Package com.persistit.ref

Provides an interface and abstract superclasses for classes used to break object reference graphs for serialization.

See: Description

Interface Summary

Interface	Description
PersistitReference	Interface for reference classes used to isolate object references during serialization.

Class Summary

Class	Description
AbstractReference	An abstract superclass for implementations of PersistitReference.
AbstractWeakReference	An abstract superclass for implementations of PersistitReference that implement weak reference semantics.

Package com.persistit.ref Description

Provides an interface and abstract superclasses for classes used to break object reference graphs for serialization.

The general problem this interface is intended to solve is to reduce or control the scope of serialization of an object. In a typical application some object A may need to refer to some other object B that has a large graph of connected objects. Using Java's standard serialization mechanism, serializing A also serializes B and all the objects it references. This set may be very large, and further, it may be semantically incorrect to serialize the state of B with A because the state of B may change independently of A, so in many cases B's state should not be serialized concurrently with A's state.

For example, consider a PurchaseOrder class that identifies a Supplier in one of its fields. Assume further that the Supplier refers to a large, mostly static, catalog of Products. A naive implementation might be written as follows:

class PurchaseOrder
{
        ...
        private Date date;
        private Supplier supplier;
        ...
        
        public Supplier getSupplier()
        {
                return supplier;
        }
        
        public void setSuppler(Object suppler)
        {
                this.supplier = supplier;
        }
}

In this implementation, standard Java serialization would serialize not only the state of a PurchaseOrder, but also the entire state of the referenced Supplier.

To break this connection, the PurchaseOrder class could be rewritten as follows:

class PurchaseOrder
{
        ...
        private Date date;
        private SupplierReference supplier;
        ...
        
        public Supplier getSupplier()
        {
                return (Supplier)supplier.get();
        }
        
        public void setSuppler(Object supplier)
        {
                Object id = <code to derive the supplier's permanent id>;
                this.supplier = new SupplierReference(id, supplier);
        }
}

class SupplierReference extends AbstractReference
{
        public Object lookup(object supplierId)
        {
                Supplier supplier = <code to retrieve the Supplier given its identity>;
                return supplier;
        }
}

Two abstract implementation classes are provided: AbstractReference and AbstractWeakReference. For both of these the AbstractReference.lookup(java.lang.Object) method must be implemented to peform the application-specific actions necessary to recover and instantiate a persistent object given its persistent identifier. The difference between the two classes is that once the referent object has been instantiated, the AbstractReference implementation holds a strong reference to it, while the AbstractWeakReference holds a weak reference. A weak reference allows the garbage collector to remove and reclaim the memory occupied by the referent object. A subsequent call to the AbstractWeakReference's get method simply instantiates a new copy of the referent object.