KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > oracle > toplink > essentials > internal > indirection > IndirectionPolicy


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the "License"). You may not use this file except
5  * in compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * glassfish/bootstrap/legal/CDDLv1.0.txt or
9  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * HEADER in each file and include the License file at
15  * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
16  * add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your
18  * own identifying information: Portions Copyright [yyyy]
19  * [name of copyright owner]
20  */
21 // Copyright (c) 1998, 2005, Oracle. All rights reserved.
22 package oracle.toplink.essentials.internal.indirection;
23
24 import java.io.*;
25 import java.util.*;
26 import oracle.toplink.essentials.exceptions.*;
27 import oracle.toplink.essentials.internal.descriptors.*;
28 import oracle.toplink.essentials.internal.sessions.MergeManager;
29 import oracle.toplink.essentials.mappings.*;
30 import oracle.toplink.essentials.queryframework.*;
31 import oracle.toplink.essentials.internal.sessions.AbstractRecord;
32 import oracle.toplink.essentials.internal.sessions.UnitOfWorkImpl;
33 import oracle.toplink.essentials.internal.sessions.AbstractSession;
34
35 /**
36  * <h2>Purpose</h2>:
37  * An IndirectionPolicy acts as a 'rules' holder that determines
38  * the behavior of a ForeignReferenceMapping (or TransformationMapping)
39  * with respect to indirection, or lack thereof.
40  * <p>
41  * <h3>Description</h3>:
42  * IndirectionPolicy is an abstract class that defines the protocol to be implemented by
43  * subclasses so that the assorted DatabaseMappings can use an assortment of
44  * indirection policies:<ul>
45  * <li> no indirection policy (read everything from database)
46  * <li> basic indirection policy (use ValueHolders)
47  * <li> transparent indirection policy (collections only)
48  * <li> proxy indirection policy (transparent 1:1 indirection using JDK 1.3's <CODE>Proxy</CODE>)
49  * </ul>
50  *
51  * <p>
52  * <h3>Responsibilities</h3>:
53  * <ul>
54  * <li>instantiate the various IndirectionPolicies
55  * </ul>
56  * <p>
57  *
58  * @see ForeignReferenceMapping
59  * @author Mike Norman
60  * @since TOPLink/Java 2.5
61  */
62 public abstract class IndirectionPolicy implements Cloneable JavaDoc, Serializable {
63     protected DatabaseMapping mapping;
64
65     /**
66      * INTERNAL:
67      * Construct a new indirection policy.
68      */
69     public IndirectionPolicy() {
70         super();
71     }
72
73     /**
74      * INTERNAL:
75      * Return a backup clone of the attribute.
76      */
77     public Object JavaDoc backupCloneAttribute(Object JavaDoc attributeValue, Object JavaDoc clone, Object JavaDoc backup, UnitOfWorkImpl unitOfWork) {
78         return this.getMapping().buildBackupCloneForPartObject(attributeValue, clone, backup, unitOfWork);
79     }
80
81     /**
82      * INTERNAL
83      * Return true if the refresh shoud refresh on this mapping or not.
84      */
85     protected ReadObjectQuery buildCascadeQuery(MergeManager mergeManager) {
86         ReadObjectQuery cascadeQuery = new ReadObjectQuery();
87         if (mergeManager.shouldCascadeAllParts()) {
88             cascadeQuery.cascadeAllParts();
89             cascadeQuery.refreshIdentityMapResult();
90         }
91         if (mergeManager.shouldCascadePrivateParts() && getForeignReferenceMapping().isPrivateOwned()) {
92             cascadeQuery.cascadePrivateParts();
93             cascadeQuery.refreshIdentityMapResult();
94         }
95
96         return cascadeQuery;
97     }
98
99     /**
100      * INTERNAL:
101      * Clones itself.
102      */
103     public Object JavaDoc clone() {
104         try {
105             return super.clone();
106         } catch (CloneNotSupportedException JavaDoc e) {
107             throw new InternalError JavaDoc();
108         }
109     }
110
111     /**
112      * INTERNAL:
113      * Return a clone of the attribute.
114      * @param builtDirectlyFromRow indicates that we are building the clone
115      * directly from a row as opposed to building the original from the
116      * row, putting it in the shared cache, and then cloning the original.
117      */
118     public abstract Object JavaDoc cloneAttribute(Object JavaDoc attributeValue, Object JavaDoc original, Object JavaDoc clone, UnitOfWorkImpl unitOfWork, boolean buildDirectlyFromRow);
119
120     /**
121      * INTERNAL:
122      * Return the primary key for the reference object (i.e. the object
123      * object referenced by domainObject and specified by mapping).
124      * This key will be used by a RemoteValueHolder.
125      */
126     public Vector extractPrimaryKeyForReferenceObject(Object JavaDoc referenceObject, AbstractSession session) {
127         return this.getOneToOneMapping().extractPrimaryKeysFromRealReferenceObject(referenceObject, session);
128     }
129
130     /**
131      * INTERNAL:
132      * Return the reference row for the reference object.
133      * This allows the new row to be built without instantiating
134      * the reference object.
135      * Return null if the object has already been instantiated.
136      */
137     public abstract AbstractRecord extractReferenceRow(Object JavaDoc referenceObject);
138
139     /**
140      * INTERNAL:
141      * Reduce casting clutter....
142      */
143     protected CollectionMapping getCollectionMapping() {
144         return (CollectionMapping)this.getMapping();
145     }
146
147     /**
148      * INTERNAL:
149      * Reduce casting clutter....
150      */
151     protected ForeignReferenceMapping getForeignReferenceMapping() {
152         return (ForeignReferenceMapping)this.getMapping();
153     }
154
155     /**
156      * INTERNAL:
157      * Return the database mapping that uses the indirection policy.
158      */
159     public DatabaseMapping getMapping() {
160         return mapping;
161     }
162
163     /**
164      * INTERNAL:
165      * Reduce casting clutter....
166      */
167     protected ObjectReferenceMapping getOneToOneMapping() {
168         return (ObjectReferenceMapping)this.getMapping();
169     }
170
171     /**
172      * INTERNAL:
173      * Return the original indirection object for a unit of work indirection object.
174      */
175     public abstract Object JavaDoc getOriginalIndirectionObject(Object JavaDoc unitOfWorkIndirectionObject, AbstractSession session);
176
177     /**
178      * INTERNAL:
179      * Return the "real" attribute value, as opposed to any wrapper.
180      * This will trigger the wrapper to instantiate the value.
181      */
182     public abstract Object JavaDoc getRealAttributeValueFromObject(Object JavaDoc object);
183
184     /**
185      * INTERNAL:
186      * Given a proxy object, trigger the indirection and return the actual object represented by the proxy.
187      * For non-proxy indirection, this method will simply return the object.
188      */
189     public static Object JavaDoc getValueFromProxy(Object JavaDoc value) {
190         return value;
191     }
192
193     /**
194      * INTERNAL:
195      * Initialize the indirection policy (Do nothing by default)
196      */
197     public void initialize() {
198     }
199
200     /**
201      * INTERNAL:
202      * Iterate over the specified attribute value,
203      * heeding the settings in the iterator.
204      */
205     public void iterateOnAttributeValue(DescriptorIterator iterator, Object JavaDoc attributeValue) {
206         if (attributeValue != null) {
207             this.getMapping().iterateOnRealAttributeValue(iterator, attributeValue);
208         }
209     }
210
211     /**
212      * INTERNAL:
213      * Return the null value of the appropriate attribute. That is, the
214      * field from the database is NULL, return what should be
215      * placed in the object's attribute as a result.
216      */
217     public abstract Object JavaDoc nullValueFromRow();
218
219     /**
220      * INTERNAL:
221      * Return whether the specified object is instantiated.
222      */
223     public abstract boolean objectIsInstantiated(Object JavaDoc object);
224
225     /**
226      * INTERNAL:
227      * set the database mapping that uses the indirection policy.
228      */
229     public void setMapping(DatabaseMapping mapping) {
230         this.mapping = mapping;
231     }
232
233     /**
234      * INTERNAL:
235      * Set the value of the appropriate attribute of target to attributeValue.
236      * In this case, simply place the value inside the target.
237      */
238     public void setRealAttributeValueInObject(Object JavaDoc target, Object JavaDoc attributeValue) {
239         this.getMapping().setAttributeValueInObject(target, attributeValue);
240     }
241
242     /**
243      * INTERNAL:
244      * Return whether the indirection policy actually uses indirection.
245      * The default is true.
246      */
247     public boolean usesIndirection() {
248         return true;
249     }
250     
251     /**
252      * INTERNAL:
253      * Return whether the indirection policy uses transparent indirection.
254      * The default is false.
255      */
256     public boolean usesTransparentIndirection(){
257         return false;
258     }
259
260     /**
261      * INTERNAL:
262      * Verify that the value of the attribute within an instantiated object
263      * is of the appropriate type for the indirection policy.
264      * If it is incorrect, throw an exception.
265      * If the value is null return a new indirection object to be used for the attribute.
266      */
267     public Object JavaDoc validateAttributeOfInstantiatedObject(Object JavaDoc attributeValue) throws DescriptorException {
268         return attributeValue;
269     }
270
271     /**
272      * INTERNAL:
273      * Verify that the container policy is compatible with the
274      * indirection policy. If it is incorrect, add an exception to the
275      * integrity checker.
276      */
277     public void validateContainerPolicy(IntegrityChecker checker) throws DescriptorException {
278         // by default, do nothing
279 }
280
281     /**
282      * INTERNAL:
283      * Verify that attributeType is correct for the
284      * indirection policy. If it is incorrect, add an exception to the
285      * integrity checker.
286      */
287     public void validateDeclaredAttributeType(Class JavaDoc attributeType, IntegrityChecker checker) throws DescriptorException {
288         // by default, do nothing
289 }
290
291     /**
292      * INTERNAL:
293      * Verify that attributeType is an appropriate collection type for the
294      * indirection policy. If it is incorrect, add an exception to the integrity checker.
295      */
296     public void validateDeclaredAttributeTypeForCollection(Class JavaDoc attributeType, IntegrityChecker checker) throws DescriptorException {
297         // by default, do nothing
298 }
299
300     /**
301      * INTERNAL:
302      * Verify that getter returnType is correct for the
303      * indirection policy. If it is incorrect, add an exception
304      * to the integrity checker.
305      */
306     public void validateGetMethodReturnType(Class JavaDoc returnType, IntegrityChecker checker) throws DescriptorException {
307         // by default, do nothing
308 }
309
310     /**
311      * INTERNAL:
312      * Verify that getter returnType is an appropriate collection type for the
313      * indirection policy. If it is incorrect, add an exception to the integrity checker.
314      */
315     public void validateGetMethodReturnTypeForCollection(Class JavaDoc returnType, IntegrityChecker checker) throws DescriptorException {
316         // by default, do nothing
317 }
318
319     /**
320      * INTERNAL:
321      * Verify that setter parameterType is correct for the
322      * indirection policy. If it is incorrect, add an exception
323      * to the integrity checker.
324      */
325     public void validateSetMethodParameterType(Class JavaDoc parameterType, IntegrityChecker checker) throws DescriptorException {
326         // by default, do nothing
327 }
328
329     /**
330      * INTERNAL:
331      * Verify that setter parameterType is an appropriate collection type for the
332      * indirection policy. If it is incorrect, add an exception to the integrity checker.
333      */
334     public void validateSetMethodParameterTypeForCollection(Class JavaDoc parameterType, IntegrityChecker checker) throws DescriptorException {
335         // by default, do nothing
336 }
337
338     /**
339      * INTERNAL:
340      * Return the value to be stored in the object's attribute.
341      * This value is determined by the query.
342      */
343     public abstract Object JavaDoc valueFromQuery(ReadQuery query, AbstractRecord row, AbstractSession session);
344
345     /**
346      * INTERNAL:
347      * Return the value to be stored in the object's attribute.
348      * This value is determined by the row.
349      */
350     public abstract Object JavaDoc valueFromRow(Object JavaDoc object);
351 }
352
Popular Tags