Java > Open Source Codes > oracle > toplink > essentials > sessions > IdentityMapAccessor


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, 2006, Oracle. All rights reserved.
22 package oracle.toplink.essentials.sessions;
23
24 import java.util.*;
25 import oracle.toplink.essentials.expressions.*;
26 import oracle.toplink.essentials.exceptions.*;
27 import oracle.toplink.essentials.queryframework.*;
28 import oracle.toplink.essentials.internal.sessions.AbstractRecord;
29
30 /**
31  * PUBLIC:
32  * IdentityMapAccessor provides the public interface into all functionality associated with
33  * TopLink identity maps. An appropriate IdentityMapAccessor can be obtained from a session
34  * with its getIdentityMapAccessor() method.
35  * Methods that used to be called on the Session to access identity maps can now be called
36  * through the IdentityMapAccessor.
37  * <p>
38  * For instance, to initialize identity maps the code used to be: <code>
39  * session.initializeIdentityIdentityMaps() <br></code>
40  * With this class, the code now is: <code>
41  * session.getIdentityMapAccessor().initializeIdentityMaps() </code>
42  * @see oracle.toplink.sessions.Session
43  */
44 public interface IdentityMapAccessor {
45
46     /**
47      * ADVANCED:
48      * Returns true if the identity map contains an Object with the same primary
49      * key and Class type of the given domainObject.
50      * @param domainObject Object
51      * @return boolean
52      */
53     public boolean containsObjectInIdentityMap(Object domainObject);
54
55     /**
56      * ADVANCED:
57      * Returns true if the identity map contains an Object with the same
58      * primary key and Class type as those specified.
59      * @param primaryKey Vector
60      * @param theClass Class
61      * @return boolean
62      */
63     public boolean containsObjectInIdentityMap(Vector primaryKey, Class theClass);
64
65     /**
66      * ADVANCED:
67      * Returns true if the identity map contains an Object with the same primary key
68      * of the specified row (ie. the database record) and Class type.
69      * @param rowContainingPrimaryKey Record
70      * @param theClass Class type to be found
71      * @return boolean - true if Object in indentity map
72      */
73     public boolean containsObjectInIdentityMap(Record rowContainingPrimaryKey, Class theClass);
74
75     /**
76      * ADVANCED:
77      * Queries the cache in-memory with the passed in criteria and returns matching Objects.
78      * If the expression is too complex an exception will be thrown.
79      * Only returns Objects that are invalid from the map if specified with the
80      * boolean shouldReturnInvalidatedObjects.
81      * @param selectionCriteria Expression selecting the Objects to be returned
82      * @param theClass Class to be considered
83      * @param translationRow Record
84      * @param valueHolderPolicy see
85      * {@link oracle.toplink.queryframework.InMemoryQueryIndirectionPolicy InMemoryQueryIndirectionPolicy}
86      * @param shouldReturnInvalidatedObjects boolean - true if only invalid Objects should be returned
87      * @return Vector of Objects
88      * @throws QueryException
89      */
90     public Vector getAllFromIdentityMap(Expression selectionCriteria, Class theClass,
91             Record translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy,
92             boolean shouldReturnInvalidatedObjects)
93     throws QueryException;
94
95     /**
96      * ADVANCED:
97      * Queries the cache in-memory with the passed in criteria and returns matching Objects.
98      * If the expression is too complex an exception will be thrown.
99      * @param selectionCriteria Expression selecting the Objects to be returned
100      * @param theClass Class to be considered
101      * @param translationRow Record
102      * @param valueHolderPolicy see
103      * {@link oracle.toplink.queryframework.InMemoryQueryIndirectionPolicy InMemoryQueryIndirectionPolicy}
104      * @return Vector of Objects with type theClass and matching the selectionCriteria
105      * @throws QueryException
106      */
107     public Vector getAllFromIdentityMap(Expression selectionCriteria, Class theClass,
108             Record translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy)
109     throws QueryException;
110
111     /**
112      * ADVANCED:
113      * Returns the Object from the identity map with the same primary key
114      * and Class type of the given domainObject.
115      * @param domainObject Object
116      * @return Object from identity map, may be null.
117      */
118     public Object getFromIdentityMap(Object domainObject);
119
120     /**
121      * ADVANCED:
122      * Returns the Object from the identity map with the same primary key
123      * and Class type as those specified.
124      * @param primaryKey Vector
125      * @param theClass Class
126      * @return Object from identity map, may be null.
127      */
128     public Object getFromIdentityMap(Vector primaryKey, Class theClass);
129
130     /**
131      * ADVANCED:
132      * Returns the Object from the identity map with the same primary key
133      * of the specified row (ie. the database record) and Class type.
134      * @param rowContainingPrimaryKey Record
135      * @param theClass Class
136      * @return Object from identity map, may be null.
137      */
138     public Object getFromIdentityMap(Record rowContainingPrimaryKey, Class theClass);
139
140     /**
141      * ADVANCED:
142      * Returns the Object from the identity map with the same primary key and Class type
143      * as specified. May return null and will only return an Object that is invalidated
144      * if specified with the boolean shouldReturnInvalidatedObjects.
145      * @param primaryKey Vector
146      * @param theClass Class
147      * @param shouldReturnInvalidatedObjects InMemoryQueryIndirectionPolicy
148      * @return Object from identity map, may be null.
149      */
150     public Object getFromIdentityMap(Vector primaryKey, Class theClass, boolean shouldReturnInvalidatedObjects);
151
152     /**
153      * ADVANCED:
154      * Returns the Object from the identity map with the same primary key of the specified
155      * row and Class type. May return null and will only Only return an Object that is
156      * invalidated if specified with the boolean shouldReturnInvalidatedObjects.
157      * @param rowContainingPrimaryKey Record
158      * @param theClass Class
159      * @param shouldReturnInvalidatedObjects boolean
160      * @return Object from identity map, may be null.
161      */
162     public Object getFromIdentityMap(Record rowContainingPrimaryKey, Class theClass,
163             boolean shouldReturnInvalidatedObjects);
164
165     /**
166      * ADVANCED:
167      * Queries the cache in-memory and returns an Object from this identity map.
168      * If the Object is not found with the passed in Class type, Row and selectionCriteria,
169      * null is returned. If the expression is too complex an exception will be thrown.
170      * @param selectionCriteria Expression
171      * @param theClass Class
172      * @param translationRow Record
173      * @return Object from identity map, may be null
174      * @throws QueryException
175      */
176     public Object getFromIdentityMap(Expression selectionCriteria, Class theClass, Record translationRow)
177     throws QueryException;
178
179     /**
180      * ADVANCED:
181      * Queries the cache in-memory and returns an Object from this identity map.
182      * If the Object is not found with the passed in Class type, Row and selectionCriteria,
183      * null is returned. This method allows for control of un-instantiated indirection access
184      * with valueHolderPolicy. If the expression is too complex an exception will be thrown.
185      * @param selectionCriteria Expression
186      * @param theClass Class
187      * @param translationRow Record
188      * @param valueHolderPolicy
189      * see {@link oracle.toplink.queryframework.InMemoryQueryIndirectionPolicy InMemoryQueryIndirectionPolicy}
190      * @return Object from identity map, may be null
191      * @throws QueryException
192      */
193     public Object getFromIdentityMap(Expression selectionCriteria, Class theClass, Record translationRow,
194             InMemoryQueryIndirectionPolicy valueHolderPolicy) throws QueryException;
195
196     /**
197      * ADVANCED:
198      * Returns the remaining life of the given Object. This method is associated with use of
199      * TopLink's cache invalidation feature and returns the difference between the next expiry
200      * time of the Object and its read time. The method will return 0 for invalidated Objects.
201      * @param object Object under consideration
202      * @return long time in milliseconds
203      */
204     public long getRemainingValidTime(Object object);
205
206     /**
207      * ADVANCED:
208      * Extracts and returns the write lock value from the identity map through the given Object.
209      * Write lock values are used when optimistic locking is stored in the cache instead of the object.
210      * @param domainObject Object
211      * @return Object for versioning
212      */
213     public Object getWriteLockValue(Object domainObject);
214
215     /**
216      * ADVANCED:
217      * Extracts the write lock value from the identity map through the passed in primaryKey and Class type.
218      * Write lock values are used when optimistic locking is stored in the cache instead of the object.
219      * @param primaryKey Vector
220      * @param theClass Class
221      * @return Object for versioning
222      */
223     public Object getWriteLockValue(Vector primaryKey, Class theClass);
224
225     /**
226      * PUBLIC:
227      * Resets the entire Object cache.
228      * <p> NOTE: Be careful using this method. This method blows away both this session's and its parent's caches.
229      * This includes the server cache or any other cache. This throws away any Objects that have been read in.
230      * Extreme caution should be used before doing this because Object identity will no longer
231      * be maintained for any Objects currently read in. This should only be called
232      * if the application knows that it no longer has references to Objects held in the cache.
233      */
234     public void initializeAllIdentityMaps();
235
236     /**
237      * PUBLIC:
238      * Resets the identity map for only the instances of the given Class type.
239      * For inheritance the user must make sure that they only use the root class.
240      * <p> NOTE: Caution must be used in doing this to ensure that the Objects within the identity map
241      * are not referenced from other Objects of other classes or from the application.
242      * @param theClass Class
243      */
244     public void initializeIdentityMap(Class theClass);
245
246     /**
247      * PUBLIC:
248      * Resets the entire local Object cache.
249      * <p> NOTE: This throws away any Objects that have been read in.
250      * Extreme caution should be used before doing this because Object identity will no longer
251      * be maintained for any Objects currently read in. This should only be called
252      * if the application knows that it no longer has references to Objects held in the cache.
253      */
254     public void initializeIdentityMaps();
255
256     /**
257      * ADVANCED:
258      * Sets an Object to be invalid in the TopLink identity maps.
259      * If this Object does not exist in the cache, this method will return
260      * without any action.
261      * @param object Object
262      */
263     public void invalidateObject(Object object);
264
265     /**
266      * ADVANCED:
267      * Sets an Object with the specified primary key and Class type to be invalid in
268      * the TopLink identity maps. If the Object does not exist in the cache,
269      * this method will return without any action.
270      * @param primaryKey Vector
271      * @param theClass Class
272      */
273     public void invalidateObject(Vector primaryKey, Class theClass);
274
275     /**
276      * ADVANCED:
277      * Sets an Object with the specified primary key of the passed in Row and Class type to
278      * be invalid in the TopLink identity maps. If the Object does not exist in the cache,
279      * this method will return without any action.
280      * @param rowContainingPrimaryKey Record
281      * @param theClass Class
282      */
283     public void invalidateObject(Record rowContainingPrimaryKey, Class theClass);
284
285     /**
286      * ADVANCED:
287      * Sets all of the Objects in the given collection to be invalid in the TopLink identity maps.
288      * This method will take no action for any Objects in the collection that do not exist in the cache.
289      * @param collection Vector of Objects to be invalidated
290      */
291     public void invalidateObjects(Vector collection);
292
293     /**
294      * ADVANCED:
295      * Sets all of the Objects matching the given Expression to be invalid in the TopLink identity maps.
296      * <p>
297      * <b>Example</b> - Invalidating Employee Objects with non-null first names:
298      * <p>
299      * <code>
300      * ExpressionBuilder eb = new ExpressionBuilder(Employee.class); <br>
301      * Expression exp = eb.get("firstName").notNull(); <br>
302      * session.getIdentityMapAccessor().invalidateObjects(exp); <br>
303      * </code>
304      * @param selectionCriteria Expression
305      */
306     public void invalidateObjects(Expression selectionCriteria);
307
308     /**
309      * ADVANCED:
310      * Sets all of the Objects for all classes to be invalid in TopLink's identity maps.
311      * It will recurse on inheritance.
312      */
313     public void invalidateAll();
314     
315     /**
316      * ADVANCED:
317      * Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps
318      * Will set the recurse on inheritance to true.
319      * @param myClass Class
320      */
321     public void invalidateClass(Class myClass);
322
323     /**
324      * ADVANCED:
325      * Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps.
326      * User can set the recurse flag to false if they do not want to invalidate
327      * all the same Class types within an inheritance tree.
328      * @param myClass Class
329      * @param recurse boolean
330      */
331     public void invalidateClass(Class myClass, boolean recurse);
332
333     /**
334      * ADVANCED:
335      * Returns true if an Object with the same primary key and Class type of the
336      * the given Object is valid in TopLink's identity maps.
337      * @param object Object
338      * @return boolean
339      */
340     public boolean isValid(Object object);
341
342     /**
343      * ADVANCED:
344      * Returns true if the Object described by the given primary key and Class type is valid
345      * in TopLink's identity maps.
346      * @param primaryKey Vector
347      * @param theClass Class
348      * @return boolean
349      */
350     public boolean isValid(Vector primaryKey, Class theClass);
351
352     /**
353      * ADVANCED:
354      * Returns true if this Object with the given primary key of the Row and Class type
355      * given is valid in TopLink's identity maps.
356      * @param rowContainingPrimaryKey AbstractRecord
357      * @param theClass Class
358      * @return boolean
359      */
360     public boolean isValid(AbstractRecord rowContainingPrimaryKey, Class theClass);
361
362     /**
363      * PUBLIC:
364      * Used to print all the Objects in the identity map of the given Class type.
365      * The output of this method will be logged to this session's SessionLog at SEVERE level.
366      * @param businessClass Class
367      */
368     public void printIdentityMap(Class businessClass);
369
370     /**
371      * PUBLIC:
372      * Used to print all the Objects in every identity map in this session.
373      * The output of this method will be logged to this session's SessionLog at SEVERE level.
374      */
375     public void printIdentityMaps();
376
377     /**
378      * PUBLIC:
379      * Used to print all the locks in every identity map in this session.
380      * The output of this method will be logged to this session's SessionLog at FINEST level.
381      */
382     public void printIdentityMapLocks();
383
384     /**
385      * ADVANCED:
386      * Registers the given Object with the identity map.
387      * The Object must always be registered with its version number if optimistic locking is used.
388      * @param domainObject Object
389      * @return Object
390      */
391     public Object putInIdentityMap(Object domainObject);
392
393     /**
394      * ADVANCED:
395      * Registers the Object and given key with the identity map.
396      * The Object must always be registered with its version number if optimistic locking is used.
397      * @param domainObject Object
398      * @param key Vector
399      * @return Object
400      */
401     public Object putInIdentityMap(Object domainObject, Vector key);
402
403     /**
404      * ADVANCED:
405      * Registers the Object and given key with the identity map.
406      * The Object must always be registered with its version number if optimistic locking is used.
407      * @param domainObject Object
408      * @param key Vector
409      * @param writeLockValue Object for versioning
410      * @return Object
411      */
412     public Object putInIdentityMap(Object domainObject, Vector key, Object writeLockValue);
413
414     /**
415      * ADVANCED:
416      * Registers the given Object with the identity map.
417      * The Object must always be registered with its version number if optimistic locking is used.
418      * The readTime may also be included in the cache key as it is constructed.
419      * @param domainObject Object
420      * @param key Vector
421      * @param writeLockValue Object for versioning
422      * @param readTime long, time in milliseconds
423      * @return Object the Object put into the identity map
424      */
425     public Object putInIdentityMap(Object domainObject, Vector key, Object writeLockValue, long readTime);
426
427     /**
428      * ADVANCED:
429      * Removes the Object from the Object cache.
430      * <p> NOTE: Caution should be used when calling to avoid violating Object identity.
431      * The application should only call this if its known that no references to the Object exist.
432      * @param domainObject Object
433      * @return Object the Object removed from the identity map
434      */
435     public Object removeFromIdentityMap(Object domainObject);
436
437     /**
438      * ADVANCED:
439      * Removes the Object with given primary key and Class from the Object cache.
440      * <p> NOTE: Caution should be used when calling to avoid violating Object identity.
441      * The application should only call this if its known that no references to the Object exist.
442      * @param key Vector
443      * @param theClass Class
444      * @return Object the Object removed from the identity map
445      */
446     public Object removeFromIdentityMap(Vector key, Class theClass);
447
448     /**
449      * ADVANCED:
450      * Updates the write lock value in the identity map for cache key of the primary key
451      * the given Object.
452      * @param domainObject Object
453      * @param writeLockValue Object for versioning
454      */
455     public void updateWriteLockValue(Object domainObject, Object writeLockValue);
456
457     /**
458      * ADVANCED:
459      * Updates the write lock value in the cache for the Object with same primary key as the given Object.
460      * The write lock values is used when optimistic locking is stored in the cache instead of in the object.
461      * @param primaryKey Vector
462      * @param theClass Class
463      * @param writeLockValue Object for versioning
464      */
465     public void updateWriteLockValue(Vector primaryKey, Class theClass, Object writeLockValue);
466
467     /**
468      * ADVANCED:
469      * This can be used to help debugging an Object identity problem.
470      * An Object identity problem is when an Object in the cache references an
471      * Object that is not in the cache. This method will validate that all cached
472      * Objects are in a correct state.
473      */
474     public void validateCache();
475 }

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags