001: /*
002: * All content copyright (c) 2003-2006 Terracotta, Inc., except as may otherwise be noted in a separate copyright notice. All rights reserved.
003: */
004: package com.tc.object;
005:
006: import com.tc.exception.TCNonPortableObjectError;
007: import com.tc.object.appevent.ApplicationEvent;
008: import com.tc.object.appevent.ApplicationEventContext;
009: import com.tc.object.dna.api.DNA;
010: import com.tc.object.tx.ClientTransactionManager;
011: import com.tc.object.tx.optimistic.OptimisticTransactionManager;
012:
013: import java.lang.ref.ReferenceQueue;
014: import java.lang.ref.WeakReference;
015: import java.util.Collection;
016: import java.util.Map;
017:
018: /**
019: * Manages client-side (L1) object state in a VM.
020: *
021: */
022: public interface ClientObjectManager {
023:
024: /**
025: * Find a class based on the class name and the classloader name
026: * @param className Class name
027: * @param loaderDesc Classloader name
028: * @return Class, never null
029: * @throws ClassNotFoundException If class not found
030: */
031: public Class getClassFor(String className, String loaderDesc)
032: throws ClassNotFoundException;
033:
034: /**
035: * Determine whether this instance is managed.
036: * @param pojo The instance
037: * @return True if managed
038: */
039: public boolean isManaged(Object pojo);
040:
041: /**
042: * Mark a managed object as referenced
043: * @param tcobj Managed object
044: */
045: public void markReferenced(TCObject tcobj);
046:
047: /**
048: * Determine whether this class is portable
049: * @param clazz The class to check
050: * @return True if portable
051: */
052: public boolean isPortableClass(Class clazz);
053:
054: /**
055: * Determine whether this instance is portable
056: * @param instance The instance to check
057: * @return True if portable
058: */
059: public boolean isPortableInstance(Object instance);
060:
061: /**
062: * Check whether field of an instance is portable
063: * @param value Field value
064: * @param fieldName Field name
065: * @param pojo Instance to check
066: * @throws TCNonPortableObjectError If field is not portable
067: */
068: public void checkPortabilityOfField(Object value, String fieldName,
069: Object pojo) throws TCNonPortableObjectError;
070:
071: /**
072: * Check whether logical action is portable
073: * @param params Method call parameters
074: * @param paramIndex Parameter index
075: * @param methodName Method name
076: * @param pojo Instance
077: * @throws TCNonPortableObjectError If logical action is not portable
078: */
079: public void checkPortabilityOfLogicalAction(Object[] params,
080: int paramIndex, String methodName, Object pojo)
081: throws TCNonPortableObjectError;
082:
083: /**
084: * Replace root ID. Primitive roots are replaceable. Object reference roots generally are not
085: * but this can be controlled by the configuration.
086: * @param rootName Root object name
087: * @param newRootID New root object identifier
088: */
089: public void replaceRootIDIfNecessary(String rootName,
090: ObjectID newRootID);
091:
092: /**
093: * Find object by ID. If necessary, the object will be faulted into the JVM.
094: * The default fault-count will be used to limit the number of dependent objects that
095: * are also faulted in.
096: * @param id Identifier
097: * @return Instance for the id
098: * @throws ClassNotFoundException If class can't be found in this VM
099: */
100: public Object lookupObject(ObjectID id)
101: throws ClassNotFoundException;
102:
103: /**
104: * Look up object by ID, faulting into the JVM if necessary, This method also passes the parent Object context so that
105: * more intelligent prefetching is possible at the L2.
106: * The default fault-count will be used to limit the number of dependent objects that
107: * are also faulted in.
108: *
109: * @param id Object identifier of the object we are looking up
110: * @param parentContext Object identifier of the parent object
111: * @return The actual object
112: * @throws TCClassNotFoundException If a class is not found during faulting
113: */
114: public Object lookupObject(ObjectID id, ObjectID parentContext)
115: throws ClassNotFoundException;
116:
117: /**
118: * Find object by ID. If necessary, the object will be faulted into the JVM.
119: * No fault-count depth will be used and all dependent objects will be faulted into
120: * memory.
121: * @param id Identifier
122: * @return Instance for the id
123: * @throws ClassNotFoundException If class can't be found in this VM
124: */
125: public Object lookupObjectNoDepth(ObjectID id)
126: throws ClassNotFoundException;
127:
128: /**
129: * Find the managed object for this instance or create a new one if it does not
130: * yet exist.
131: * @param obj Instance
132: * @return Managed object, may be new. Should never be null, but might be object representing null TCObject.
133: */
134: public TCObject lookupOrCreate(Object obj);
135:
136: /**
137: * Find the managed object for this instance or share. This method is (exclusively?) used when
138: * implementing ConcurrentHashMap sharing.
139: * @param obj Instance
140: * @return Should never be null, but might be object representing null TCObject.
141: */
142: public TCObject lookupOrShare(Object pojo);
143:
144: /**
145: * Find identifier for existing instance
146: * @param obj Object instance
147: * @return Identifier
148: */
149: public ObjectID lookupExistingObjectID(Object obj);
150:
151: /**
152: * Find named root object
153: * @param name Root name
154: * @return Root object
155: */
156: public Object lookupRoot(String name);
157:
158: /**
159: * Find and create if necessary a root object for the specified named root.
160: * All dependent objects needed will be faulted in to arbitrary depth.
161: * @param rootName Root name
162: * @param object Instance to use if new
163: * @return New or existing object to use as root
164: */
165: public Object lookupOrCreateRootNoDepth(String rootName,
166: Object object);
167:
168: /**
169: * Find and create if necessary a root object for the specified named root.
170: * All dependent objects needed will be faulted in, limited to the
171: * fault-count specified in the configuration.
172: *
173: * @param name Root name
174: * @param obj Instance to use if new
175: * @return New or existing object to use as root
176: */
177: public Object lookupOrCreateRoot(String name, Object obj);
178:
179: /**
180: * Find and create if necessary a root object for the specified named root.
181: * All dependent objects needed will be faulted in, limited to the
182: * fault-count specified in the configuration.
183: *
184: * @param name Root name
185: * @param obj Instance to use if new
186: * @param dsoFinal Specify whether this is root is considered final and whether an existing root can be replaced
187: * @return New or existing object to use as root
188: */
189: public Object lookupOrCreateRoot(String name, Object obj,
190: boolean dsoFinal);
191:
192: /**
193: * Find managed object locally (don't fault in an object from the server).
194: * @param id Identifier
195: * @return Managed object or null if not in client
196: */
197: public TCObject lookupIfLocal(ObjectID id);
198:
199: /**
200: * Find managed object by identifier
201: * @param id Identifier
202: * @return Managed object
203: * @throws ClassNotFoundException If a class needed to hydrate cannot be found
204: */
205: public TCObject lookup(ObjectID id) throws ClassNotFoundException;
206:
207: /**
208: * Find managed object by instance, which may be null
209: * @param pojo Instance
210: * @return Managed object if it exists, or null otherwise
211: */
212: public TCObject lookupExistingOrNull(Object pojo);
213:
214: /**
215: * Get all IDs currently in the cache and add to c. Clear all from remote object manager.
216: * @param c Collection to collect IDs in
217: * @return c
218: */
219: public Collection getAllObjectIDsAndClear(Collection c);
220:
221: /**
222: * Create new peer object instance for the clazz, referred to through a WeakReference.
223: * @param clazz The kind of class
224: * @param dna The dna defining the object instance
225: * @return Weak reference referring to the peer
226: */
227: public WeakReference createNewPeer(TCClass clazz, DNA dna);
228:
229: //public WeakObjectReference createNewPeer(TCClass clazz, DNA dna);
230:
231: /**
232: * Create new peer object instance for the clazz, referred to through a WeakReference.
233: * @param clazz The kind of class
234: * @param size The size if this is an array
235: * @param id The object identifier
236: * @param parentID The parent object, if this is an inner object
237: * @return Weak reference referring to the peer
238: */
239: public WeakReference createNewPeer(TCClass clazz, int size,
240: ObjectID id, ObjectID parentID);
241:
242: //public WeakObjectReference createNewPeer(TCClass clazz, int size, ObjectID id, ObjectID parentID);
243:
244: /**
245: * Get or create a reference to the managed class for this clazz
246: * @param clazz The Java class
247: * @return The Terracotta class
248: */
249: public TCClass getOrCreateClass(Class clazz);
250:
251: /**
252: * Set the client transaction manager
253: * @param txManager Transaction manager
254: */
255: public void setTransactionManager(ClientTransactionManager txManager);
256:
257: /**
258: * Get the client transaction manager
259: * @return Transaction manager
260: */
261: public ClientTransactionManager getTransactionManager();
262:
263: /**
264: * Get the reference queue for weakly referenced peers
265: * @return Reference queue
266: */
267: public ReferenceQueue getReferenceQueue();
268:
269: /**
270: * Shutdown the client object manager
271: */
272: public void shutdown();
273:
274: /**
275: * Unpause, moving state to running
276: */
277: public void unpause();
278:
279: /**
280: * Pause client object manager, for use while starting
281: */
282: public void pause();
283:
284: /**
285: * Change to STARTING state
286: */
287: public void starting();
288:
289: /**
290: * Do deep copy of source object using the transaction manager
291: * @param source Source object
292: * @param optimisticTxManager Transaction manager to use
293: * @return Deep copy of source
294: */
295: public Object deepCopy(Object source,
296: OptimisticTransactionManager optimisticTxManager);
297:
298: /**
299: * Take a source and a parent (if non-static inner) and create a new empty instance
300: * @param source Source object
301: * @param parent Parent object
302: * @return New copy instance of source
303: */
304: public Object createNewCopyInstance(Object source, Object parent);
305:
306: /**
307: * For an inner object, create or find the containing parent instance.
308: * @param visited Map of those objects that have been visited so far
309: * @param cloned Map of those objects that have been cloned already
310: * @param v The object
311: * @return The new or existing parent object clone
312: */
313: public Object createParentCopyInstanceIfNecessary(Map visited,
314: Map cloned, Object v);
315:
316: /**
317: * @return True if creation in progress
318: */
319: public boolean isCreationInProgress();
320:
321: /**
322: * Add all pending create object actions (created during traversals) to the current transaction.
323: */
324: public void addPendingCreateObjectsToTransaction();
325:
326: /**
327: * Check whether there are any currently pending create objects
328: * @return True if any pending
329: */
330: public boolean hasPendingCreateObjects();
331:
332: /**
333: * Create or replace a root value, typically used for replacable roots.
334: * @param rootName Root name
335: * @param root New root value
336: */
337: public Object createOrReplaceRoot(String rootName, Object root);
338:
339: //// The following are in support of the Eclipse ApplicationEventDialog and the Session Configurator.
340:
341: /**
342: * Store the pojo object hierarchy in the context's tree model.
343: * @param pojo The object
344: * @param context The event context
345: */
346: void storeObjectHierarchy(Object pojo,
347: ApplicationEventContext context);
348:
349: /**
350: * Send an ApplicationEvent occurring on pojo to the server via JMX.
351: * The handling of concrete event types occurs in com.tc.objectserver.DSOApplicationEvents.
352: * @param pojo The object
353: * @param event The event
354: */
355: void sendApplicationEvent(Object pojo, ApplicationEvent event);
356:
357: /**
358: * Clone logicalPojo and then apply the specified logical operation, returning the clone.
359: * @param logicalPojo The logical object
360: * @param methodName The method name on the logical object
361: * @param parameters The parameter values
362: * @return The cloned object
363: */
364: Object cloneAndInvokeLogicalOperation(Object logicalPojo,
365: String methodName, Object[] parameters);
366:
367: }
|