org.apache.openjpa.kernel
Interface Broker

All Superinterfaces:

AutoClear, AutoDetach, CallbackModes, Closeable, ConnectionRetainModes, DetachState, LockLevels, RestoreState, StoreContext, Synchronization

All Known Subinterfaces:

DistributedBroker

All Known Implementing Classes:

BrokerImpl, DelegatingBroker, DistributedBrokerImpl, FinalizingBrokerImpl

public interface Broker
extends Synchronization, Closeable, StoreContext, ConnectionRetainModes, DetachState, LockLevels, RestoreState, AutoClear, AutoDetach, CallbackModes

The broker is the primary interface into the OpenJPA runtime. Each broker maintains an independent object cache and an independent transactional context.

Since:

0.4.0

Author:

Abe White

Field Summary

Fields inherited from interface org.apache.openjpa.kernel.StoreContext

EXCLUDE_ALL, OID_ALLOW_NEW, OID_COPY, OID_NODELETED, OID_NOVALIDATE

Fields inherited from interface org.apache.openjpa.kernel.ConnectionRetainModes

CONN_RETAIN_ALWAYS, CONN_RETAIN_DEMAND, CONN_RETAIN_TRANS

Fields inherited from interface org.apache.openjpa.kernel.DetachState

DETACH_ALL, DETACH_FETCH_GROUPS, DETACH_FGS, DETACH_LOADED

Fields inherited from interface org.apache.openjpa.kernel.LockLevels

LOCK_NONE, LOCK_READ, LOCK_WRITE

Fields inherited from interface org.apache.openjpa.kernel.RestoreState

RESTORE_ALL, RESTORE_IMMUTABLE, RESTORE_NONE

Fields inherited from interface org.apache.openjpa.kernel.AutoClear

CLEAR_ALL, CLEAR_DATASTORE

Fields inherited from interface org.apache.openjpa.kernel.AutoDetach

DETACH_CLOSE, DETACH_COMMIT, DETACH_NONE, DETACH_NONTXREAD, DETACH_ROLLBACK, names, values

Fields inherited from interface org.apache.openjpa.event.CallbackModes

CALLBACK_FAIL_FAST, CALLBACK_IGNORE, CALLBACK_LOG, CALLBACK_RETHROW, CALLBACK_ROLLBACK

Method Summary

void	addLifecycleListener(Object listener, Class[] classes) Register a listener for lifecycle-related events on the specified classes.
void	addTransactionListener(Object listener) Register a listener for transaction-related events.
void	assertActiveTransaction() Throw an exception if there is no active transaction.
void	assertNontransactionalRead() Throw an exception if there is no transaction active and nontransactional reading is not enabled.
void	assertOpen() Throw an exception if this broker has been closed.
void	assertWriteOperation() Throw an exception if a write operation is not permitted (there is no active transaction and nontransactional writing is not enabled).
Object	attach(Object pc, boolean copyNew, OpCallbacks call) Import the specified detached object into the broker.
Object[]	attachAll(Collection objs, boolean copyNew, OpCallbacks call) Import the specified objects into the broker.
void	begin() Begin a transaction.
boolean	beginOperation(boolean syncTrans) Begin a logical operation.
boolean	cancelAll() Cancel all pending data store statements.
void	close() Close the broker.
void	commit() Commit the current transaction.
void	commitAndResume() Issue a commit and then start a new transaction.
void	delete(Object pc, OpCallbacks call) Delete the given object.
void	deleteAll(Collection objs, OpCallbacks call) Delete the given objects.
Object	detach(Object pc, OpCallbacks call) Detach the specified object from the broker.
Object[]	detachAll(Collection objs, OpCallbacks call) Detach the specified objects from the broker.
void	detachAll(OpCallbacks call) Detach all objects in place.
void	detachAll(OpCallbacks call, boolean flush) Detach all objects in place, with the option of performing a flush before doing the detachment.
void	dirtyType(Class cls) Mark the given class as dirty within the current transaction.
boolean	endOperation() End a logical operation.
void	evict(Object pc, OpCallbacks call) Evict the given object.
void	evictAll(Collection objs, OpCallbacks call) Evict the given objects.
void	evictAll(Extent extent, OpCallbacks call) Evict all persistent-clean and persistent-nontransactional instances in the given Extent.
void	evictAll(OpCallbacks call) Evict all clean objects.
void	flush() Flush all transactional instances to the data store.
int	getAutoClear() Whether objects clear when entering transactions.
int	getAutoDetach() Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.
BrokerFactory	getBrokerFactory() Return the factory that produced this broker.
boolean	getCachePreparedQuery() Affirms if this receiver is caching prepared queries.
int	getConnectionRetainMode() Return the connection retain mode for this broker.
boolean	getEvictFromDataCache() Whether to also evict an object from the store cache when it is evicted through this broker.
Seq	getIdentitySequence(ClassMetaData meta) Returns a Seq for the datastore identity values of the specified persistent class, or null if the class' identity cannot be represented as a sequence.
boolean	getIgnoreChanges() Whether to take into account changes in the transaction when executing a query or iterating an extent.
InverseManager	getInverseManager() Return the inverse manager in use.
LifecycleEventManager	getLifecycleEventManager() Return the lifecycle event manager associated with the broker.
int	getLifecycleListenerCallbackMode() The callback mode for handling exceptions from lifecycle event listeners.
ManagedRuntime	getManagedRuntime() Return the managed runtime in use.
boolean	getMultithreaded() Whether the broker or its managed instances are used in a multithreaded environment.
boolean	getNontransactionalRead() Whether to allow nontransactional access to persistent state.
boolean	getNontransactionalWrite() Whether to allow nontransactional changes to persistent state.
boolean	getOptimistic() Whether to use optimistic transactional semantics.
Map<String,Object>	getProperties() Retrieve the current properties for this broker Some of these properties may have been changed from the original configuration.
int	getRestoreState() Whether to restore an object's original state on rollback.
boolean	getRetainState() Whether objects retain their persistent state on transaction commit.
Throwable	getRollbackCause() Returns the Throwable that caused the transaction to be marked for rollback.
boolean	getRollbackOnly() Return whether the current transaction has been marked for rollback.
Set<String>	getSupportedProperties() Return the supported properties for this broker as property keys.
boolean	getSyncWithManagedTransactions() Whether to check for a global transaction upon every managed, non-transactional operation.
int	getTransactionListenerCallbackMode() The callback mode for handling exceptions from transaction event listeners.
Collection<Object>	getTransactionListeners() Gets an umodifiable collection of currently registered lsteners.
Object	getUserObject(Object key) Get the value for the specified key from the map of user objects.
Seq	getValueSequence(FieldMetaData fmd) Returns a Seq for the generated values of the specified field, or null if the field is not generated.
boolean	isClosed() Whether the broker is closed.
boolean	isCloseInvoked() Whether close() has been invoked, though the broker might remain open until the current managed transaction completes.
boolean	isDetached(Object obj) Returns true if obj is a detached object (one that can be reattached to a Broker via a call to attach(java.lang.Object, boolean, org.apache.openjpa.kernel.OpCallbacks)); otherwise returns false.
boolean	isDetachedNew() Whether to treat relations to detached instances during persist operations as new or as pseudo-hollow instances.
void	lock(Object pc, int level, int timeout, OpCallbacks call) Ensure that the given instance is locked at the given lock level.
void	lock(Object pc, OpCallbacks call) Ensure that the given instance is locked at the current lock level, as set in the FetchConfiguration for the broker.
void	lockAll(Collection objs, int level, int timeout, OpCallbacks call) Ensure that the given instances are locked at the given lock level.
void	lockAll(Collection objs, OpCallbacks call) Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the broker.
Extent	newExtent(Class cls, boolean subs) Return an extent of the given class, optionally including subclasses.
Object	newInstance(Class cls) Create a new instance of type cls.
Query	newQuery(String language, Class cls, Object query) Create a new query from the given data, with the given candidate class and language.
Query	newQuery(String language, Object query) Create a new query in the given language.
OpenJPAStateManager	persist(Object pc, Object id, OpCallbacks call) Make the given instance persistent.
void	persist(Object obj, OpCallbacks call) Persist the given object.
void	persistAll(Collection objs, OpCallbacks call) Persist the given objects.
void	preFlush() Run pre-flush actions on transactional objects, including persistence-by-reachability, inverse relationship management, deletion of dependent instances, and instance callbacks.
Object	putUserObject(Object key, Object val) Put the specified key-value pair into the map of user objects.
void	refresh(Object pc, OpCallbacks call) Refresh the state of the given object.
void	refreshAll(Collection objs, OpCallbacks call) Refresh the state of the given objects.
void	release(Object pc, OpCallbacks call) Release the given object from management.
void	releaseAll(Collection objs, OpCallbacks call) Release the given objects from management.
void	releaseSavepoint() Release the last set savepoint and any resources associated with it.
void	releaseSavepoint(String name) Release the savepoint and any resources associated with it.
void	removeLifecycleListener(Object listener) Remove a listener for lifecycle-related events.
void	removeTransactionListener(Object listener) Remove a listener for transaction-related events.
void	rollback() Rollback the current transaction.
void	rollbackAndResume() Issue a rollback and then start a new transaction.
void	rollbackToSavepoint() Rollback the current transaction to the last savepoint.
void	rollbackToSavepoint(String name) Rollback the current transaction to the given savepoint name.
void	setAutoClear(int clear) Whether objects clear when entering transactions.
void	setAutoDetach(int flags) Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.
void	setAutoDetach(int flag, boolean on) Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.
void	setCachePreparedQuery(boolean flag) Sets whether this receiver will cache prepared queries during its lifetime.
void	setDetachedNew(boolean isNew) Whether to treat relations to detached instances as new.
void	setEvictFromDataCache(boolean evict) Whether to also evict an object from the store cache when it is evicted through this broker.
void	setIgnoreChanges(boolean ignore) Whether to take into account changes in the transaction when executing a query or iterating an extent.
void	setImplicitBehavior(OpCallbacks call, RuntimeExceptionTranslator ex) Set the broker's behavior for implicit actions such as flushing, automatic detachment, and exceptions thrown by managed instances outside a broker operation.
void	setLifecycleListenerCallbackMode(int mode) The callback mode for handling exceptions from lifecycle event listeners.
void	setMultithreaded(boolean multi) Whether the broker or its managed instances are used in a multithreaded environment.
void	setNontransactionalRead(boolean read) Whether to allow nontransactional access to persistent state.
void	setNontransactionalWrite(boolean write) Whether to allow nontransactional changes to persistent state.
void	setOptimistic(boolean opt) Whether to use optimistic transactional semantics.
void	setRestoreState(int restore) Whether to restore an object's original state on rollback.
void	setRetainState(boolean retain) Whether objects retain their persistent state on transaction commit.
void	setRollbackOnly() Mark the current transaction for rollback.
void	setRollbackOnly(Throwable cause) Mark the current transaction for rollback with the specified cause of the rollback.
void	setSavepoint(String name) Set a transactional savepoint where operations after this savepoint will be rolled back.
void	setSyncWithManagedTransactions(boolean resync) Whether to check for a global transaction upon every managed, non-transactional operation.
void	setTransactionListenerCallbackMode(int mode) The callback mode for handling exceptions from transaction event listeners.
boolean	syncWithManagedTransaction() Attempt to synchronize with a current managed transaction, returning true if successful, false if no managed transaction is active.
void	validateChanges() Validate the changes made in this transaction, reporting any optimistic violations, constraint violations, etc.

Methods inherited from interface javax.transaction.Synchronization

afterCompletion, beforeCompletion

Methods inherited from interface org.apache.openjpa.kernel.StoreContext

beginStore, embed, extentIterator, find, find, findAll, findAll, findCached, getAllowReferenceToSiblingContext, getBroker, getClassLoader, getConfiguration, getConnection, getConnectionFactory, getConnectionFactory2, getConnectionFactory2Name, getConnectionFactoryName, getConnectionPassword, getConnectionUserName, getDeletedTypes, getDetachState, getDirtyObjects, getFetchConfiguration, getLockLevel, getLockManager, getManagedObjects, getObjectId, getObjectIdType, getOrderDirtyObjects, getPendingTransactionalObjects, getPersistedTypes, getPopulateDataCache, getPostLoadOnMerge, getStateManager, getStoreManager, getTransactionalObjects, getUpdatedTypes, getVersion, hasConnection, isActive, isCached, isDeleted, isDirty, isManaged, isNew, isPersistent, isStoreActive, isTrackChangesByType, isTransactional, lock, newObjectId, nontransactional, nontransactionalAll, popFetchConfiguration, pushFetchConfiguration, pushFetchConfiguration, retrieve, retrieveAll, setAllowReferenceToSiblingContext, setConnectionFactory2Name, setConnectionFactoryName, setDetachState, setOrderDirtyObjects, setPopulateDataCache, setPostLoadOnMerge, setTrackChangesByType, transactional, transactionalAll, unlock

Method Detail

setImplicitBehavior

void setImplicitBehavior(OpCallbacks call,
                         RuntimeExceptionTranslator ex)

Set the broker's behavior for implicit actions such as flushing, automatic detachment, and exceptions thrown by managed instances outside a broker operation. A broker's implicit behavior can only be set once; after the first invocation with non-null arguments, subsequent invocations of this method are ignored.

getBrokerFactory

BrokerFactory getBrokerFactory()

Return the factory that produced this broker.

getConnectionRetainMode

int getConnectionRetainMode()

Return the connection retain mode for this broker.

getManagedRuntime

ManagedRuntime getManagedRuntime()

Return the managed runtime in use.

getInverseManager

InverseManager getInverseManager()

Return the inverse manager in use.

Since:

0.3.2

getMultithreaded

boolean getMultithreaded()

Whether the broker or its managed instances are used in a multithreaded environment.

setMultithreaded

void setMultithreaded(boolean multi)

Whether the broker or its managed instances are used in a multithreaded environment.

getIgnoreChanges

boolean getIgnoreChanges()

Whether to take into account changes in the transaction when executing a query or iterating an extent.

setIgnoreChanges

void setIgnoreChanges(boolean ignore)

Whether to take into account changes in the transaction when executing a query or iterating an extent.

getNontransactionalRead

boolean getNontransactionalRead()

Whether to allow nontransactional access to persistent state.

setNontransactionalRead

void setNontransactionalRead(boolean read)

Whether to allow nontransactional access to persistent state.

getNontransactionalWrite

boolean getNontransactionalWrite()

Whether to allow nontransactional changes to persistent state.

setNontransactionalWrite

void setNontransactionalWrite(boolean write)

Whether to allow nontransactional changes to persistent state.

getRestoreState

int getRestoreState()

Whether to restore an object's original state on rollback.

setRestoreState

void setRestoreState(int restore)

Whether to restore an object's original state on rollback.

getOptimistic

boolean getOptimistic()

Whether to use optimistic transactional semantics.

setOptimistic

void setOptimistic(boolean opt)

Whether to use optimistic transactional semantics.

getRetainState

boolean getRetainState()

Whether objects retain their persistent state on transaction commit.

setRetainState

void setRetainState(boolean retain)

Whether objects retain their persistent state on transaction commit.

getAutoClear

int getAutoClear()

Whether objects clear when entering transactions.

setAutoClear

void setAutoClear(int clear)

Whether objects clear when entering transactions.

getSyncWithManagedTransactions

boolean getSyncWithManagedTransactions()

Whether to check for a global transaction upon every managed, non-transactional operation. Defaults to false.

setSyncWithManagedTransactions

void setSyncWithManagedTransactions(boolean resync)

Whether to check for a global transaction upon every managed, non-transactional operation. Defaults to false.

getAutoDetach

int getAutoDetach()

Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.

setAutoDetach

void setAutoDetach(int flags)

Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.

setAutoDetach

void setAutoDetach(int flag,
                   boolean on)

Bit flags marked in AutoDetach which indicate when persistent managed objects should be automatically detached in-place.

getProperties

Map<String,Object> getProperties()

Retrieve the current properties for this broker Some of these properties may have been changed from the original configuration.

Returns:

the changed properties

Since:

2.0.0

getSupportedProperties

Set<String> getSupportedProperties()

Return the supported properties for this broker as property keys. If a property has multiple keys, all keys will be returned.

Since:

2.0.0

isDetachedNew

boolean isDetachedNew()

Whether to treat relations to detached instances during persist operations as new or as pseudo-hollow instances.

setDetachedNew

void setDetachedNew(boolean isNew)

Whether to treat relations to detached instances as new.

getEvictFromDataCache

boolean getEvictFromDataCache()

Whether to also evict an object from the store cache when it is evicted through this broker.

setEvictFromDataCache

void setEvictFromDataCache(boolean evict)

Whether to also evict an object from the store cache when it is evicted through this broker.

putUserObject

Object putUserObject(Object key,
                     Object val)

Put the specified key-value pair into the map of user objects. Use a value of null to remove the key.

Since:

0.3.2

getUserObject

Object getUserObject(Object key)

Get the value for the specified key from the map of user objects.

Since:

0.3.2

addTransactionListener

void addTransactionListener(Object listener)

Register a listener for transaction-related events.

Since:

0.2.5

removeTransactionListener

void removeTransactionListener(Object listener)

Remove a listener for transaction-related events.

Since:

0.2.5

getTransactionListeners

Collection<Object> getTransactionListeners()

Gets an umodifiable collection of currently registered lsteners.

Since:

2.0.0

getTransactionListenerCallbackMode

int getTransactionListenerCallbackMode()

The callback mode for handling exceptions from transaction event listeners.

setTransactionListenerCallbackMode

void setTransactionListenerCallbackMode(int mode)

The callback mode for handling exceptions from transaction event listeners.

addLifecycleListener

void addLifecycleListener(Object listener,
                          Class[] classes)

Register a listener for lifecycle-related events on the specified classes. If the classes are null, all events will be propagated to the listener.

Since:

0.3.3

removeLifecycleListener

void removeLifecycleListener(Object listener)

Remove a listener for lifecycle-related events.

Since:

0.3.3

getLifecycleEventManager

LifecycleEventManager getLifecycleEventManager()

Return the lifecycle event manager associated with the broker.

getLifecycleListenerCallbackMode

int getLifecycleListenerCallbackMode()

The callback mode for handling exceptions from lifecycle event listeners.

setLifecycleListenerCallbackMode

void setLifecycleListenerCallbackMode(int mode)

The callback mode for handling exceptions from lifecycle event listeners.

getCachePreparedQuery

boolean getCachePreparedQuery()

Affirms if this receiver is caching prepared queries.

Since:

2.0.0

setCachePreparedQuery

void setCachePreparedQuery(boolean flag)

Sets whether this receiver will cache prepared queries during its lifetime. The cache configured at BrokerFactory level is not affected by setting it inactive for this receiver.

Since:

2.0.0

begin

void begin()

Begin a transaction.

commit

void commit()

Commit the current transaction.

rollback

void rollback()

Rollback the current transaction.

syncWithManagedTransaction

boolean syncWithManagedTransaction()

Attempt to synchronize with a current managed transaction, returning true if successful, false if no managed transaction is active.

commitAndResume

void commitAndResume()

Issue a commit and then start a new transaction. This is identical to:

 broker.commit (); broker.begin ();
 

except that the broker's internal atomic lock is utilized, so this method can be safely executed from multiple threads.

Since:

0.2.4

See Also:

commit(), begin()

rollbackAndResume

void rollbackAndResume()

Issue a rollback and then start a new transaction. This is identical to:

 broker.rollback (); broker.begin ();
 

except that the broker's internal atomic lock is utilized, so this method can be safely executed from multiple threads.

Since:

0.2.4

See Also:

rollback(), begin()

getRollbackOnly

boolean getRollbackOnly()

Return whether the current transaction has been marked for rollback.

setRollbackOnly

void setRollbackOnly()

Mark the current transaction for rollback.

setRollbackOnly

void setRollbackOnly(Throwable cause)

Mark the current transaction for rollback with the specified cause of the rollback.

Since:

0.9.7

getRollbackCause

Throwable getRollbackCause()

Returns the Throwable that caused the transaction to be marked for rollback.

Returns:

the Throwable, or null if none was given

Since:

0.9.7

setSavepoint

void setSavepoint(String name)

Set a transactional savepoint where operations after this savepoint will be rolled back.

rollbackToSavepoint

void rollbackToSavepoint()

Rollback the current transaction to the last savepoint. Savepoints set after this one will become invalid.

rollbackToSavepoint

void rollbackToSavepoint(String name)

Rollback the current transaction to the given savepoint name. Savepoints set after this one will become invalid.

releaseSavepoint

void releaseSavepoint()

Release the last set savepoint and any resources associated with it. The given savepoint and any set after it will become invalid.

releaseSavepoint

void releaseSavepoint(String name)

Release the savepoint and any resources associated with it. The given savepoint and any set after it will become invalid.

flush

void flush()

Flush all transactional instances to the data store. This method may set the rollback only flag on the current transaction if it encounters an error.

Since:

0.2.5

preFlush

void preFlush()

Run pre-flush actions on transactional objects, including persistence-by-reachability, inverse relationship management, deletion of dependent instances, and instance callbacks. Transaction listeners are not invoked.

Since:

0.3.3

validateChanges

void validateChanges()

Validate the changes made in this transaction, reporting any optimistic violations, constraint violations, etc. In a datastore transaction or a flushed optimistic transaction, this method will act just like flush(). In an optimistic transaction that has not yet begun a datastore-level transaction, however, it will only report exceptions that would occur on flush, without retaining any datastore resources.

persist

void persist(Object obj,
             OpCallbacks call)

Persist the given object.

persistAll

void persistAll(Collection objs,
                OpCallbacks call)

Persist the given objects.

persist

OpenJPAStateManager persist(Object pc,
                            Object id,
                            OpCallbacks call)

Make the given instance persistent. Unlike other persist operations, this method does not immediately cascade to fields marked ValueMetaData.CASCADE_IMMEDIATE.

Parameters:

pc - the instance to persist

id - the id to give the state manager; may be null for default

Returns:

the state manager for the newly persistent instance

delete

void delete(Object pc,
            OpCallbacks call)

Delete the given object.

deleteAll

void deleteAll(Collection objs,
               OpCallbacks call)

Delete the given objects.

release

void release(Object pc,
             OpCallbacks call)

Release the given object from management. This operation is not recursive.

releaseAll

void releaseAll(Collection objs,
                OpCallbacks call)

Release the given objects from management. This operation is not recursive.

refresh

void refresh(Object pc,
             OpCallbacks call)

Refresh the state of the given object.

refreshAll

void refreshAll(Collection objs,
                OpCallbacks call)

Refresh the state of the given objects.

evict

void evict(Object pc,
           OpCallbacks call)

Evict the given object.

evictAll

void evictAll(Collection objs,
              OpCallbacks call)

Evict the given objects.

evictAll

void evictAll(OpCallbacks call)

Evict all clean objects.

evictAll

void evictAll(Extent extent,
              OpCallbacks call)

Evict all persistent-clean and persistent-nontransactional instances in the given Extent.

detachAll

void detachAll(OpCallbacks call)

Detach all objects in place. A flush will be performed before detaching the entities.

detachAll

void detachAll(OpCallbacks call,
               boolean flush)

Detach all objects in place, with the option of performing a flush before doing the detachment.

Parameters:

call - Persistence operation callbacks

flush - boolean value to indicate whether to perform a flush before detaching the entities (true, do the flush; false, don't do the flush)

detach

Object detach(Object pc,
              OpCallbacks call)

Detach the specified object from the broker.

Parameters:

pc - the instance to detach

Returns:

the detached instance

detachAll

Object[] detachAll(Collection objs,
                   OpCallbacks call)

Detach the specified objects from the broker. The objects returned can be manipulated and re-attached with attachAll(java.util.Collection, boolean, org.apache.openjpa.kernel.OpCallbacks). The detached instances will be unmanaged copies of the specified parameters, and are suitable for serialization and manipulation outside of a OpenJPA environment. When detaching instances, only fields in the current FetchConfiguration will be traversed. Thus, to detach a graph of objects, relations to other persistent instances must either be in the default-fetch-group, or in the current custom FetchConfiguration.

Parameters:

objs - the instances to detach

Returns:

the detached instances

attach

Object attach(Object pc,
              boolean copyNew,
              OpCallbacks call)

Import the specified detached object into the broker.

Parameters:

pc - instance to import

copyNew - whether to copy new instances

Returns:

the re-attached instance

attachAll

Object[] attachAll(Collection objs,
                   boolean copyNew,
                   OpCallbacks call)

Import the specified objects into the broker. Instances that were previously detached from this or another broker will have their changed merged into the persistent instances. Instances that are new will be persisted as new instances.

Parameters:

objs - array of instances to import

copyNew - whether to copy new instances

Returns:

the re-attached instances

newInstance

Object newInstance(Class cls)

Create a new instance of type cls. If cls is an interface or an abstract class whose abstract methods follow the JavaBeans convention, this method will create a concrete implementation according to the metadata that defines the class. Otherwise, if cls is a managed type, this will return an instance of the specified class.

Throws:

IllegalArgumentException - if cls is not a managed type or interface.

isDetached

boolean isDetached(Object obj)

Returns true if obj is a detached object (one that can be reattached to a Broker via a call to attach(java.lang.Object, boolean, org.apache.openjpa.kernel.OpCallbacks)); otherwise returns false.

newExtent

Extent newExtent(Class cls,
                 boolean subs)

Return an extent of the given class, optionally including subclasses.

newQuery

Query newQuery(String language,
               Class cls,
               Object query)

Create a new query from the given data, with the given candidate class and language.

newQuery

Query newQuery(String language,
               Object query)

Create a new query in the given language.

getIdentitySequence

Seq getIdentitySequence(ClassMetaData meta)

Returns a Seq for the datastore identity values of the specified persistent class, or null if the class' identity cannot be represented as a sequence.

getValueSequence

Seq getValueSequence(FieldMetaData fmd)

Returns a Seq for the generated values of the specified field, or null if the field is not generated.

lock

void lock(Object pc,
          int level,
          int timeout,
          OpCallbacks call)

Ensure that the given instance is locked at the given lock level.

Parameters:

pc - the object to lock

level - the lock level to use

timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

Since:

0.3.1

lock

void lock(Object pc,
          OpCallbacks call)

Ensure that the given instance is locked at the current lock level, as set in the FetchConfiguration for the broker.

Since:

0.3.1

lockAll

void lockAll(Collection objs,
             int level,
             int timeout,
             OpCallbacks call)

Ensure that the given instances are locked at the given lock level.

Parameters:

objs - the objects to lock

level - the lock level to use

timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

Since:

0.3.1

lockAll

void lockAll(Collection objs,
             OpCallbacks call)

Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the broker.

Since:

0.3.1

cancelAll

boolean cancelAll()

Cancel all pending data store statements. If statements are cancelled while a flush is in progress, the transaction rollback only flag will be set.

Returns:

true if any statements were cancelled, false otherwise

Since:

0.3.1

dirtyType

void dirtyType(Class cls)

Mark the given class as dirty within the current transaction.

Since:

0.3.0

beginOperation

boolean beginOperation(boolean syncTrans)

Begin a logical operation. This indicates to the broker the granularity of an operation which may require pre/post operation side-effects, such as non-tx detach. Will lock the broker until the endOperation() is called.

Parameters:

syncTrans - whether instances may be loaded/modified during this operation requiring a re-check of global tx

Returns:

whether this is the outermost operation on the stack

endOperation

boolean endOperation()

End a logical operation. This indicates to the broker the granularity of an operation which may require pre/post operation side-effects, such as non-tx detach. Unlocks the given broker.

Returns:

whether this is the outermost operation on the stack

isClosed

boolean isClosed()

Whether the broker is closed.

isCloseInvoked

boolean isCloseInvoked()

Whether close() has been invoked, though the broker might remain open until the current managed transaction completes.

close

void close()

Close the broker.

Specified by:

close in interface Closeable

assertOpen

void assertOpen()

Throw an exception if this broker has been closed.

assertActiveTransaction

void assertActiveTransaction()

Throw an exception if there is no active transaction.

assertNontransactionalRead

void assertNontransactionalRead()

Throw an exception if there is no transaction active and nontransactional reading is not enabled.

assertWriteOperation

void assertWriteOperation()

Throw an exception if a write operation is not permitted (there is no active transaction and nontransactional writing is not enabled).