< prev index next >

src/java.desktop/share/classes/java/beans/PersistenceDelegate.java

Print this page

        

*** 28,40 **** * 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 --- 28,40 ---- * 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} and {@code writeObject} ! * methods used by the {@code ObjectOutputStream}, streams like ! * the {@code 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
*** 49,68 **** * 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> --- 49,68 ---- * 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} ! * method without a corresponding {@code readObject} ! * method. The {@code writeObject} analog encodes each * instance in terms of its public API and there is no need to ! * define a {@code 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 {@code writeObject} ! * and {@code 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. * <p>
*** 86,108 **** */ 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. * --- 86,108 ---- */ public abstract class PersistenceDelegate { /** ! * The {@code writeObject} is a single entry point to the persistence ! * and is used by a {@code Encoder} 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} method is called to see if * that candidate returned from the stream can ! * be mutated into an accurate copy of {@code oldInstance}. ! * If it can, the {@code initialize} method is called to * perform the initialization. If not, the candidate is removed ! * from the stream, and the {@code 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. *
*** 118,203 **** 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} * 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 <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. --- 118,203 ---- initialize(oldInstance.getClass(), oldInstance, newInstance, out); } } /** ! * Returns true if an <em>equivalent</em> copy of {@code oldInstance} may be ! * created by applying a series of statements to {@code newInstance}. * In the specification of this method, we mean by equivalent that the modified instance ! * is indistinguishable from {@code oldInstance} 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} ! * and {@code toString} prevent most classes from producing truly * indistinguishable copies of their instances]. * <p> ! * The default behavior returns {@code 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 {@code newInstance} may be ! * created by applying a series of mutations to {@code oldInstance}. */ protected boolean mutatesTo(Object oldInstance, Object newInstance) { return (newInstance != null && oldInstance != null && oldInstance.getClass() == newInstance.getClass()); } /** ! * Returns an expression whose value is {@code oldInstance}. * 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} method of the persistence ! * delegate for the {@code Field} 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}) ! * will be identical to {@code 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 {@code 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 {@code newInstance} ! * so that the new instance becomes <em>equivalent</em> to {@code oldInstance}. * In the specification of this method, we mean by equivalent that, after the method * returns, the modified instance is indistinguishable from ! * {@code newInstance} 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} * and its publicly available state. These statements are sent ! * to the output stream using its {@code 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 {@code oldInstance} are returned ! * as references to the {@code 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. * <p> ! * The default implementation, calls the {@code 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.
< prev index next >