org.exolab.castor.jdo
public interface Database
Database operations can only be performed in the context of a transaction. Client applications should begin and commit a transaction using the Database and Database methods. Server applications should use implicit transaction demaraction by the container or explicit transaction demarcation using javax.transaction.UserTransaction.
All objects queried and created during a transaction are persistent. Changes to persistent objects will be stored in the database when the transaction commits. Changes will not be stored if the transaction is rolled back or fails to commit.
Once the transaction has committed or rolled back, all persistent objects become transient. Opening a new transaction does not make these objects persistent.
For example:
Database db; Query oql; QueryResults results; Product prod; // Open a database and start a transaction db = jdo.getDatabase(); db.begin(); // Select all the products in a given group oql = db.getOQLQuery( "SELECT p FROM Product p WHERE group=$"); oql.bind( groupId ); results = oql.execute(); while ( results.hasMore() ) { // A 25% mark down for each product and mark as sale prod = (Product) results.next(); prod.markDown( 0.25 ); prod.setOnSale( true ); } // Commit all changes, close the database db.commit(); db.close();
Version: $Revision: 1.13 $ $Date: 2005/11/10 15:59:51 $
See Also: getDatabase Query
Field Summary | |
---|---|
static AccessMode | DbLocked
Database lock access. |
static AccessMode | Exclusive
Exclusive access. |
static AccessMode | ReadOnly
Read only access. |
static AccessMode | Shared
Shared access. |
Method Summary | |
---|---|
void | begin()
Begin a new transaction. |
void | close()
Closes the database. |
void | commit()
Commits and closes the transaction. |
void | create(Object object)
Creates a new object in persistent storage. |
CacheManager | getCacheManager()
Get's the CacheManager instance.
|
ClassLoader | getClassLoader()
Returns the current ClassLoader if one has been set for this Database instance. |
String | getDatabaseName()
Return the name of the database |
Object | getIdentity(Object object)
Returns the object's identity. |
Connection | getJdbcConnection()
Gets the underlying JDBC connection.
|
OQLQuery | getOQLQuery()
Creates an OQL query with no statement. OQLQuery
must be called before the query can be executed.
|
OQLQuery | getOQLQuery(String oql)
Creates an OQL query from the supplied statement. |
Query | getQuery()
Creates an empty query. |
PersistenceInfoGroup | getScope() |
boolean | isActive()
Returns true if a transaction is currently active.
|
boolean | isAutoStore()
Return if the current transaction is set to autoStore, it there is
transaction active. |
boolean | isClosed()
Returns true if the database is closed.
|
boolean | isPersistent(Object object)
Returns true if the object is persistent. |
Object | load(Class type, Object identity)
Load an object of the specified type and given identity.
|
Object | load(Class type, Object identity, short accessMode) Load an object of the specified type and given identity. |
Object | load(Class type, Object identity, AccessMode mode) Load an object of the specified type and given identity. |
Object | load(Class type, Object identity, Object object) Load an object of the specified type and given identity into a given instance of object. |
void | lock(Object object)
Acquire a soft write lock on the object. |
void | remove(Object object)
Removes the object from persistent storage. |
void | rollback()
Rolls back and closes the transaction. |
void | setAutoStore(boolean autoStore)
True if autoStore is set on.
|
void | update(Object object)
Update a data object which is queried/loaded/created in another
transaction. |
Database lock prevents two concurrent transactions from accessing the same record either through Castor or direct database access by acquiring a write lock in the select statement. Concurrent transactions will block until the lock is released at commit time.
When an object is first loaded in the transaction, it will be synchronized with the database and not populated from the cache. Dirty checking is not required.
Exclusive access prevents two concurrent transactions from accessing the same record. In exclusive mode objects acquire a write lock, and concurrent transactions will block until the lock is released at commit time.
Dirty checking is enabled for all fields marked as such. When an object is first loaded in the transaction, it will be synchronized with the database and not populated from the cache.
Read-only objects are not persistent and changes to these objects are not reflected in the database when the transaction commits.
Shared access allows the same record to be accessed by two concurrent transactions, each with it's own view (object).
These objects acquire a read lock which escalated to a write lock when the transaction commits if the object has been modified. Dirty checking is enabled for all fields marked as such, and a cached copy is used to populate the object.
Throws: PersistenceException A transaction is already open on this database, or an error reported by the persistence engine
Throws: PersistenceException An error occured while attempting to close the database
In other words, any modifications to any data objects which are queried/loaded/created/update to this database is automatically stored to the database and visible to subsequence transactions. (ie. update is solely used for long transaction support and should not be called for any data object queried/loaded/created in the this transaction.)
If the transaction cannot commit, the entire transaction rolls back and a TransactionAbortedException exception is thrown.
After this method returns, the transaction is closed and all persistent objects are transient. Using Database to open a new transaction will not restore objects to their persistent stage.
Throws: TransactionNotInProgressException Method called while transaction is not in progress TransactionAbortedException The transaction cannot commit and has been rolled back
If the object has an identity then duplicate identity check happens in this method, and the object is visible to queries in this transaction. If the identity is null, duplicate identity check occurs when the transaction completes and the object is not visible to queries until the transaction commits.
Parameters: object The object to create
Throws: TransactionNotInProgressException Method called while transaction is not in progress DuplicateIdentityException An object with this identity already exists in persistent storage ClassNotPersistenceCapableException The class is not persistent capable PersistenceException An error reported by the persistence engine
Returns: the CacheManager-instance.
Returns: ClassLoader the current ClassLoader instance, null
if no
ClassLoader's instance has been explicitely set.
Returns: The database name.
Note: Prior to 0.9.9.1 release of castor the identity could only be determined if the object took part in the transaction. If this was not the case, the previous implementation also returned null.
Parameters: object The object.
Returns: The object's identity, or null.
Throws: ClassNotPersistenceCapableException The class is not persistent capable.
Returns: the underlying JDBC connection, if present; otherwise null
Throws: PersistenceException If the underlying JDBC connection cannot be obtained.
Returns: An OQL query
Parameters: oql An OQL query statement
Returns: An OQL query
Throws: PersistenceException
Returns: A query
Returns: True if a transaction is active
If autoStore is set on. AutoStore will create all reachable object if the object is not loaded from the transaction. If it is turn off, only dependent object will be created automatically.
Returns: True if the current transaction is set to 'autoStore'.
Returns: True if the database is closed
Parameters: object The object
Returns: True if persistent in this transaction
Parameters: type The object's type identity The object's identity
Returns: The object instance.
Throws: ObjectNotFoundException No object of the given type and identity was found in persistent storage LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object TransactionNotInProgressException Method called while transaction is not in progress PersistenceException An error reported by the persistence engine
Deprecated: Use load(Class, Object, AccessMode) instead.
Load an object of the specified type and given identity. Once loaded the object is persistent. Calling this method with the same identity in the same transaction will return the same object. This method is equivalent to a query that returns a single object.
Parameters: type The object's type identity The object's identity accessMode The access mode
Returns: The object instance.
Throws: ObjectNotFoundException No object of the given type and identity was found in persistent storage LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object TransactionNotInProgressException Method called while transaction is not in progress PersistenceException An error reported by the persistence engine
Load an object of the specified type and given identity. Once loaded the object is persistent. Calling this method with the same identity in the same transaction will return the same object. This method is equivalent to a query that returns a single object.
Parameters: type The object's type identity The object's identity mode The access mode
Returns: The object instance.
Throws: ObjectNotFoundException No object of the given type and identity was found in persistent storage LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object TransactionNotInProgressException Method called while transaction is not in progress PersistenceException An error reported by the persistence engine
Load an object of the specified type and given identity into a given instance of object. Once loaded the object is persistent. Calling this method with the same identity in the same transaction will return the same object. This method is equivalent to a query that returns a single object. If the identity spans on more than one field, all of the identity fields can be wrapped in a Complex object.
Parameters: type The object's type identity The object's identity object The object instance to be loaded into
Returns: The object instance.
Throws: ObjectNotFoundException No object of the given type and identity was found in persistent storage LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object TransactionNotInProgressException Method called while transaction is not in progress PersistenceException An error reported by the persistence engine
A soft lock is acquired in memory, not in the database. To acquire a lock in the database, use the locked access mode.
If the object already has a write lock in this transaction or a read lock in this transaction but no read lock in any other transaction, a write lock is obtained. If this object has a read lock in any other transaction this method will block until the other transaction will release its lock. If the timeout has elapsed or a deadlock has been detected, an exception will be thrown but the current lock will be retained.
Parameters: object The object to lock
Throws: TransactionNotInProgressException Method called while transaction is not in progress ObjectNotPersistentException The object has not been queried or created in this transaction LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object PersistenceException An error reported by the persistence engine
Parameters: object The object to remove
Throws: TransactionNotInProgressException Method called while transaction is not in progress ObjectNotPersistentException The object has not been queried or created in this transaction LockNotGrantedException Timeout or deadlock occured attempting to acquire a lock on the object PersistenceException An error reported by the persistence engine
Throws: TransactionNotInProgressException Method called while transaction is not in progress
This method should be called before begin().
If autoStore is set, and db.create( theDataObject ) is called, Castor will create theDataObject, and create each object that does not exist in the transaction and reachable from theDataObject.
If db.update( theDataObject ), and theDataObject is loaded/queuied/created in a previous transaction, Castor will let theDataObject, and all reachable object from theDataObject, participate in the current transaction.
If autoStore is not set, Castor will only create/update/store dependent object, and related objects must be created/update explicitly.
Parameters: autoStore True if this feature should be enabled.
For example, the data object may be sent to a client application and dispayed to a user. After that the objects is being modified in the client application, the object returns back and is update to the database in the second transaction.
See Long Transaction on Castor website.
Parameters: object The object to create
Throws: TransactionNotInProgressException Method called while transaction is not in progress ClassNotPersistenceCapableException The class is not persistent capable PersistenceException An error reported by the persistence engine