/*

 * Copyright (c) 2000, 2010, 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

 * <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 <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 <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 <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 <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 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)

    {

        PersistenceDelegate info = out.getPersistenceDelegate(superType);

        info.initialize(superType, oldInstance, newInstance, out);

    }

}