org.apache.ojb.otm
Interface OTMConnection

All Known Implementing Classes:

BaseConnection, LocalTransactionFactory.LocalConnection, ManagedTransactionFactory.ManagedConnection

public interface OTMConnection

A OTMConnection within the given Environment

Author:

Raghu Rajah

Method Summary

void	close() Close the OTMConnection
void	deletePersistent(Object obj) Mark the given object for deletion from the persistent store.
Collection	getCollectionByQuery(Query query)
Collection	getCollectionByQuery(Query query, int lock)
int	getCount(Query query) return the number of objects that would be returned from this query
ClassDescriptor	getDescriptorFor(Class clazz)
EditingContext	getEditingContext() Get the EditingContext associated with the transaction to which this connection belongs.
Identity	getIdentity(Object object) Get the identity of the object
Iterator	getIteratorByOQLQuery(OQLQuery query)
Iterator	getIteratorByOQLQuery(OQLQuery query, int lock)
Iterator	getIteratorByQuery(Query query)
Iterator	getIteratorByQuery(Query query, int lock)
Object	getObjectByIdentity(Identity oid) Get the object with the given Identity from the persistent store.
Object	getObjectByIdentity(Identity oid, int lock) Get the object with the given Identity from the persistent store with the given lock value.
Transaction	getTransaction() Obtain the Transaction this connection is associated with
void	invalidate(Identity oid) In the case if the program need to change the objects via direct JDBC call, it should first call invalidate() for the object, which will lock the object for write and tell OJB OTM that it must be re-read from the database, only after that you shold perform JDBC operation.
void	invalidateAll() clear the underlying caches
boolean	isClosed() check if the OTMConnection is closed
void	lockForWrite(Object object) Lock the given object for Write.
void	makePersistent(Object object) Make the given object persistent by inserting it into the database.
EnhancedOQLQuery	newOQLQuery() returns a new OQL Query.
EnhancedOQLQuery	newOQLQuery(int lock) returns a new OQL Query.
void	refresh(Object object) Updates the values in the object from the data in data store.
ObjectCache	serviceObjectCache() get the global cache
void	setTransaction(Transaction tx) Associate this connection with a given transaction.

Method Detail

makePersistent

void makePersistent(Object object)
                    throws LockingException

Make the given object persistent by inserting it into the database. Also read locks the object (OTM will automatically lock it for write on transaction commit if the object will appear to be modified).

Parameters:

object - the object to be made persistent

Throws:

LockingException

getTransaction

Transaction getTransaction()

Obtain the Transaction this connection is associated with

setTransaction

void setTransaction(Transaction tx)

Associate this connection with a given transaction.

deletePersistent

void deletePersistent(Object obj)
                      throws LockingException

Mark the given object for deletion from the persistent store. The object would then become a transient object, rather than a persistent one.

Parameters:

obj - the object to delete

Throws:

LockingException

lockForWrite

void lockForWrite(Object object)
                  throws LockingException

Lock the given object for Write. Only write locked objects are persisted back to the database. Changes to read objects are not inserted back into the database.

Parameters:

object - the object to be locked for write.

Throws:

LockingException

getObjectByIdentity

Object getObjectByIdentity(Identity oid)
                           throws LockingException

Get the object with the given Identity from the persistent store. By default, the fetch is for read. (OTM will automatically lock it for write on transaction commit if the object will appear to be modified).

Parameters:

oid - the Identity of the object to fetch

Returns:

the object from the persistent store.

Throws:

LockingException - thrown by the LockManager to avoid deadlocks. The fetch could be re-submitted.

getObjectByIdentity

Object getObjectByIdentity(Identity oid,
                           int lock)
                           throws LockingException

Get the object with the given Identity from the persistent store with the given lock value.

Parameters:

oid - the Identity of the object to fetch

lock - the lock that need to be acquired on the object Possible values are: LockType.NO_LOCK (aka read only) - changes to the object will not be written to database; LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database, in this case the lock will be automatically upgraded to the write lock on transaction commit; LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.

Returns:

the object from the persistent store.

Throws:

LockingException - thrown by the LockManager to avoid a deadlock.

getIteratorByQuery

Iterator getIteratorByQuery(Query query)

Parameters:

query - The query to execute

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked for read.

getIteratorByQuery

Iterator getIteratorByQuery(Query query,
                            int lock)

Parameters:

query - The query to execute

lock - the lock that need to be acquired on the object Possible values are: LockType.NO_LOCK (aka read only) - changes to the object will not be written to database; LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database, in this case the lock will be automatically upgraded to the write lock on transaction commit; LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked with the given lock value.

getIteratorByOQLQuery

Iterator getIteratorByOQLQuery(OQLQuery query)

Parameters:

query - The OQL query to execute

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked for read.

getIteratorByOQLQuery

Iterator getIteratorByOQLQuery(OQLQuery query,
                               int lock)

Parameters:

query - The OQL query to execute

lock - the lock that need to be acquired on the object Possible values are: LockType.NO_LOCK (aka read only) - changes to the object will not be written to database; LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database, in this case the lock will be automatically upgraded to the write lock on transaction commit; LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked for read.

getCollectionByQuery

Collection getCollectionByQuery(Query query,
                                int lock)

Parameters:

query - The query to execute

lock - the lock that need to be acquired on the object Possible values are: LockType.NO_LOCK (aka read only) - changes to the object will not be written to database; LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database, in this case the lock will be automatically upgraded to the write lock on transaction commit; LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked with the given lock value.

getCollectionByQuery

Collection getCollectionByQuery(Query query)

Parameters:

query - The query to execute

Returns:

an Iterator that iterates Objects of class c if calling the .next() method. The returned objects are locked for read.

getIdentity

Identity getIdentity(Object object)

Get the identity of the object

Parameters:

object - The object

Returns:

the identity of the object

getDescriptorFor

ClassDescriptor getDescriptorFor(Class clazz)

getEditingContext

EditingContext getEditingContext()

Get the EditingContext associated with the transaction to which this connection belongs. EditingContext contains and manages the set of objects read/edited within the current transaction.

Returns:

EditingContext associated with current Transaction

invalidate

void invalidate(Identity oid)
                throws LockingException

In the case if the program need to change the objects via direct JDBC call, it should first call invalidate() for the object, which will lock the object for write and tell OJB OTM that it must be re-read from the database, only after that you shold perform JDBC operation. NOTE: it is not recommended to use read-uncommitted isolation if you want this feature to work correctly.

Throws:

LockingException

invalidateAll

void invalidateAll()
                   throws LockingException

clear the underlying caches

Throws:

LockingException

newOQLQuery

EnhancedOQLQuery newOQLQuery()

returns a new OQL Query. This OQL query is Enhanced, meaning it does the ODMG functionality as well as some additional OJB specific, non portable functionality.

Returns:

the new OQLQuery

newOQLQuery

EnhancedOQLQuery newOQLQuery(int lock)

returns a new OQL Query. This OQL query is Enhanced, meaning it does the ODMG functionality as well as some additional OJB specific, non portable functionality.

Parameters:

lock - the lock that need to be acquired on the object Possible values are: LockType.NO_LOCK (aka read only) - changes to the object will not be written to database; LockType.READ_LOCK (aka optimistic lock) - changes to the object will be written to the database, in this case the lock will be automatically upgraded to the write lock on transaction commit; LockType.WRITE_LOCK (aka pessimistic lock) - changes to the object will be written to the database.

Returns:

the new OQLQuery

getCount

int getCount(Query query)

return the number of objects that would be returned from this query

Parameters:

query -

Returns:

the number of objects that would be returned from this query

close

void close()

Close the OTMConnection

isClosed

boolean isClosed()

check if the OTMConnection is closed

serviceObjectCache

ObjectCache serviceObjectCache()

get the global cache

Returns:

refresh

void refresh(Object object)

Updates the values in the object from the data in data store. The state of the object becomes "Persistent-clean".