org.opendaylight.persistence.util.test

Class SerializabilityTester

java.lang.Object

org.opendaylight.persistence.util.test.SerializabilityTester

public final class SerializabilityTester
extends Object

Tester to test objects which implement Serializable.

Text taken from Effective Java by Joshua Bloch

The object Serialization API provides a framework for encoding (Serializing) objects as byte streams and reconstructing (Deserializing) objects from their byte-stream encodings. Once an object has been serialized, its encoding can be transmitted from one running virtual machine to another or stored on disk for later deserialization.

• Implementing the Serializable interface is not a decision to be undertaken lightly. It offers real benefits. It is essential if a class is to participate in a framework that relies on serialization for object transmission or persistence.
• A major cost of implementing Serializable is that it decreases the flexibility to change a class's implementation once it has been released.
• When a class implements Serializable, its byte-stream encoding becomes part of its exported API.
• If you don't make the effort to design a custom serialized form, but merely accept the default, the serialized form will forever be tied to the class's original internal representation. The class's private and package private instance fields become part of its exported API, and the practice of minimizing access to fields loses its effectiveness as a tool for information hiding.
• Even a well-designed serialized form places constraints on the evolution of a class; an ill-designed serialized form can be crippling.
• Deserialization is a "hidden constructor" with all of the same issues as other constructors. It must be ensured that all of the in variants established by the constructors are met.
• When a serializable class is revised, it is important to check that it is possible to serialize an instance of the new release and deserialize it in old releases, and vice versa. In addition to binary compatibility, semantic compatibility must be tested. Ensure both that the serialization-deserialization process succeeds and that it results in faithful replica of the original object.
• Classes designed for inheritance should rarely implement Serializable, and interfaces should rarely extend it. If a class or interface exists primarily to participate in a framework that requires all participants to implement Serializable, then it makes perfect sense for the class or interface to implement or extend Serializable.
• If the class has invariants that would be violated if its instance fields were initialized to their default values consider adding the following method:

   private void readObjectNoData() throws InvalidObjectException {
       throw new InvalidObjectException("Stream data required");
   }
   

• However, if a class that is designed for inheritance is not Serializable, it may be impossible to write a Serializable subclass. Specifically, it will be impossible if the superclass does not provide an accessible parameterless constructor.
• Inner classes should not implement serializable unless they are static. Non-static inner classes use compiled-generated synthetic fields to store references to enclosing instances and to store values of local variables from enclosing scopes.
• Consider using a custom serialized form. Do not accept the default serialized form without first considering whether it is appropriate. Generally speaking, the default serialized form should be accepted only if it is largely identical to the encoding that would be chosen for a custom serialization. The default serialized form is likely to be appropriate if an object's physical representation is identical to its logical content.
• Every serializable class has a unique identification number associated with it. If this number is not specified by declaring a static final long field named serialVersionUID, the system automatically generates it at runtime by applying a complex procedure to the class. The automatically generated value is affected by the class'name, the names of the interfaces it implements, and all of its public and protected members. If any of these things is changed any way, for example, by adding a trivial convenience method, the automatically generates serial version UID changes. If a serial version is not declared, compatibility will be broken, resulting in an InvalidClassException at runtime. This number must be changed when backwards compatibility is broken.
• Even if it is decided the default serialized form is a appropriate, it is recommended to to provide a readObject method to ensure invariants and security.

   private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
       stream.defaultReadObject();
       // Ensure invariants and security
       // ...
   }
   
   

• If the default serialized form is used, transient fields will be initialized to the default value when an instance is deserialized: null for reference fields, zero for numeric primitive fields, and false for boolean fields. If these values are unaceptable for any transient fields, provide a readObject method (like the one above) that restore transient fields to acceptable values. Alternatively, these fields can be lazily initialized the first time they are used.
• Whether or not the default serialized form is used, synchronization must be imposed on object serialization if it is imposed on any other method that reads the entire state of the object.

   // synchronized method if other methods use synchronization to read the entire state of the object
   private synchronized void writeObject(ObjectOutputStream stream) throws IOException {
       stream.defaultWriteObject();
   }
   
   

• Regardless of what serialized form is used, declare an explicit serial version UID in every Serializable class. This eliminates the serial version UID as potential source if incompatibility. There is also a small performance benefit: If no serial version UID is provided, an expensive computation is required to generate one at runtime.
• readObject method is effectively another public constructor, and it demands all of the same care as any other constructor. Check its arguments for validity, make defensive copies, etc. Loosely speaking, readObject is a constructor that takes a byte stream as its sole parameter. Throw InvalidObjectException if an invariant is broken.
• When an object is deserialized, it is critical to defensively copy any field containing an object reference that a client must not possess. Don't use the writeUnshared and readUnshared methods from ObjectOutputStream and ObjectInputStream; they are typically faster that defensive copying, but they don't provide the necessary safety guarantee.
• A readObject method must not invoke an overridable method, directly or indirectly. Overriding methods will run before the subclass state is deserialized.
• For instance control (Singletons), prefer enum types to readResolve. If you depend on readResolve for instance control, all instance fields with object reference types must be declared transient. Otherwise it is possible for a determined attacker to secure a reference to the deserialized object before its readResolve method runs. The use of readResolve is not obsolete. If you have to write a serializable instance-controlled (singleton) class whose instances are not known at compile time, you will not be able to represent the class as an enum type.
• The accessibility of readResolve is significant.. If it is placed in a final class it should be private. For nonfinal classes, if it is private it will not apply to any subclasses. If it is package-private, it will apply only to subclasses in the same package. If it is protected or public, it will apply to all subclasses that do not override it. If readResolve is protected or public and a subclass does not override it, deserializing a serialized subclass instance will produce a superclass instance, which is likely to case ClassCastException.
• Consider serialization proxies instead of serialized instances. Serialization proxy pattern reduces security problems and errors. See ProxiedSerializable under the test folder for an example.

Author:

Fabiel Zuniga, Nachiket Abhyankar

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SerializabilityTester.SemanticCompatibilityVerifier<T extends Serializable> Semantic compatibility verifier.

Method Summary

Methods

Modifier and Type	Method and Description
static <T extends Serializable> void	testSerialization(T serializable, SerializabilityTester.SemanticCompatibilityVerifier<T> semanticCompatibilityVerifier) Test serialization's binary and semantic compatibility.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

testSerialization

public static <T extends Serializable> void testSerialization(T serializable,
                                              SerializabilityTester.SemanticCompatibilityVerifier<T> semanticCompatibilityVerifier)

Test serialization's binary and semantic compatibility.

Type Parameters:

T - type of the serializable entity

Parameters:

serializable - serializable object

semanticCompatibilityVerifier - semantic compatibility verifier to assert that original and its replica are semantically compatible. If null is provided just binary compatibility will be tested (The only errors that will be caught via this test is situations where an non-serializable object reference with a non-null value is used - NotSerializableException). Thus it is highly recommended to pass a non-null semanticCompatibilityVerifier.