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.Collection;
022: import javax.transaction.Synchronization;
023:
024: import org.apache.openjpa.ee.ManagedRuntime;
025: import org.apache.openjpa.event.CallbackModes;
026: import org.apache.openjpa.event.LifecycleEventManager;
027: import org.apache.openjpa.lib.util.Closeable;
028: import org.apache.openjpa.meta.ClassMetaData;
029: import org.apache.openjpa.meta.FieldMetaData;
030: import org.apache.openjpa.meta.ValueMetaData;
031: import org.apache.openjpa.util.RuntimeExceptionTranslator;
032:
033: /**
034: * The broker is the primary interface into the OpenJPA runtime. Each broker
035: * maintains an independent object cache and an independent transactional
036: * context.
037: *
038: * @since 0.4.0
039: * @author Abe White
040: */
041: public interface Broker extends Synchronization, Closeable,
042: StoreContext, ConnectionRetainModes, DetachState, LockLevels,
043: RestoreState, AutoClear, AutoDetach, CallbackModes {
044:
045: /**
046: * Set the broker's behavior for implicit actions such as flushing,
047: * automatic detachment, and exceptions thrown by managed instances outside
048: * a broker operation. A broker's implicit behavior can only be set once;
049: * after the first invocation with non-null arguments,
050: * subsequent invocations of this method are ignored.
051: */
052: public void setImplicitBehavior(OpCallbacks call,
053: RuntimeExceptionTranslator ex);
054:
055: /**
056: * Return the factory that produced this broker.
057: */
058: public BrokerFactory getBrokerFactory();
059:
060: /**
061: * Return the connection retain mode for this broker.
062: */
063: public int getConnectionRetainMode();
064:
065: /**
066: * Return the managed runtime in use.
067: */
068: public ManagedRuntime getManagedRuntime();
069:
070: /**
071: * Return the inverse manager in use.
072: *
073: * @since 0.3.2
074: */
075: public InverseManager getInverseManager();
076:
077: /**
078: * Whether the broker or its managed instances are used in a multithreaded
079: * environment.
080: */
081: public boolean getMultithreaded();
082:
083: /**
084: * Whether the broker or its managed instances are used in a multithreaded
085: * environment.
086: */
087: public void setMultithreaded(boolean multi);
088:
089: /**
090: * Whether to take into account changes in the transaction when executing
091: * a query or iterating an extent.
092: */
093: public boolean getIgnoreChanges();
094:
095: /**
096: * Whether to take into account changes in the transaction when executing
097: * a query or iterating an extent.
098: */
099: public void setIgnoreChanges(boolean ignore);
100:
101: /**
102: * Whether to allow nontransactional access to persistent state.
103: */
104: public boolean getNontransactionalRead();
105:
106: /**
107: * Whether to allow nontransactional access to persistent state.
108: */
109: public void setNontransactionalRead(boolean read);
110:
111: /**
112: * Whether to allow nontransactional changes to persistent state.
113: */
114: public boolean getNontransactionalWrite();
115:
116: /**
117: * Whether to allow nontransactional changes to persistent state.
118: */
119: public void setNontransactionalWrite(boolean write);
120:
121: /**
122: * Whether to restore an object's original state on rollback.
123: */
124: public int getRestoreState();
125:
126: /**
127: * Whether to restore an object's original state on rollback.
128: */
129: public void setRestoreState(int restore);
130:
131: /**
132: * Whether to use optimistic transactional semantics.
133: */
134: public boolean getOptimistic();
135:
136: /**
137: * Whether to use optimistic transactional semantics.
138: */
139: public void setOptimistic(boolean opt);
140:
141: /**
142: * Whether objects retain their persistent state on transaction commit.
143: */
144: public boolean getRetainState();
145:
146: /**
147: * Whether objects retain their persistent state on transaction commit.
148: */
149: public void setRetainState(boolean retain);
150:
151: /**
152: * Whether objects clear when entering transactions.
153: */
154: public int getAutoClear();
155:
156: /**
157: * Whether objects clear when entering transactions.
158: */
159: public void setAutoClear(int clear);
160:
161: /**
162: * Whether to check for a global transaction upon every managed,
163: * non-transactional operation. Defaults to false.
164: */
165: public boolean getSyncWithManagedTransactions();
166:
167: /**
168: * Whether to check for a global transaction upon every managed,
169: * non-transactional operation. Defaults to false.
170: */
171: public void setSyncWithManagedTransactions(boolean resync);
172:
173: /**
174: * Bit flags marked in {@link AutoDetach} which indicate when persistent
175: * managed objects should be automatically detached in-place.
176: */
177: public int getAutoDetach();
178:
179: /**
180: * Bit flags marked in {@link AutoDetach} which indicate when persistent
181: * managed objects should be automatically detached in-place.
182: */
183: public void setAutoDetach(int flags);
184:
185: /**
186: * Bit flags marked in {@link AutoDetach} which indicate when persistent
187: * managed objects should be automatically detached in-place.
188: */
189: public void setAutoDetach(int flag, boolean on);
190:
191: /**
192: * Whether to treat relations to detached instances during persist
193: * operations as new or as pseudo-hollow instances.
194: */
195: public boolean isDetachedNew();
196:
197: /**
198: * Whether to treat relations to detached instances as new.
199: */
200: public void setDetachedNew(boolean isNew);
201:
202: /**
203: * Whether to also evict an object from the store cache when it is
204: * evicted through this broker.
205: */
206: public boolean getEvictFromDataCache();
207:
208: /**
209: * Whether to also evict an object from the store cache when it is
210: * evicted through this broker.
211: */
212: public void setEvictFromDataCache(boolean evict);
213:
214: /**
215: * Put the specified key-value pair into the map of user objects. Use
216: * a value of null to remove the key.
217: *
218: * @since 0.3.2
219: */
220: public Object putUserObject(Object key, Object val);
221:
222: /**
223: * Get the value for the specified key from the map of user objects.
224: *
225: * @since 0.3.2
226: */
227: public Object getUserObject(Object key);
228:
229: /**
230: * Register a listener for transaction-related events.
231: *
232: * @since 0.2.5
233: */
234: public void addTransactionListener(Object listener);
235:
236: /**
237: * Remove a listener for transaction-related events.
238: *
239: * @since 0.2.5
240: */
241: public void removeTransactionListener(Object listener);
242:
243: /**
244: * The callback mode for handling exceptions from transaction event
245: * listeners.
246: */
247: public int getTransactionListenerCallbackMode();
248:
249: /**
250: * The callback mode for handling exceptions from transaction event
251: * listeners.
252: */
253: public void setTransactionListenerCallbackMode(int mode);
254:
255: /**
256: * Register a listener for lifecycle-related events on the specified
257: * classes. If the classes are null, all events will be propagated to
258: * the listener.
259: *
260: * @since 0.3.3
261: */
262: public void addLifecycleListener(Object listener, Class[] classes);
263:
264: /**
265: * Remove a listener for lifecycle-related events.
266: *
267: * @since 0.3.3
268: */
269: public void removeLifecycleListener(Object listener);
270:
271: /**
272: * Return the lifecycle event manager associated with the broker.
273: */
274: public LifecycleEventManager getLifecycleEventManager();
275:
276: /**
277: * The callback mode for handling exceptions from lifecycle event listeners.
278: */
279: public int getLifecycleListenerCallbackMode();
280:
281: /**
282: * The callback mode for handling exceptions from lifecycle event listeners.
283: */
284: public void setLifecycleListenerCallbackMode(int mode);
285:
286: /**
287: * Begin a transaction.
288: */
289: public void begin();
290:
291: /**
292: * Commit the current transaction.
293: */
294: public void commit();
295:
296: /**
297: * Rollback the current transaction.
298: */
299: public void rollback();
300:
301: /**
302: * Attempt to synchronize with a current managed transaction, returning
303: * true if successful, false if no managed transaction is active.
304: */
305: public boolean syncWithManagedTransaction();
306:
307: /**
308: * Issue a commit and then start a new transaction. This is identical to:
309: * <pre> broker.commit (); broker.begin ();
310: * </pre> except that the broker's internal atomic lock is utilized,
311: * so this method can be safely executed from multiple threads.
312: *
313: * @see #commit()
314: * @see #begin()
315: * @since 0.2.4
316: */
317: public void commitAndResume();
318:
319: /**
320: * Issue a rollback and then start a new transaction. This is identical to:
321: * <pre> broker.rollback (); broker.begin ();
322: * </pre> except that the broker's internal atomic lock is utilized,
323: * so this method can be safely executed from multiple threads.
324: *
325: * @see #rollback()
326: * @see #begin()
327: * @since 0.2.4
328: */
329: public void rollbackAndResume();
330:
331: /**
332: * Return whether the current transaction has been marked for rollback.
333: */
334: public boolean getRollbackOnly();
335:
336: /**
337: * Mark the current transaction for rollback.
338: */
339: public void setRollbackOnly();
340:
341: /**
342: * Mark the current transaction for rollback with the specified cause
343: * of the rollback.
344: *
345: * @since 0.9.7
346: */
347: public void setRollbackOnly(Throwable cause);
348:
349: /**
350: * Returns the Throwable that caused the transaction to be
351: * marked for rollback.
352: *
353: * @return the Throwable, or null if none was given
354: *
355: * @since 0.9.7
356: */
357: public Throwable getRollbackCause();
358:
359: /**
360: * Set a transactional savepoint where operations after this savepoint
361: * will be rolled back.
362: */
363: public void setSavepoint(String name);
364:
365: /**
366: * Rollback the current transaction to the last savepoint.
367: * Savepoints set after this one will become invalid.
368: */
369: public void rollbackToSavepoint();
370:
371: /**
372: * Rollback the current transaction to the given savepoint name.
373: * Savepoints set after this one will become invalid.
374: */
375: public void rollbackToSavepoint(String name);
376:
377: /**
378: * Release the last set savepoint and any resources associated with it.
379: * The given savepoint and any set after it will become invalid.
380: */
381: public void releaseSavepoint();
382:
383: /**
384: * Release the savepoint and any resources associated with it.
385: * The given savepoint and any set after it will become invalid.
386: */
387: public void releaseSavepoint(String name);
388:
389: /**
390: * Flush all transactional instances to the data store. This method may
391: * set the rollback only flag on the current transaction if it encounters
392: * an error.
393: *
394: * @since 0.2.5
395: */
396: public void flush();
397:
398: /**
399: * Run pre-flush actions on transactional objects, including
400: * persistence-by-reachability, inverse relationship management,
401: * deletion of dependent instances, and instance callbacks.
402: * Transaction listeners are not invoked.
403: *
404: * @since 0.3.3
405: */
406: public void preFlush();
407:
408: /**
409: * Validate the changes made in this transaction, reporting any optimistic
410: * violations, constraint violations, etc. In a datastore transaction or
411: * a flushed optimistic transaction, this method will act just like
412: * {@link #flush}. In an optimistic transaction that has not yet begun a
413: * datastore-level transaction, however, it will only report exceptions
414: * that would occur on flush, without retaining any datastore resources.
415: */
416: public void validateChanges();
417:
418: /**
419: * Persist the given object.
420: */
421: public void persist(Object obj, OpCallbacks call);
422:
423: /**
424: * Persist the given objects.
425: */
426: public void persistAll(Collection objs, OpCallbacks call);
427:
428: /**
429: * Make the given instance persistent. Unlike other persist operations,
430: * this method does <b>not</b> immediately cascade to fields marked
431: * {@link ValueMetaData#CASCADE_IMMEDIATE}.
432: *
433: * @param pc the instance to persist
434: * @param id the id to give the state manager; may be null for default
435: * @return the state manager for the newly persistent instance
436: */
437: public OpenJPAStateManager persist(Object pc, Object id,
438: OpCallbacks call);
439:
440: /**
441: * Delete the given object.
442: */
443: public void delete(Object pc, OpCallbacks call);
444:
445: /**
446: * Delete the given objects.
447: */
448: public void deleteAll(Collection objs, OpCallbacks call);
449:
450: /**
451: * Release the given object from management. This operation is not
452: * recursive.
453: */
454: public void release(Object pc, OpCallbacks call);
455:
456: /**
457: * Release the given objects from management. This operation is not
458: * recursive.
459: */
460: public void releaseAll(Collection objs, OpCallbacks call);
461:
462: /**
463: * Refresh the state of the given object.
464: */
465: public void refresh(Object pc, OpCallbacks call);
466:
467: /**
468: * Refresh the state of the given objects.
469: */
470: public void refreshAll(Collection objs, OpCallbacks call);
471:
472: /**
473: * Evict the given object.
474: */
475: public void evict(Object pc, OpCallbacks call);
476:
477: /**
478: * Evict the given objects.
479: */
480: public void evictAll(Collection objs, OpCallbacks call);
481:
482: /**
483: * Evict all clean objects.
484: */
485: public void evictAll(OpCallbacks call);
486:
487: /**
488: * Evict all persistent-clean and persistent-nontransactional
489: * instances in the given {@link Extent}.
490: */
491: public void evictAll(Extent extent, OpCallbacks call);
492:
493: /**
494: * Detach all objects in place. A flush will be performed before
495: * detaching the entities.
496: */
497: public void detachAll(OpCallbacks call);
498:
499: /**
500: * Detach all objects in place, with the option of performing a
501: * flush before doing the detachment.
502: * @param call Persistence operation callbacks
503: * @param flush boolean value to indicate whether to perform a
504: * flush before detaching the entities (true, do the flush;
505: * false, don't do the flush)
506: */
507: public void detachAll(OpCallbacks call, boolean flush);
508:
509: /**
510: * Detach the specified object from the broker.
511: *
512: * @param pc the instance to detach
513: * @return the detached instance
514: */
515: public Object detach(Object pc, OpCallbacks call);
516:
517: /**
518: * Detach the specified objects from the broker. The objects returned can
519: * be manipulated and re-attached with {@link #attachAll}. The
520: * detached instances will be unmanaged copies of the specified parameters,
521: * and are suitable for serialization and manipulation outside
522: * of a OpenJPA environment. When detaching instances, only fields
523: * in the current {@link FetchConfiguration} will be traversed. Thus,
524: * to detach a graph of objects, relations to other persistent
525: * instances must either be in the <code>default-fetch-group</code>,
526: * or in the current custom {@link FetchConfiguration}.
527: *
528: * @param objs the instances to detach
529: * @return the detached instances
530: */
531: public Object[] detachAll(Collection objs, OpCallbacks call);
532:
533: /**
534: * Import the specified detached object into the broker.
535: *
536: * @param pc instance to import
537: * @return the re-attached instance
538: * @param copyNew whether to copy new instances
539: */
540: public Object attach(Object pc, boolean copyNew, OpCallbacks call);
541:
542: /**
543: * Import the specified objects into the broker. Instances that were
544: * previously detached from this or another broker will have their
545: * changed merged into the persistent instances. Instances that
546: * are new will be persisted as new instances.
547: *
548: * @param objs array of instances to import
549: * @return the re-attached instances
550: * @param copyNew whether to copy new instances
551: */
552: public Object[] attachAll(Collection objs, boolean copyNew,
553: OpCallbacks call);
554:
555: /**
556: * Create a new instance of type <code>cls</code>. If <code>cls</code> is
557: * an interface or an abstract class whose abstract methods follow the
558: * JavaBeans convention, this method will create a concrete implementation
559: * according to the metadata that defines the class.
560: * Otherwise, if <code>cls</code> is a managed type, this will return an
561: * instance of the specified class.
562: *
563: * @throws IllegalArgumentException if <code>cls</code> is not a managed
564: * type or interface.
565: */
566: public Object newInstance(Class cls);
567:
568: /**
569: * Returns <code>true</code> if <code>obj</code> is a detached object
570: * (one that can be reattached to a {@link Broker} via a call to
571: * {@link Broker#attach}); otherwise returns <code>false</code>.
572: */
573: public boolean isDetached(Object obj);
574:
575: /**
576: * Return an extent of the given class, optionally including subclasses.
577: */
578: public Extent newExtent(Class cls, boolean subs);
579:
580: /**
581: * Create a new query from the given data, with the given candidate class
582: * and language.
583: */
584: public Query newQuery(String language, Class cls, Object query);
585:
586: /**
587: * Create a new query in the given language.
588: */
589: public Query newQuery(String language, Object query);
590:
591: /**
592: * Returns a {@link Seq} for the datastore identity values of the
593: * specified persistent class, or null if the class' identity cannot be
594: * represented as a sequence.
595: */
596: public Seq getIdentitySequence(ClassMetaData meta);
597:
598: /**
599: * Returns a {@link Seq} for the generated values of the specified
600: * field, or null if the field is not generated.
601: */
602: public Seq getValueSequence(FieldMetaData fmd);
603:
604: /**
605: * Ensure that the given instance is locked at the given lock level.
606: *
607: * @param pc the object to lock
608: * @param level the lock level to use
609: * @param timeout the number of milliseconds to wait for the lock before
610: * giving up, or -1 for no limit
611: * @since 0.3.1
612: */
613: public void lock(Object pc, int level, int timeout, OpCallbacks call);
614:
615: /**
616: * Ensure that the given instance is locked at the current lock level, as
617: * set in the {@link FetchConfiguration} for the broker.
618: *
619: * @since 0.3.1
620: */
621: public void lock(Object pc, OpCallbacks call);
622:
623: /**
624: * Ensure that the given instances are locked at the given lock level.
625: *
626: * @param objs the objects to lock
627: * @param level the lock level to use
628: * @param timeout the number of milliseconds to wait for the lock before
629: * giving up, or -1 for no limit
630: * @since 0.3.1
631: */
632: public void lockAll(Collection objs, int level, int timeout,
633: OpCallbacks call);
634:
635: /**
636: * Ensure that the given instances are locked at the current lock level, as
637: * set in the {@link FetchConfiguration} for the broker.
638: *
639: * @since 0.3.1
640: */
641: public void lockAll(Collection objs, OpCallbacks call);
642:
643: /**
644: * Cancel all pending data store statements. If statements are cancelled
645: * while a flush is in progress, the transaction rollback only flag will
646: * be set.
647: *
648: * @return true if any statements were cancelled, false otherwise
649: * @since 0.3.1
650: */
651: public boolean cancelAll();
652:
653: /**
654: * Mark the given class as dirty within the current transaction.
655: *
656: * @since 0.3.0
657: */
658: public void dirtyType(Class cls);
659:
660: /**
661: * Begin a logical operation. This indicates to the broker the
662: * granularity of an operation which may require pre/post operation
663: * side-effects, such as non-tx detach.
664: * Will lock the broker until the {@link #endOperation} is called.
665: *
666: * @param syncTrans whether instances may be loaded/modified during
667: * this operation requiring a re-check of global tx
668: * @return whether this is the outermost operation on the stack
669: */
670: public boolean beginOperation(boolean syncTrans);
671:
672: /**
673: * End a logical operation. This indicates to the broker the
674: * granularity of an operation which may require pre/post operation
675: * side-effects, such as non-tx detach. Unlocks the given broker.
676: *
677: * @return whether this is the outermost operation on the stack
678: */
679: public boolean endOperation();
680:
681: /**
682: * Whether the broker is closed.
683: */
684: public boolean isClosed();
685:
686: /**
687: * Whether {@link #close} has been invoked, though the broker might
688: * remain open until the current managed transaction completes.
689: */
690: public boolean isCloseInvoked();
691:
692: /**
693: * Close the broker.
694: */
695: public void close();
696:
697: /**
698: * Throw an exception if this broker has been closed.
699: */
700: public void assertOpen();
701:
702: /**
703: * Throw an exception if there is no active transaction.
704: */
705: public void assertActiveTransaction();
706:
707: /**
708: * Throw an exception if there is no transaction active and
709: * nontransactional reading is not enabled.
710: */
711: public void assertNontransactionalRead();
712:
713: /**
714: * Throw an exception if a write operation is not permitted (there is
715: * no active transaction and nontransactional writing is not enabled).
716: */
717: public void assertWriteOperation();
718: }
|