/*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.beans;
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.
Author: Philip Milne See Also: - XMLEncoder
Since: 1.4
/**
* 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
* <code>readObject</code> and <code>writeObject</code>
* methods used by the <code>ObjectOutputStream</code>, streams like
* the <code>XMLEncoder</code> 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.
* <p>
* In addition to using a delegation model, this persistence
* scheme differs from traditional serialization schemes
* in requiring an analog of the <code>writeObject</code>
* method without a corresponding <code>readObject</code>
* method. The <code>writeObject</code> analog encodes each
* instance in terms of its public API and there is no need to
* define a <code>readObject</code> 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 <code>writeObject</code>
* and <code>readObject</code> 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.
* <p>
* A persistence delegate, may take control of all
* aspects of the persistence of an object including:
* <ul>
* <li>
* Deciding whether or not an instance can be mutated
* into another instance of the same class.
* <li>
* Instantiating the object, either by calling a
* public constructor or a public factory method.
* <li>
* Performing the initialization of the object.
* </ul>
* @see XMLEncoder
*
* @since 1.4
*
* @author Philip Milne
*/
public abstract class PersistenceDelegate {
The writeObject is a single entry point to the persistence
and is used by a 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.
Params: - oldInstance – The instance that will be created by this expression.
- out – The stream to which this expression will be written.
Throws: - NullPointerException – if
out is null
/**
* The <code>writeObject</code> is a single entry point to the persistence
* and is used by a <code>Encoder</code> in the traditional
* mode of delegation. Although this method is not final,
* it should not need to be subclassed under normal circumstances.
* <p>
* This implementation first checks to see if the stream
* has already encountered this object. Next the
* <code>mutatesTo</code> method is called to see if
* that candidate returned from the stream can
* be mutated into an accurate copy of <code>oldInstance</code>.
* If it can, the <code>initialize</code> method is called to
* perform the initialization. If not, the candidate is removed
* from the stream, and the <code>instantiate</code> method
* is called to create a new candidate for this object.
*
* @param oldInstance The instance that will be created by this expression.
* @param out The stream to which this expression will be written.
*
* @throws NullPointerException if {@code out} is {@code null}
*/
public void writeObject(Object oldInstance, Encoder out) {
Object newInstance = out.get(oldInstance);
if (!mutatesTo(oldInstance, newInstance)) {
out.remove(oldInstance);
out.writeExpression(instantiate(oldInstance, out));
}
else {
initialize(oldInstance.getClass(), oldInstance, newInstance, out);
}
}
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.
Params: - oldInstance – The instance to be copied.
- newInstance – The instance that is to be modified.
Returns: True if an equivalent copy of newInstance may be
created by applying a series of mutations to oldInstance.
/**
* Returns true if an <em>equivalent</em> copy of <code>oldInstance</code> may be
* created by applying a series of statements to <code>newInstance</code>.
* In the specification of this method, we mean by equivalent that the modified instance
* is indistinguishable from <code>oldInstance</code> in the behavior
* of the relevant methods in its public API. [Note: we use the
* phrase <em>relevant</em> methods rather than <em>all</em> methods
* here only because, to be strictly correct, methods like <code>hashCode</code>
* and <code>toString</code> prevent most classes from producing truly
* indistinguishable copies of their instances].
* <p>
* The default behavior returns <code>true</code>
* if the classes of the two instances are the same.
*
* @param oldInstance The instance to be copied.
* @param newInstance The instance that is to be modified.
* @return True if an equivalent copy of <code>newInstance</code> may be
* created by applying a series of mutations to <code>oldInstance</code>.
*/
protected boolean mutatesTo(Object oldInstance, Object newInstance) {
return (newInstance != null && oldInstance != null &&
oldInstance.getClass() == newInstance.getClass());
}
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.
Params: - oldInstance – The instance that will be created by this expression.
- out – The stream to which this expression will be written.
Throws: - NullPointerException – if
out is null
Returns: An expression whose value is oldInstance.
/**
* Returns an expression whose value is <code>oldInstance</code>.
* This method is used to characterize the constructor
* or factory method that should be used to create the given object.
* For example, the <code>instantiate</code> method of the persistence
* delegate for the <code>Field</code> class could be defined as follows:
* <pre>
* Field f = (Field)oldInstance;
* return new Expression(f, f.getDeclaringClass(), "getField", new Object[]{f.getName()});
* </pre>
* Note that we declare the value of the returned expression so that
* the value of the expression (as returned by <code>getValue</code>)
* will be identical to <code>oldInstance</code>.
*
* @param oldInstance The instance that will be created by this expression.
* @param out The stream to which this expression will be written.
* @return An expression whose value is <code>oldInstance</code>.
*
* @throws NullPointerException if {@code out} is {@code null}
*/
protected abstract Expression instantiate(Object oldInstance, 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.
Params: - type – the type of the instances
- oldInstance – The instance to be copied.
- newInstance – The instance that is to be modified.
- out – The stream to which any initialization statements should be written.
Throws: - NullPointerException – if
out is null
/**
* Produce a series of statements with side effects on <code>newInstance</code>
* so that the new instance becomes <em>equivalent</em> to <code>oldInstance</code>.
* In the specification of this method, we mean by equivalent that, after the method
* returns, the modified instance is indistinguishable from
* <code>newInstance</code> in the behavior of all methods in its
* public API.
* <p>
* The implementation typically achieves this goal by producing a series of
* "what happened" statements involving the <code>oldInstance</code>
* and its publicly available state. These statements are sent
* to the output stream using its <code>writeExpression</code>
* 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 <code>oldInstance</code> are returned
* as references to the <code>newInstance</code> 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.
* <p>
* The default implementation, calls the <code>initialize</code>
* method of the type's superclass.
*
* @param type the type of the instances
* @param oldInstance The instance to be copied.
* @param newInstance The instance that is to be modified.
* @param out The stream to which any initialization statements should be written.
*
* @throws NullPointerException if {@code out} is {@code null}
*/
protected void initialize(Class<?> type,
Object oldInstance, Object newInstance,
Encoder out)
{
Class superType = type.getSuperclass();
PersistenceDelegate info = out.getPersistenceDelegate(superType);
info.initialize(superType, oldInstance, newInstance, out);
}
}