001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.kernel;
020:
021: import java.util.BitSet;
022: import java.util.Collection;
023: import java.util.Iterator;
024:
025: import org.apache.openjpa.conf.OpenJPAConfiguration;
026: import org.apache.openjpa.meta.ValueMetaData;
027:
028: /**
029: * Represents a set of managed objects and their environment.
030: *
031: * @since 0.4.0
032: * @author Abe White
033: */
034: public interface StoreContext {
035:
036: /**
037: * Marker bitset to indicate that all field loads should be excluded in
038: * the <code>find</code> methods of this interface.
039: */
040: public static final BitSet EXCLUDE_ALL = new BitSet(0);
041:
042: public static final int OID_NOVALIDATE = 2 << 0;
043: public static final int OID_NODELETED = 2 << 1;
044: public static final int OID_COPY = 2 << 2;
045: public static final int OID_ALLOW_NEW = 2 << 3;
046:
047: /**
048: * Return the broker for this context, if possible. Note that a broker
049: * will be unavailable in remote contexts, and this method may return null.
050: */
051: public Broker getBroker();
052:
053: /**
054: * Return the configuration associated with this context.
055: */
056: public OpenJPAConfiguration getConfiguration();
057:
058: /**
059: * Return the (mutable) fetch configuration for loading objects from this
060: * context.
061: */
062: public FetchConfiguration getFetchConfiguration();
063:
064: /**
065: * Return the current thread's class loader at the time this context
066: * was obtained.
067: */
068: public ClassLoader getClassLoader();
069:
070: /**
071: * Return the lock manager in use.
072: */
073: public LockManager getLockManager();
074:
075: /**
076: * Return the store manager in use. This will be a wrapper around the
077: * native store manager, which you can retrieve via
078: * {@link DelegatingStoreManager#getInnermostDelegate}.
079: */
080: public DelegatingStoreManager getStoreManager();
081:
082: /**
083: * Return the connection user name.
084: */
085: public String getConnectionUserName();
086:
087: /**
088: * Return the connection password.
089: */
090: public String getConnectionPassword();
091:
092: /**
093: * Return the cached instance for the given oid/object, or null if not
094: * cached.
095: *
096: * @param oid the object's id
097: * @return the cached object, or null if not cached
098: */
099: public Object findCached(Object oid, FindCallbacks call);
100:
101: /**
102: * Find the persistence object with the given oid. If
103: * <code>validate</code> is true, the broker will check the store
104: * for the object, and return null if it does not exist. If
105: * <code>validate</code> is false, this method never returns null. The
106: * broker will either return its cached instance, attempt to create a
107: * hollow instance, or throw an <code>ObjectNotFoundException</code> if
108: * unable to return a hollow instance.
109: *
110: * @param validate if true, validate that the instance exists in the
111: * store and load fetch group fields, otherwise return
112: * any cached or hollow instance
113: */
114: public Object find(Object oid, boolean validate, FindCallbacks call);
115:
116: /**
117: * Return the objects with the given oids.
118: *
119: * @param oids the oids of the objects to return
120: * @return the objects that were looked up, in the same order as the oids
121: * parameter
122: * @see #find(Object,boolean,FindCallbacks)
123: */
124: public Object[] findAll(Collection oids, boolean validate,
125: FindCallbacks call);
126:
127: /**
128: * Return the object with the given oid. If present, the
129: * cached instance will be returned. Otherwise, the instance will be
130: * initialized through the store as usual; however, in this case
131: * the store will be passed the given execution data, and the
132: * system will load the object according to the given fetch configuratiion
133: * (or the context's configuration, if the given one is null).
134: * Fields can optionally be excluded from required loading using the
135: * <code>exclude</code> mask. By default this method does not find new
136: * unflushed instances, validates, and does not throw an exception
137: * if a cached instance has been deleted concurrently. These options
138: * are controllable through the given <code>OID_XXX</code> flags.
139: */
140: public Object find(Object oid, FetchConfiguration fetch,
141: BitSet exclude, Object edata, int flags);
142:
143: /**
144: * Return the objects with the given oids.
145: *
146: * @see #find(Object,FetchConfiguration,BitSet,Object,int)
147: */
148: public Object[] findAll(Collection oids, FetchConfiguration fetch,
149: BitSet exclude, Object edata, int flags);
150:
151: /**
152: * Return an iterator over all instances of the given type. The iterator
153: * should be closed with {@link org.apache.openjpa.util.ImplHelper#close}
154: * when no longer needed. This method delegates to
155: * {@link StoreManager#executeExtent}.
156: */
157: public Iterator extentIterator(Class cls, boolean subs,
158: FetchConfiguration fetch, boolean ignoreChanges);
159:
160: /**
161: * Immediately load the given object's persistent fields. One might
162: * use this action to make sure that an instance's fields are loaded
163: * before transitioning it to transient. Note that this action is not
164: * recursive. Any related objects that are loaded will not necessarily
165: * have their fields loaded. Unmanaged target is ignored.
166: *
167: * @param fgOnly indicator as to whether to retrieve only fields
168: * in the current fetch groups, or all fields
169: * @see #retrieve
170: */
171: public void retrieve(Object pc, boolean fgOnly, OpCallbacks call);
172:
173: /**
174: * Retrieve the given objects' persistent state. Unmanaged targets are
175: * ignored.
176: *
177: * @param fgOnly indicator as to whether to retrieve only fields
178: * @see #retrieve
179: */
180: public void retrieveAll(Collection objs, boolean fgOnly,
181: OpCallbacks call);
182:
183: /**
184: * Make the given instance embedded.
185: *
186: * @param obj the instance to embed; may be null to create a new instance
187: * @param id the id to give the embedded state manager; may be
188: * null for default
189: * @param owner the owning state manager
190: * @param ownerMeta the value in which the object is embedded
191: * @return the state manager for the embedded instance
192: */
193: public OpenJPAStateManager embed(Object obj, Object id,
194: OpenJPAStateManager owner, ValueMetaData ownerMeta);
195:
196: /**
197: * Return the application or datastore identity class the given persistent
198: * class uses for object ids.
199: */
200: public Class getObjectIdType(Class cls);
201:
202: /**
203: * Create a new object id instance from the given value.
204: *
205: * @param cls the persitent class that uses this identity value
206: * @param val an object id instance, stringified object id, or primary
207: * key value
208: */
209: public Object newObjectId(Class cls, Object val);
210:
211: /**
212: * Return the set of classes that have been made persistent in the current
213: * transaction.
214: *
215: * @since 0.3.4
216: */
217: public Collection getPersistedTypes();
218:
219: /**
220: * Return the set of classes that have been deleted in the current
221: * transaction.
222: *
223: * @since 0.3.4
224: */
225: public Collection getDeletedTypes();
226:
227: /**
228: * Return the set of classes for objects that have been modified
229: * in the current transaction.
230: *
231: * @since 0.3.4
232: */
233: public Collection getUpdatedTypes();
234:
235: /**
236: * Return a list of all managed instances.
237: */
238: public Collection getManagedObjects();
239:
240: /**
241: * Return a list of current transaction instances.
242: */
243: public Collection getTransactionalObjects();
244:
245: /**
246: * Return a list of instances which will become transactional upon
247: * the next transaction.
248: */
249: public Collection getPendingTransactionalObjects();
250:
251: /**
252: * Return a list of current dirty instances.
253: */
254: public Collection getDirtyObjects();
255:
256: /**
257: * Whether to maintain the order in which objects are dirtied for
258: * {@link #getDirtyObjects}. Default is the store manager's decision.
259: */
260: public boolean getOrderDirtyObjects();
261:
262: /**
263: * Whether to maintain the order in which objects are dirtied for
264: * {@link #getDirtyObjects}. Default is the store manager's decision.
265: */
266: public void setOrderDirtyObjects(boolean order);
267:
268: /**
269: * Return the state manager for the given instance. Includes objects
270: * made persistent in the current transaction. If <code>obj</code> is not
271: * a managed type or is managed by another context, throw an exception.
272: */
273: public OpenJPAStateManager getStateManager(Object obj);
274:
275: /**
276: * Return the lock level of the specified object.
277: */
278: public int getLockLevel(Object obj);
279:
280: /**
281: * Returns the current version indicator for <code>o</code>.
282: */
283: public Object getVersion(Object obj);
284:
285: /**
286: * Return whether the given object is dirty.
287: */
288: public boolean isDirty(Object obj);
289:
290: /**
291: * Return whether the given object is transactional.
292: */
293: public boolean isTransactional(Object obj);
294:
295: /**
296: * Make the given object transactional.
297: *
298: * @param pc instance to make transactional
299: * @param updateVersion if true, the instance's version will be
300: * incremented at the next flush
301: */
302: public void transactional(Object pc, boolean updateVersion,
303: OpCallbacks call);
304:
305: /**
306: * Make the given objects transactional.
307: *
308: * @param objs instances to make transactional
309: * @param updateVersion if true, the instance's version will be
310: * incremented at the next flush
311: */
312: public void transactionalAll(Collection objs,
313: boolean updateVersion, OpCallbacks call);
314:
315: /**
316: * Make the given object nontransactional.
317: */
318: public void nontransactional(Object pc, OpCallbacks call);
319:
320: /**
321: * Make the given objects nontransactional.
322: */
323: public void nontransactionalAll(Collection objs, OpCallbacks call);
324:
325: /**
326: * Return whether the given object is persistent.
327: */
328: public boolean isPersistent(Object obj);
329:
330: /**
331: * Return whether the given object is a newly-created instance registered
332: * with <code>broker</code>.
333: */
334: public boolean isNew(Object obj);
335:
336: /**
337: * Return whether the given object is deleted.
338: */
339: public boolean isDeleted(Object obj);
340:
341: /**
342: * Return the oid of the given instance.
343: */
344: public Object getObjectId(Object obj);
345:
346: /**
347: * Detach mode constant to determine which fields are part of the
348: * detached graph. Defaults to {@link DetachState#DETACH_LOADED}.
349: */
350: public int getDetachState();
351:
352: /**
353: * Detach mode constant to determine which fields are part of the
354: * detached graph. Defaults to {@link DetachState#DETACH_LOADED}.
355: */
356: public void setDetachState(int mode);
357:
358: /**
359: * Whether objects accessed during this transaction will be added to the
360: * store cache. Defaults to true.
361: *
362: * @since 0.3.4
363: */
364: public boolean getPopulateDataCache();
365:
366: /**
367: * Whether to populate the store cache with objects used by this
368: * transaction. Defaults to true.
369: *
370: * @since 0.3.4
371: */
372: public void setPopulateDataCache(boolean cache);
373:
374: /**
375: * Whether memory usage is reduced during this transaction at the expense
376: * of tracking changes at the type level instead of the instance level,
377: * resulting in more aggressive cache invalidation.
378: *
379: * @since 1.0.0
380: */
381: public boolean isTrackChangesByType();
382:
383: /**
384: * If a large number of objects will be created, modified, or deleted
385: * during this transaction setting this option to true will reduce memory
386: * usage if you perform periodic flushes by tracking changes at the type
387: * level instead of the instance level, resulting in more aggressive cache
388: * invalidation. Upon transaction commit the data cache will have to
389: * more aggressively flush objects. The store cache will have to flush
390: * instances of objects for each class of object modified during the
391: * transaction. A side benefit of large transaction mode is that smaller
392: * update messages can be used for
393: * {@link org.apache.openjpa.event.RemoteCommitEvent}s. Defaults to false.
394: *
395: * @since 1.0.0
396: */
397: public void setTrackChangesByType(boolean largeTransaction);
398:
399: /**
400: * Whether this context is using managed transactions.
401: */
402: public boolean isManaged();
403:
404: /**
405: * Whether a logical transaction is active.
406: */
407: public boolean isActive();
408:
409: /**
410: * Whether a data store transaction is active.
411: */
412: public boolean isStoreActive();
413:
414: /**
415: * Begin a data store transaction.
416: */
417: public void beginStore();
418:
419: /**
420: * Whether the broker has a dedicated connection based on the configured
421: * connection retain mode and transaction status.
422: */
423: public boolean hasConnection();
424:
425: /**
426: * Return the connection in use by the context, or a new connection if none.
427: */
428: public Object getConnection();
429:
430: /**
431: * Synchronizes on an internal lock if the
432: * <code>Multithreaded</code> flag is set to true. Make sure to call
433: * {@link #unlock} in a finally clause of the same method.
434: */
435: public void lock();
436:
437: /**
438: * Releases the internal lock.
439: */
440: public void unlock();
441: }
|