All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.openmdx.dalvik.uses.java.beans.PersistenceDelegate Maven / Gradle / Ivy

There is a newer version: 2.18.10
Show newest version
/*
 * Copyright (c) 2000, 2006, 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 org.openmdx.dalvik.uses.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. *
* @see XMLEncoder * *

* openMDX/Dalvik Notice (January 2013):
* THIS CODE HAS BEEN MODIFIED AND ITS NAMESPACE HAS BEEN PREFIXED WITH * org.openmdx.dalvik.uses. *

* @since openMDX 2.12 * @author openMDX Team * * @author Philip Milne */ @SuppressWarnings({"rawtypes"}) 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. */ 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. */ 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 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. */ 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); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy