Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Understanding Java Serialization

Learn how Java serialization works, how to control it with serialVersionUID and transient fields, and when to choose native serialization over alternatives.

~6 min readJava
#Java Serialization#Serializable#serialVersionUID#Deserialization
A Java object being converted into a byte stream and then reconstructed, illustrating the serialization and deserialization process.

Java serialization converts an object's state into a byte stream that can be written to disk, sent over a network, or stored in a database. The reverse process, deserialization, reconstructs the object from that byte stream. The mechanism is built into the JDK and requires no external libraries, but it carries assumptions about class versioning, security, and performance that you need to understand before relying on it in production.

How Java Serialization Works

For an object to be serialized, its class must implement the java.io.Serializable marker interface. The interface declares no methods; it simply signals to the JVM that the class is eligible for serialization. When you pass an object to ObjectOutputStream.writeObject(), the JVM inspects the object's class and serializes its non-transient, non-static fields. It also records metadata about the class, including the class name and its serialVersionUID (declared explicitly or computed automatically).

java
import java.io.*; public class User implements Serializable { private String name; private int age; // constructors, getters, setters }

Deserialization is the mirror operation. ObjectInputStream.readObject() reads the byte stream, reconstructs the object, and populates its fields. The Java serialization mechanism does not call the serialized class's constructor during deserialization. Instead, it initializes the object through the no-arg constructor of the first non-serializable superclass and restores serializable fields directly from the stream. Constructor-based validation logic on the serialized class is therefore bypassed.

The default serialization mechanism writes all fields except those marked transient or static. static fields belong to the class, not the instance, so they are not serialized. transient fields are explicitly excluded from the serialized representation.

Why serialVersionUID Matters

Every serializable class has a serialVersionUID. If you do not declare it explicitly, the JVM computes one from the class structure using a deterministic algorithm. This computed value can change when the class's fields, methods, or inheritance hierarchy change. When deserializing, the JVM compares the serialVersionUID in the byte stream with the one in the loaded class. If they differ, it throws an InvalidClassException.

java
public class User implements Serializable { private static final long serialVersionUID = 1L; private String name; private int age; }

Declaring an explicit serialVersionUID gives you control over compatibility. If you keep it the same while adding new fields, deserialization of old streams will succeed, and the new fields will be set to their default values (null for objects, 0 for primitives). Removing or renaming a field does not necessarily cause deserialization to fail; the old value may be discarded, and a renamed field may keep its default value unless you map it in custom serialization. Changing a field's type in an incompatible way, however, can cause an InvalidClassException. The rule is: change the serialVersionUID only when you intentionally break compatibility, and keep it constant when you want to support older serialized data.

Excluding Fields with transient

Marking a field transient prevents it from being serialized. This is useful for fields that are derived from other data, contain sensitive information, or reference objects that are not themselves serializable. For example, a password field or a database connection should not be written to disk.

java
public class Session implements Serializable { private static final long serialVersionUID = 1L; private String username; private transient String password; private transient Connection dbConnection; }

When deserializing, transient fields are left at their default values. You must reinitialize them after deserialization, often in a custom readObject method or by using a factory method. Static fields are also never serialized; they keep whatever value is set on the loaded class.

Custom Serialization with writeObject and readObject

Sometimes the default serialization behavior is not enough. You may need to encrypt sensitive fields, validate data on deserialization, or handle version changes gracefully. You can implement private methods writeObject(ObjectOutputStream out) and readObject(ObjectInputStream in) in your class. The JVM invokes these methods instead of the default mechanism.

The next example uses a Session object; encrypt and decrypt are stand-ins for your own cryptography logic.

java
private void writeObject(ObjectOutputStream out) throws IOException { out.defaultWriteObject(); // Custom logic, e.g., encrypt before writing. out.writeObject(encrypt(password)); } private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); // Custom logic, e.g., decrypt and validate after reading. password = decrypt((String) in.readObject()); if (username == null || username.isEmpty()) { throw new InvalidObjectException("Username cannot be blank"); } }

defaultWriteObject() and defaultReadObject() handle the normal fields. You then write or read additional data manually. This pattern is also used to evolve a class: you can read old data, apply defaults for missing fields, and then write new data in the new format.

Security Concerns with Native Java Serialization

Native Java serialization has a well-known security weakness: deserializing untrusted data can lead to remote code execution. The readObject() method can trigger arbitrary code if the stream contains a crafted object that exploits a gadget chain in the classpath. Even without a full exploit, deserialization can cause denial-of-service via excessive memory allocation or CPU usage.

On Java 9 and later, the JDK provides a filter mechanism, ObjectInputFilter, that lets you restrict which classes can be deserialized. You can set a global filter or a per-stream filter. For example, the following filter allows classes from java.base and rejects everything else.

java
ObjectInputFilter filter = ObjectInputFilter.Config.createFilter("java.base/*;!*"); ObjectInputStream in = new ObjectInputStream(inputStream); in.setObjectInputFilter(filter);

The filter pattern syntax is documented in the JDK. However, filtering is a mitigation, not a cure. The safest approach is to avoid native serialization for untrusted input altogether. Consider using structured formats like JSON, Protocol Buffers, or Avro, which do not automatically instantiate arbitrary types.

Performance and Operational Considerations

Native Java serialization is convenient but not efficient. The byte stream includes class metadata, field names, and type information, making it larger than a compact binary format. The serialization process also uses reflection, which adds CPU overhead. For high-throughput systems, this can become a bottleneck.

Another operational issue is compatibility across versions. If you change a class's fields, you must manage serialVersionUID and potentially custom serialization to avoid breaking existing data. This becomes harder as your application evolves. Many teams prefer a schema-based format like Protocol Buffers, which has explicit versioning rules and generates compact, language-neutral data.

That said, native serialization is still useful in certain scenarios. If you are writing a short-lived object to a local cache, or if you need a simple built-in way to deep-copy an object within the same JVM and performance is not the main concern, the simplicity of Serializable may outweigh the drawbacks. For any data that crosses a trust boundary, choose a safer format.

Choosing Between Native Serialization and Alternatives

The decision comes down to your requirements for security, performance, and maintainability. Use native Java serialization when:

  • You are working entirely within a trusted JVM environment.
  • The object graph is complex and would be tedious to map to a schema.
  • You need a simple way to deep-copy an object and performance is not critical.

Use a structured format like JSON or Protocol Buffers when:

  • Data is sent over a network or stored long-term.
  • The receiving system may be written in a different language.
  • You need schema evolution with explicit compatibility rules (a schema-based format such as Protocol Buffers or Avro is a stronger fit than plain JSON).
  • You cannot trust the source of the data.

JSON is human-readable and widely supported, but it does not preserve type information by default. Protocol Buffers and Avro are binary formats with strict schemas, often making them faster and more compact than native serialization. They also avoid the security risks of deserializing arbitrary Java classes.

If you must use native serialization, apply an ObjectInputFilter (available on Java 9 and later), validate all fields after deserialization, and keep serialVersionUID explicit. For new projects, prefer a modern serialization framework that gives you control over the data format and its security properties.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.