ajava.beans.PersistenceDelegate Maven / Gradle / Ivy
Show all versions of a-javabeans8 Show documentation
/*
* 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 ajava.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.
*
* @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.
*
* @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.
*
* @param oldInstance The instance to be copied.
* @param newInstance The instance that is to be modified.
* @return 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) {
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.
*
* @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 oldInstance.
*
* @throws NullPointerException if {@code out} is {@code null}
* and this value is used in the method
*/
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.
*
* @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);
}
}