1 /*
2 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 package java.beans;
26
27 /**
28 * The PersistenceDelegate class takes the responsibility
29 * for expressing the state of an instance of a given class
30 * in terms of the methods in the class's public API. Instead
31 * of associating the responsibility of persistence with
32 * the class itself as is done, for example, by the
33 * <code>readObject</code> and <code>writeObject</code>
34 * methods used by the <code>ObjectOutputStream</code>, streams like
35 * the <code>XMLEncoder</code> which
36 * use this delegation model can have their behavior controlled
37 * independently of the classes themselves. Normally, the class
38 * is the best place to put such information and conventions
39 * can easily be expressed in this delegation scheme to do just that.
40 * Sometimes however, it is the case that a minor problem
41 * in a single class prevents an entire object graph from
42 * being written and this can leave the application
43 * developer with no recourse but to attempt to shadow
44 * the problematic classes locally or use alternative
45 * persistence techniques. In situations like these, the
46 * delegation model gives a relatively clean mechanism for
47 * the application developer to intervene in all parts of the
48 * serialization process without requiring that modifications
49 * be made to the implementation of classes which are not part
50 * of the application itself.
51 * <p>
52 * In addition to using a delegation model, this persistence
53 * scheme differs from traditional serialization schemes
54 * in requiring an analog of the <code>writeObject</code>
55 * method without a corresponding <code>readObject</code>
56 * method. The <code>writeObject</code> analog encodes each
57 * instance in terms of its public API and there is no need to
58 * define a <code>readObject</code> analog
59 * since the procedure for reading the serialized form
60 * is defined by the semantics of method invocation as laid
61 * out in the Java Language Specification.
62 * Breaking the dependency between <code>writeObject</code>
63 * and <code>readObject</code> implementations, which may
64 * change from version to version, is the key factor
65 * in making the archives produced by this technique immune
66 * to changes in the private implementations of the classes
67 * to which they refer.
68 * <p>
69 * A persistence delegate, may take control of all
70 * aspects of the persistence of an object including:
71 * <ul>
72 * <li>
73 * Deciding whether or not an instance can be mutated
74 * into another instance of the same class.
75 * <li>
76 * Instantiating the object, either by calling a
77 * public constructor or a public factory method.
78 * <li>
79 * Performing the initialization of the object.
80 * </ul>
81 * @see XMLEncoder
82 *
83 * @since 1.4
84 *
85 * @author Philip Milne
86 */
87
88 public abstract class PersistenceDelegate {
89
90 /**
91 * The <code>writeObject</code> is a single entry point to the persistence
92 * and is used by a <code>Encoder</code> in the traditional
93 * mode of delegation. Although this method is not final,
94 * it should not need to be subclassed under normal circumstances.
95 * <p>
96 * This implementation first checks to see if the stream
97 * has already encountered this object. Next the
98 * <code>mutatesTo</code> method is called to see if
99 * that candidate returned from the stream can
100 * be mutated into an accurate copy of <code>oldInstance</code>.
101 * If it can, the <code>initialize</code> method is called to
102 * perform the initialization. If not, the candidate is removed
103 * from the stream, and the <code>instantiate</code> method
104 * is called to create a new candidate for this object.
105 *
106 * @param oldInstance The instance that will be created by this expression.
107 * @param out The stream to which this expression will be written.
108 */
109 public void writeObject(Object oldInstance, Encoder out) {
110 Object newInstance = out.get(oldInstance);
111 if (!mutatesTo(oldInstance, newInstance)) {
112 out.remove(oldInstance);
113 out.writeExpression(instantiate(oldInstance, out));
114 }
115 else {
116 initialize(oldInstance.getClass(), oldInstance, newInstance, out);
117 }
118 }
119
120 /**
121 * Returns true if an <em>equivalent</em> copy of <code>oldInstance</code> may be
122 * created by applying a series of statements to <code>newInstance</code>.
123 * In the specification of this method, we mean by equivalent that the modified instance
124 * is indistinguishable from <code>oldInstance</code> in the behavior
125 * of the relevant methods in its public API. [Note: we use the
126 * phrase <em>relevant</em> methods rather than <em>all</em> methods
127 * here only because, to be strictly correct, methods like <code>hashCode</code>
128 * and <code>toString</code> prevent most classes from producing truly
129 * indistinguishable copies of their instances].
130 * <p>
131 * The default behavior returns <code>true</code>
132 * if the classes of the two instances are the same.
133 *
134 * @param oldInstance The instance to be copied.
135 * @param newInstance The instance that is to be modified.
136 * @return True if an equivalent copy of <code>newInstance</code> may be
137 * created by applying a series of mutations to <code>oldInstance</code>.
138 */
139 protected boolean mutatesTo(Object oldInstance, Object newInstance) {
140 return (newInstance != null && oldInstance != null &&
141 oldInstance.getClass() == newInstance.getClass());
142 }
143
144 /**
145 * Returns an expression whose value is <code>oldInstance</code>.
146 * This method is used to characterize the constructor
147 * or factory method that should be used to create the given object.
148 * For example, the <code>instantiate</code> method of the persistence
149 * delegate for the <code>Field</code> class could be defined as follows:
150 * <pre>
151 * Field f = (Field)oldInstance;
152 * return new Expression(f, f.getDeclaringClass(), "getField", new Object[]{f.getName()});
153 * </pre>
154 * Note that we declare the value of the returned expression so that
155 * the value of the expression (as returned by <code>getValue</code>)
156 * will be identical to <code>oldInstance</code>.
157 *
158 * @param oldInstance The instance that will be created by this expression.
159 * @param out The stream to which this expression will be written.
160 * @return An expression whose value is <code>oldInstance</code>.
161 */
162 protected abstract Expression instantiate(Object oldInstance, Encoder out);
163
164 /**
165 * Produce a series of statements with side effects on <code>newInstance</code>
166 * so that the new instance becomes <em>equivalent</em> to <code>oldInstance</code>.
167 * In the specification of this method, we mean by equivalent that, after the method
168 * returns, the modified instance is indistinguishable from
169 * <code>newInstance</code> in the behavior of all methods in its
170 * public API.
171 * <p>
172 * The implementation typically achieves this goal by producing a series of
173 * "what happened" statements involving the <code>oldInstance</code>
174 * and its publicly available state. These statements are sent
175 * to the output stream using its <code>writeExpression</code>
176 * method which returns an expression involving elements in
177 * a cloned environment simulating the state of an input stream during
178 * reading. Each statement returned will have had all instances
179 * the old environment replaced with objects which exist in the new
180 * one. In particular, references to the target of these statements,
181 * which start out as references to <code>oldInstance</code> are returned
182 * as references to the <code>newInstance</code> instead.
183 * Executing these statements effects an incremental
184 * alignment of the state of the two objects as a series of
185 * modifications to the objects in the new environment.
186 * By the time the initialize method returns it should be impossible
187 * to tell the two instances apart by using their public APIs.
188 * Most importantly, the sequence of steps that were used to make
189 * these objects appear equivalent will have been recorded
190 * by the output stream and will form the actual output when
191 * the stream is flushed.
192 * <p>
193 * The default implementation, calls the <code>initialize</code>
194 * method of the type's superclass.
195 *
196 * @param oldInstance The instance to be copied.
197 * @param newInstance The instance that is to be modified.
198 * @param out The stream to which any initialization statements should be written.
199 */
200 protected void initialize(Class<?> type,
201 Object oldInstance, Object newInstance,
202 Encoder out)
203 {
204 Class superType = type.getSuperclass();
205 PersistenceDelegate info = out.getPersistenceDelegate(superType);
206 info.initialize(superType, oldInstance, newInstance, out);
207 }
208 }
Save This Page