2362N/A * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The PersistenceDelegate class takes the responsibility 0N/A * for expressing the state of an instance of a given class 0N/A * in terms of the methods in the class's public API. Instead 0N/A * of associating the responsibility of persistence with 0N/A * the class itself as is done, for example, by the 0N/A * <code>readObject</code> and <code>writeObject</code> 0N/A * methods used by the <code>ObjectOutputStream</code>, streams like 0N/A * the <code>XMLEncoder</code> which 0N/A * use this delegation model can have their behavior controlled 0N/A * independently of the classes themselves. Normally, the class 0N/A * is the best place to put such information and conventions 0N/A * can easily be expressed in this delegation scheme to do just that. 0N/A * Sometimes however, it is the case that a minor problem 0N/A * in a single class prevents an entire object graph from 0N/A * being written and this can leave the application 0N/A * developer with no recourse but to attempt to shadow 0N/A * the problematic classes locally or use alternative 0N/A * persistence techniques. In situations like these, the 0N/A * delegation model gives a relatively clean mechanism for 0N/A * the application developer to intervene in all parts of the 0N/A * serialization process without requiring that modifications 0N/A * be made to the implementation of classes which are not part 0N/A * of the application itself. 0N/A * In addition to using a delegation model, this persistence 0N/A * scheme differs from traditional serialization schemes 0N/A * in requiring an analog of the <code>writeObject</code> 0N/A * method without a corresponding <code>readObject</code> 0N/A * method. The <code>writeObject</code> analog encodes each 0N/A * instance in terms of its public API and there is no need to 0N/A * define a <code>readObject</code> analog 0N/A * since the procedure for reading the serialized form 0N/A * is defined by the semantics of method invocation as laid 0N/A * out in the Java Language Specification. 0N/A * Breaking the dependency between <code>writeObject</code> 0N/A * and <code>readObject</code> implementations, which may 0N/A * change from version to version, is the key factor 0N/A * in making the archives produced by this technique immune 0N/A * to changes in the private implementations of the classes 0N/A * to which they refer. 0N/A * A persistence delegate, may take control of all 0N/A * aspects of the persistence of an object including: 0N/A * Deciding whether or not an instance can be mutated 0N/A * into another instance of the same class. 0N/A * Instantiating the object, either by calling a 0N/A * public constructor or a public factory method. 0N/A * Performing the initialization of the object. 0N/A * @author Philip Milne 0N/A * The <code>writeObject</code> is a single entry point to the persistence 0N/A * and is used by a <code>Encoder</code> in the traditional 0N/A * mode of delegation. Although this method is not final, 0N/A * it should not need to be subclassed under normal circumstances. 0N/A * This implementation first checks to see if the stream 0N/A * has already encountered this object. Next the 0N/A * <code>mutatesTo</code> method is called to see if 0N/A * that candidate returned from the stream can 0N/A * be mutated into an accurate copy of <code>oldInstance</code>. 0N/A * If it can, the <code>initialize</code> method is called to 0N/A * perform the initialization. If not, the candidate is removed 0N/A * from the stream, and the <code>instantiate</code> method 0N/A * is called to create a new candidate for this object. 0N/A * @param oldInstance The instance that will be created by this expression. 0N/A * @param out The stream to which this expression will be written. 2147N/A * @throws NullPointerException if {@code out} is {@code null} 0N/A * Returns true if an <em>equivalent</em> copy of <code>oldInstance</code> may be 0N/A * created by applying a series of statements to <code>newInstance</code>. 0N/A * In the specification of this method, we mean by equivalent that the modified instance 0N/A * is indistinguishable from <code>oldInstance</code> in the behavior 0N/A * of the relevant methods in its public API. [Note: we use the 0N/A * phrase <em>relevant</em> methods rather than <em>all</em> methods 0N/A * here only because, to be strictly correct, methods like <code>hashCode</code> 0N/A * and <code>toString</code> prevent most classes from producing truly 0N/A * indistinguishable copies of their instances]. 0N/A * The default behavior returns <code>true</code> 0N/A * if the classes of the two instances are the same. 0N/A * @param oldInstance The instance to be copied. 0N/A * @param newInstance The instance that is to be modified. 0N/A * @return True if an equivalent copy of <code>newInstance</code> may be 0N/A * created by applying a series of mutations to <code>oldInstance</code>. 0N/A * Returns an expression whose value is <code>oldInstance</code>. 0N/A * This method is used to characterize the constructor 0N/A * or factory method that should be used to create the given object. 0N/A * For example, the <code>instantiate</code> method of the persistence 0N/A * delegate for the <code>Field</code> class could be defined as follows: 0N/A * Field f = (Field)oldInstance; 0N/A * return new Expression(f, f.getDeclaringClass(), "getField", new Object[]{f.getName()}); 0N/A * Note that we declare the value of the returned expression so that 0N/A * the value of the expression (as returned by <code>getValue</code>) 0N/A * will be identical to <code>oldInstance</code>. 0N/A * @param oldInstance The instance that will be created by this expression. 0N/A * @param out The stream to which this expression will be written. 0N/A * @return An expression whose value is <code>oldInstance</code>. 2147N/A * @throws NullPointerException if {@code out} is {@code null} 0N/A * Produce a series of statements with side effects on <code>newInstance</code> 0N/A * so that the new instance becomes <em>equivalent</em> to <code>oldInstance</code>. 0N/A * In the specification of this method, we mean by equivalent that, after the method 0N/A * returns, the modified instance is indistinguishable from 0N/A * <code>newInstance</code> in the behavior of all methods in its 0N/A * The implementation typically achieves this goal by producing a series of 0N/A * "what happened" statements involving the <code>oldInstance</code> 0N/A * and its publicly available state. These statements are sent 0N/A * to the output stream using its <code>writeExpression</code> 0N/A * method which returns an expression involving elements in 0N/A * a cloned environment simulating the state of an input stream during 0N/A * reading. Each statement returned will have had all instances 0N/A * the old environment replaced with objects which exist in the new 0N/A * one. In particular, references to the target of these statements, 0N/A * which start out as references to <code>oldInstance</code> are returned 0N/A * as references to the <code>newInstance</code> instead. 0N/A * Executing these statements effects an incremental 0N/A * alignment of the state of the two objects as a series of 0N/A * modifications to the objects in the new environment. 0N/A * By the time the initialize method returns it should be impossible 0N/A * to tell the two instances apart by using their public APIs. 0N/A * Most importantly, the sequence of steps that were used to make 0N/A * these objects appear equivalent will have been recorded 0N/A * by the output stream and will form the actual output when 0N/A * the stream is flushed. 0N/A * The default implementation, calls the <code>initialize</code> 0N/A * method of the type's superclass. 0N/A * @param oldInstance The instance to be copied. 0N/A * @param newInstance The instance that is to be modified. 0N/A * @param out The stream to which any initialization statements should be written. 2147N/A * @throws NullPointerException if {@code out} is {@code null}