Database (Castor JavaDoc)

All Known Implementing Classes:

AbstractDatabaseImpl, GlobalDatabaseImpl, LocalDatabaseImpl
```
public interface Database
```
An open connection to the database. This object represents an open connection to the database that can be used to perform transactional operations on the database.
Database operations can only be performed in the context of a transaction. Client applications should begin and commit a transaction using the begin() and commit() 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: 8660 $ $Date: 2006-03-16 16:04:24 -0700 (Thu, 16 Mar 2006) $

Author:

Assaf Arkin

See Also:

JDOManager.getDatabase(), Query

Field Summary

Fields
Modifier and Type	Field	Description
`static AccessMode`	`DBLOCKED`	Database lock access.
`static AccessMode`	`EXCLUSIVE`	Exclusive access.
`static AccessMode`	`READONLY`	Read only access.
`static AccessMode`	`SHARED`	Shared access.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`begin()`	Begin a new transaction.
`void`	`close()`	Closes the database.
`void`	`commit()`	Commits and closes the transaction.
`void`	`create(java.lang.Object object)`	Creates a new object in persistent storage.
`CacheManager`	`getCacheManager()`	Get's the CacheManager instance.
`java.lang.ClassLoader`	`getClassLoader()`	Returns the current ClassLoader if one has been set for this Database instance.
`java.lang.String`	`getDatabaseName()`	Return the name of the database.
`Identity`	`getIdentity(java.lang.Object object)`	Returns the object's identity.
`java.sql.Connection`	`getJdbcConnection()`	Gets the underlying JDBC connection.
`OQLQuery`	`getNamedQuery(java.lang.String name)`	Creates an OQL query based upon a named query as defined in the mapping file.
`OQLQuery`	`getNativeQuery(java.lang.String sql, java.lang.Class<?> result)`	Creates an OQL query instance based upon a native SQL query and a returning (resulting) class.
`OQLQuery`	`getOQLQuery()`	Creates an OQL query with no statement.
`OQLQuery`	`getOQLQuery(java.lang.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()`	Deprecated. As of Castor 1.3.2, please use the 'cascading' attribute of the field mapping instead.
`boolean`	`isClosed()`	Returns true if the database is closed.
`boolean`	`isLocked(java.lang.Class cls, java.lang.Object identity)`	Returns true if the specified object is currently locked.
`boolean`	`isPersistent(java.lang.Object entity)`	Returns true if the entity is persistent.
`<T> T`	`load(java.lang.Class<T> type, java.lang.Object identity)`	Load an object of the specified type and given identity.
`<T> T`	`load(java.lang.Class<T> type, java.lang.Object identity, java.lang.Object object)`	Load an object of the specified type and given identity into a given instance of object.
`<T> T`	`load(java.lang.Class<T> type, java.lang.Object identity, AccessMode mode)`	Load an object of the specified type and given identity.
`void`	`lock(java.lang.Object object)`	Acquire a soft write lock on the object.
`void`	`remove(java.lang.Object object)`	Removes the object from persistent storage.
`void`	`rollback()`	Rolls back and closes the transaction.
`void`	`setAutoStore(boolean autoStore)`	Deprecated. As of Castor 1.3.2, please use the 'cascading' attribute of the field mapping instead.
`void`	`update(java.lang.Object object)`	Update a data object which is queried/loaded/created in another transaction.

- Field Detail
  - READONLY
```
static final AccessMode READONLY
```
    Read only access. Used with queries and the load(Class,Object) method to load objects as read-only.
    Read-only objects are not persistent and changes to these objects are not reflected in the database when the transaction commits.
  - SHARED
```
static final AccessMode SHARED
```
    Shared access. Used with queries and the load(Class,Object) method to load objects with shared access.
    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.
  - EXCLUSIVE
```
static final AccessMode EXCLUSIVE
```
    Exclusive access. Used with queries and the load(Class,Object) method to load objects with exclusive access.
    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.
  - DBLOCKED
```
static final AccessMode DBLOCKED
```
    Database lock access. Used with queries and the load(Class,Object) method to load objects with a database lock.
    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.
- Method Detail
  - getOQLQuery
```
OQLQuery getOQLQuery()
```
    Creates an OQL query with no statement. OQLQuery.create(java.lang.String) must be called before the query can be executed.
    
    Returns:
    
    An OQL query
  - getOQLQuery
```
OQLQuery getOQLQuery(java.lang.String oql)
              throws PersistenceException
```
    Creates an OQL query from the supplied statement.
    
    Parameters:
    
    oql - An OQL query statement
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getQuery
```
Query getQuery()
```
    Creates an empty query. The query must be created before it can be executed.
    
    Returns:
    
    A query
  - getNamedQuery
```
OQLQuery getNamedQuery(java.lang.String name)
                throws PersistenceException
```
    Creates an OQL query based upon a named query as defined in the mapping file. OQLQuery.create(java.lang.String)
    
    Parameters:
    
    name - Name of the (named) query to create.
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getNativeQuery
```
OQLQuery getNativeQuery(java.lang.String sql,
                        java.lang.Class<?> result)
                 throws PersistenceException
```
    Creates an OQL query instance based upon a native SQL query and a returning (resulting) class.
    
    Parameters:
    
    sql - Native SQL query to be used.
    
    result - Class that is result of the query.
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getScope
```
PersistenceInfoGroup getScope()
```
  - getDatabaseName
```
java.lang.String getDatabaseName()
```
    Return the name of the database.
    
    Returns:
    
    The database name.
  - load
```
<T> T load(java.lang.Class<T> type,
           java.lang.Object identity)
    throws PersistenceException
```
    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. 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
    
    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
```
<T> T load(java.lang.Class<T> type,
           java.lang.Object identity,
           AccessMode mode)
    throws PersistenceException
```
    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
```
<T> T load(java.lang.Class<T> type,
           java.lang.Object identity,
           java.lang.Object object)
    throws PersistenceException
```
    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
  - create
```
void create(java.lang.Object object)
     throws PersistenceException
```
    Creates a new object in persistent storage. The object will be persisted only if the transaction commits.
    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
  - remove
```
void remove(java.lang.Object object)
     throws PersistenceException
```
    Removes the object from persistent storage. The deletion will take effect only if the transaction is committed, but the object is no longer visible to queries in the current transaction and locks for access from other transactions will block until this transaction completes.
    
    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
  - update
```
void update(java.lang.Object object)
     throws PersistenceException
```
    Update a data object which is queried/loaded/created in another transaction. This method is used only for long transaction support. Calling this method for data object queried/loaded/created in the same transaction results in Exception.
    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
  - lock
```
void lock(java.lang.Object object)
   throws PersistenceException
```
    Acquire a soft write lock on the object. Read locks are implicitly available when the object is queried. A write lock is only granted for objects that are created or deleted or for objects loaded in exclusive mode - this method can obtain such a lock explicitly.
    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
  - begin
```
void begin()
    throws PersistenceException
```
    Begin a new transaction. A transaction must be open in order to query and persist objects.
    
    Throws:
    
    PersistenceException - A transaction is already open on this database, or an error reported by the persistence engine
  - isAutoStore
```
boolean isAutoStore()
```
    Deprecated.
    As of Castor 1.3.2, please use the 'cascading' attribute of the field mapping instead.
    
    Return if the current transaction is set to autoStore, it there is transaction active. If there is no active transaction, return if the next transaction will be set to autoStore.
    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'.
  - setAutoStore
```
void setAutoStore(boolean autoStore)
```
    Deprecated.
    As of Castor 1.3.2, please use the 'cascading' attribute of the field mapping instead.
    
    True if autoStore is set on.
    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/queried/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.
  - commit
```
void commit()
     throws TransactionNotInProgressException,
            TransactionAbortedException
```
    Commits and closes the transaction. All changes made to persistent objects during the transaction are made persistent; objects created during the transaction are made durable; and, objects removed during the transaction are removed from 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 begin() 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
  - rollback
```
void rollback()
       throws TransactionNotInProgressException
```
    Rolls back and closes the transaction. All changes made to persistent objects during the transaction are lost, objects created during the transaction are not made durable and objects removed during the transaction continue to exist.
    
    Throws:
    
    TransactionNotInProgressException - Method called while transaction is not in progress
  - isActive
```
boolean isActive()
```
    Returns true if a transaction is currently active.
    
    Returns:
    
    True if a transaction is active
  - isClosed
```
boolean isClosed()
```
    Returns true if the database is closed.
    
    Returns:
    
    True if the database is closed
  - isLocked
```
boolean isLocked(java.lang.Class cls,
                 java.lang.Object identity)
          throws PersistenceException
```
    Returns true if the specified object is currently locked.
    
    Parameters:
    
    cls - Class instance.
    
    identity - Object identity.
    
    Returns:
    
    True if the object specified is locked; false otherwise.
    
    Throws:
    
    PersistenceException
  - close
```
void close()
    throws PersistenceException
```
    Closes the database. If a client transaction is in progress the transaction will be rolled back and an exception thrown. If an app-server transaction is in progress, the transaction will commit/rollback when triggered by the application server.
    
    Throws:
    
    PersistenceException - An error occured while attempting to close the database
  - isPersistent
```
boolean isPersistent(java.lang.Object entity)
```
    Returns true if the entity is persistent. An entity is persistent if it was created or loaded but not removed in this transaction. If the entity was created or loaded in another transaction, or there is no open transaction, this method returns false.
    
    Parameters:
    
    entity - The entity.
    
    Returns:
    
    True if entity is persistent in this transaction.
  - getIdentity
```
Identity getIdentity(java.lang.Object object)
              throws PersistenceException
```
    Returns the object's identity. The identity will be determined by calling the getters of the fields defined as identities in the mapping. If a mapping for the objects class could not be found a ClassNotPersistenceCapableException will be thrown. Null is only returned if the objects identity is null. It is not required to have an active transaction when using this method.
    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:
    
    PersistenceException - The class is not persistent capable.
  - getClassLoader
```
java.lang.ClassLoader getClassLoader()
```
    Returns the current ClassLoader if one has been set for this Database instance.
    
    Returns:
    
    ClassLoader the current ClassLoader instance, null if no ClassLoader's instance has been explicitely set.
  - getCacheManager
```
CacheManager getCacheManager()
```
    Get's the CacheManager instance. Call getCacheManager for every Database-instances.
    
    Returns:
    
    the CacheManager-instance.
  - getJdbcConnection
```
java.sql.Connection getJdbcConnection()
                               throws PersistenceException
```
    Gets the underlying JDBC connection. This is for advanced use only. Please make sure that you never close this Connection instance, as it will be closed by Castor.
    
    Returns:
    
    the underlying JDBC connection, if present; otherwise null
    
    Throws:
    
    PersistenceException - If the underlying JDBC connection cannot be obtained.

Interface Database

Field Summary

Method Summary

Field Detail

READONLY

SHARED

EXCLUSIVE

DBLOCKED

Method Detail

getOQLQuery

getOQLQuery

getQuery

getNamedQuery

getNativeQuery

getScope

getDatabaseName

load

load

load

create

remove

update

lock

begin

isAutoStore

setAutoStore

commit

rollback

isActive

isClosed

isLocked

close

isPersistent

getIdentity

getClassLoader

getCacheManager

getJdbcConnection