OpenJDK 27 · java.beans.PersistenceDelegate · APIdia, the JavaDoc alternative

The PersistenceDelegate class takes the responsibility for expressing the state of an instance of a given class in terms of the methods in the class's public API. Instead of associating the responsibility of persistence with the class itself as is done, for example, by the readObject and writeObject methods used by the ObjectOutputStream, streams like the XMLEncoder which use this delegation model can have their behavior controlled independently of the classes themselves. Normally, the class is the best place to put such information and conventions can easily be expressed in this delegation scheme to do just that. Sometimes however, it is the case that a minor problem in a single class prevents an entire object graph from being written and this can leave the application developer with no recourse but to attempt to shadow the problematic classes locally or use alternative persistence techniques. In situations like these, the delegation model gives a relatively clean mechanism for the application developer to intervene in all parts of the serialization process without requiring that modifications be made to the implementation of classes which are not part of the application itself.

In addition to using a delegation model, this persistence scheme differs from traditional serialization schemes in requiring an analog of the writeObject method without a corresponding readObject method. The writeObject analog encodes each instance in terms of its public API and there is no need to define a readObject analog since the procedure for reading the serialized form is defined by the semantics of method invocation as laid out in the Java Language Specification. Breaking the dependency between writeObject and readObject implementations, which may change from version to version, is the key factor in making the archives produced by this technique immune to changes in the private implementations of the classes to which they refer.

A persistence delegate, may take control of all aspects of the persistence of an object including:

Deciding whether or not an instance can be mutated into another instance of the same class.
Instantiating the object, either by calling a public constructor or a public factory method.
Performing the initialization of the object.

Constructor Summary

Access	Constructor and Description
protected	PersistenceDelegate() Constructs a `PersistenceDelegate`.

Method Summary

Modifier and Type	Method and Description
protected void	initialize(Class<?> the type of the instances type, Object The instance to be copied. oldInstance, Object The instance that is to be modified. newInstance, Encoder The stream to which any initialization statements should be written. out) Produce a series of statements with side effects on `newInstance` so that the new instance becomes equivalent to `oldInstance`.
protected abstract Expression	Returns: An expression whose value is `oldInstance`. instantiate(Object The instance that will be created by this expression. oldInstance, Encoder The stream to which this expression will be written. out) Returns an expression whose value is `oldInstance`.
protected boolean	Returns: True if an equivalent copy of `newInstance` may be created by applying a series of mutations to `oldInstance`. mutatesTo(Object The instance to be copied. oldInstance, Object The instance that is to be modified. newInstance) Returns true if an equivalent copy of `oldInstance` may be created by applying a series of statements to `newInstance`.
public void	writeObject(Object The instance that will be created by this expression. oldInstance, Encoder The stream to which this expression will be written. out) The `writeObject` is a single entry point to the persistence and is used by an `Encoder` in the traditional mode of delegation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

PersistenceDelegate	back to summary
protected PersistenceDelegate() Constructs a `PersistenceDelegate`.

Method Detail

initialize back to summary

initialize	back to summary
protected void initialize(Class<?> type, Object oldInstance, Object newInstance, Encoder out) Produce a series of statements with side effects on `newInstance` so that the new instance becomes equivalent to `oldInstance`. In the specification of this method, we mean by equivalent that, after the method returns, the modified instance is indistinguishable from `newInstance` in the behavior of all methods in its public API. The implementation typically achieves this goal by producing a series of "what happened" statements involving the `oldInstance` and its publicly available state. These statements are sent to the output stream using its `writeExpression` method which returns an expression involving elements in a cloned environment simulating the state of an input stream during reading. Each statement returned will have had all instances the old environment replaced with objects which exist in the new one. In particular, references to the target of these statements, which start out as references to `oldInstance` are returned as references to the `newInstance` instead. Executing these statements effects an incremental alignment of the state of the two objects as a series of modifications to the objects in the new environment. By the time the initialize method returns it should be impossible to tell the two instances apart by using their public APIs. Most importantly, the sequence of steps that were used to make these objects appear equivalent will have been recorded by the output stream and will form the actual output when the stream is flushed. The default implementation, calls the `initialize` method of the type's superclass. Parameters type:Class<?> the type of the instances oldInstance:Object The instance to be copied. newInstance:Object The instance that is to be modified. out:Encoder The stream to which any initialization statements should be written. Exceptions NullPointerException: if `out` is `null`

protected void initialize(Class<?> type, Object oldInstance, Object newInstance, Encoder out)

Produce a series of statements with side effects on newInstance so that the new instance becomes equivalent to oldInstance. In the specification of this method, we mean by equivalent that, after the method returns, the modified instance is indistinguishable from newInstance in the behavior of all methods in its public API.

The implementation typically achieves this goal by producing a series of "what happened" statements involving the oldInstance and its publicly available state. These statements are sent to the output stream using its writeExpression method which returns an expression involving elements in a cloned environment simulating the state of an input stream during reading. Each statement returned will have had all instances the old environment replaced with objects which exist in the new one. In particular, references to the target of these statements, which start out as references to oldInstance are returned as references to the newInstance instead. Executing these statements effects an incremental alignment of the state of the two objects as a series of modifications to the objects in the new environment. By the time the initialize method returns it should be impossible to tell the two instances apart by using their public APIs. Most importantly, the sequence of steps that were used to make these objects appear equivalent will have been recorded by the output stream and will form the actual output when the stream is flushed.

The default implementation, calls the initialize method of the type's superclass.

Parameters

type:Class<?>: the type of the instances
oldInstance:Object: The instance to be copied.
newInstance:Object: The instance that is to be modified.
out:Encoder: The stream to which any initialization statements should be written.

Exceptions

NullPointerException:: if out is null

instantiate back to summary

instantiate	back to summary
protected abstract Expression instantiate(Object oldInstance, Encoder out) Returns an expression whose value is `oldInstance`. This method is used to characterize the constructor or factory method that should be used to create the given object. For example, the `instantiate` method of the persistence delegate for the `Field` class could be defined as follows: Field f = (Field)oldInstance; return new Expression(f, f.getDeclaringClass(), "getField", new Object[]{f.getName()}); Note that we declare the value of the returned expression so that the value of the expression (as returned by `getValue`) will be identical to `oldInstance`. Parameters oldInstance:Object The instance that will be created by this expression. out:Encoder The stream to which this expression will be written. Returns:Expression An expression whose value is `oldInstance`. Exceptions NullPointerException: if `out` is `null` and this value is used in the method

protected abstract Expression instantiate(Object oldInstance, Encoder out)

Returns an expression whose value is oldInstance. This method is used to characterize the constructor or factory method that should be used to create the given object. For example, the instantiate method of the persistence delegate for the Field class could be defined as follows:

Field f = (Field)oldInstance;
return new Expression(f, f.getDeclaringClass(), "getField", new Object[]{f.getName()});

Note that we declare the value of the returned expression so that the value of the expression (as returned by getValue) will be identical to oldInstance.

Parameters

oldInstance:Object: The instance that will be created by this expression.
out:Encoder: The stream to which this expression will be written.

Returns:Expression

An expression whose value is oldInstance.

Exceptions

NullPointerException:: if out is null and this value is used in the method

mutatesTo back to summary

mutatesTo	back to summary
protected boolean mutatesTo(Object oldInstance, Object newInstance) Returns true if an equivalent copy of `oldInstance` may be created by applying a series of statements to `newInstance`. In the specification of this method, we mean by equivalent that the modified instance is indistinguishable from `oldInstance` in the behavior of the relevant methods in its public API. [Note: we use the phrase relevant methods rather than all methods here only because, to be strictly correct, methods like `hashCode` and `toString` prevent most classes from producing truly indistinguishable copies of their instances]. The default behavior returns `true` if the classes of the two instances are the same. Parameters oldInstance:Object The instance to be copied. newInstance:Object The instance that is to be modified. Returns:boolean True if an equivalent copy of `newInstance` may be created by applying a series of mutations to `oldInstance`.

protected boolean mutatesTo(Object oldInstance, Object newInstance)

Returns true if an equivalent copy of oldInstance may be created by applying a series of statements to newInstance. In the specification of this method, we mean by equivalent that the modified instance is indistinguishable from oldInstance in the behavior of the relevant methods in its public API. [Note: we use the phrase relevant methods rather than all methods here only because, to be strictly correct, methods like hashCode and toString prevent most classes from producing truly indistinguishable copies of their instances].

The default behavior returns true if the classes of the two instances are the same.

Parameters

oldInstance:Object: The instance to be copied.
newInstance:Object: The instance that is to be modified.

Returns:boolean

True if an equivalent copy of newInstance may be created by applying a series of mutations to oldInstance.

writeObject back to summary

writeObject	back to summary
public void writeObject(Object oldInstance, Encoder out) The `writeObject` is a single entry point to the persistence and is used by an `Encoder` in the traditional mode of delegation. Although this method is not final, it should not need to be subclassed under normal circumstances. This implementation first checks to see if the stream has already encountered this object. Next the `mutatesTo` method is called to see if that candidate returned from the stream can be mutated into an accurate copy of `oldInstance`. If it can, the `initialize` method is called to perform the initialization. If not, the candidate is removed from the stream, and the `instantiate` method is called to create a new candidate for this object. Parameters oldInstance:Object The instance that will be created by this expression. out:Encoder The stream to which this expression will be written. Exceptions NullPointerException: if `out` is `null`

public void writeObject(Object oldInstance, Encoder out)

The writeObject is a single entry point to the persistence and is used by an Encoder in the traditional mode of delegation. Although this method is not final, it should not need to be subclassed under normal circumstances.

This implementation first checks to see if the stream has already encountered this object. Next the mutatesTo method is called to see if that candidate returned from the stream can be mutated into an accurate copy of oldInstance. If it can, the initialize method is called to perform the initialization. If not, the candidate is removed from the stream, and the instantiate method is called to create a new candidate for this object.

Parameters

oldInstance:Object: The instance that will be created by this expression.
out:Encoder: The stream to which this expression will be written.

Exceptions

NullPointerException:: if out is null

public abstract Class PersistenceDelegate

Constructor Summary

Method Summary

Constructor Detail

Method Detail