AbstractDatabaseImpl (Castor JavaDoc)

java.lang.Object
- org.exolab.castor.jdo.engine.AbstractDatabaseImpl

All Implemented Interfaces:

Database

Direct Known Subclasses:

GlobalDatabaseImpl, LocalDatabaseImpl
```
public abstract class AbstractDatabaseImpl
extends java.lang.Object
implements Database
```
An implementation of the JDO database supporting explicit transaction demarcation.

Version:

$Revision: 8351 $ $Date: 2006-04-22 11:05:30 -0600 (Sat, 22 Apr 2006) $

Author:

Assaf Arkin, Bruce Snyder

Field Summary

Fields
Modifier and Type	Field	Description
`protected boolean`	`_autoStore`	True if user prefer all reachable object to be stored automatically.
`protected CallbackInterceptor`	`_callback`	The default callback interceptor for transaction.
`protected java.lang.ClassLoader`	`_classLoader`	The class loader for application classes (may be null).
`protected TransactionContext`	`_ctx`	The transaction context is this database was accessed with an `XAResource`.
`protected java.lang.String`	`_dbName`	The name of this database.
`protected InstanceFactory`	`_instanceFactory`	The instance factory to that creates new instances of data object.
`protected int`	`_lockTimeout`	The lock timeout for this database.
`protected PersistenceInfoGroup`	`_scope`	The database engine used to access the underlying SQL database.

Fields inherited from interface org.exolab.castor.jdo.Database
DBLOCKED, EXCLUSIVE, READONLY, SHARED

Constructor Summary

Constructors
Constructor	Description
`AbstractDatabaseImpl(java.lang.String dbName, int lockTimeout, CallbackInterceptor callback, InstanceFactory instanceFactory, java.lang.ClassLoader classLoader, boolean autoStore)`	Creates an instance of this class.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`abstract void`	`begin()`	Begin a new transaction.
`abstract void`	`close()`	Closes the database.
`abstract 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()`	Gets the current application ClassLoader's instance.
`TransactionContext`	`getCurrentTransaction()`	Gets the current Castor transaction in use.
`java.lang.String`	`getDatabaseName()`	Return the name of the database.
`Identity`	`getIdentity(java.lang.Object object)`	Returns the object's identity.
`abstract java.sql.Connection`	`getJdbcConnection()`	Gets the underlying JDBC connection.
`(package private) LockEngine`	`getLockEngine()`	Returns the `LockEngine` in use by this database instance.
`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()`
`protected TransactionContext`	`getTransaction()`	Returns the currently active transaction, if any.
`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`	`isLocked(java.lang.Class cls, java.lang.Object identity)`	Returns true if the specified object is currently locked.
`boolean`	`isPersistent(java.lang.Object object)`	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.
`protected void`	`loadSynchronizables()`	Load the `TxSynchronizable` implementations from the properties file, if not loaded before.
`void`	`lock(java.lang.Object object)`	Acquire a soft write lock on the object.
`protected void`	`registerSynchronizables()`	Register the `TxSynchronizable` implementations at the TransactionContect at end of begin().
`void`	`remove(java.lang.Object object)`	Removes the object from persistent storage.
`abstract void`	`rollback()`	Rolls back and closes the transaction.
`void`	`setAutoStore(boolean autoStore)`	Indicates whether user prefer all reachable object to be stored automatically; false if user wants dependent object only to be stored.
`java.lang.String`	`toString()`
`protected void`	`unregisterSynchronizables()`	Unregister the `TxSynchronizable` implementations at the TransactionContect after commit() or rollback().
`void`	`update(java.lang.Object object)`	Update a data object which is queried/loaded/created in another transaction.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - _scope
```
protected PersistenceInfoGroup _scope
```
    The database engine used to access the underlying SQL database.
  - _ctx
```
protected TransactionContext _ctx
```
    The transaction context is this database was accessed with an XAResource.
  - _lockTimeout
```
protected int _lockTimeout
```
    The lock timeout for this database. Zero for immediate timeout, an infinite value for no timeout. The timeout is specified in seconds.
  - _callback
```
protected CallbackInterceptor _callback
```
    The default callback interceptor for transaction.
  - _instanceFactory
```
protected InstanceFactory _instanceFactory
```
    The instance factory to that creates new instances of data object.
  - _dbName
```
protected java.lang.String _dbName
```
    The name of this database.
  - _autoStore
```
protected boolean _autoStore
```
    True if user prefer all reachable object to be stored automatically. False if user want only dependent object to be stored.
  - _classLoader
```
protected java.lang.ClassLoader _classLoader
```
    The class loader for application classes (may be null).
- Constructor Detail
  - AbstractDatabaseImpl
```
public AbstractDatabaseImpl(java.lang.String dbName,
                            int lockTimeout,
                            CallbackInterceptor callback,
                            InstanceFactory instanceFactory,
                            java.lang.ClassLoader classLoader,
                            boolean autoStore)
                     throws DatabaseNotFoundException
```
    Creates an instance of this class.
    
    Parameters:
    
    dbName - Name of the database.
    
    lockTimeout - Lock timeout to use.
    
    callback - Callback interceptors.
    
    instanceFactory - Instance factory.
    
    classLoader - Current class loader.
    
    autoStore - True if auto storing is enabled.
    
    Throws:
    
    DatabaseNotFoundException - If there's no database configuration for the given name.
- Method Detail
  - getLockEngine
```
LockEngine getLockEngine()
```
    Returns the LockEngine in use by this database instance.
    
    Returns:
    
    the LockEngine in use by this database instance.
  - getScope
```
public PersistenceInfoGroup getScope()
```
    Specified by:
    
    getScope in interface Database
  - setAutoStore
```
public void setAutoStore(boolean autoStore)
```
    Indicates whether user prefer all reachable object to be stored automatically; false if user wants dependent object only to be stored.
    
    Specified by:
    
    setAutoStore in interface Database
    
    Parameters:
    
    autoStore - True to indicate that 'autoStore' mode should be used.
  - isAutoStore
```
public boolean isAutoStore()
```
    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.
    
    Specified by:
    
    isAutoStore in interface Database
    
    Returns:
    
    True if 'auto-store' mode is in use.
  - getClassLoader
```
public java.lang.ClassLoader getClassLoader()
```
    Gets the current application ClassLoader's instance.
    
    Specified by:
    
    getClassLoader in interface Database
    
    Returns:
    
    the current ClassLoader's instance, or null if not provided
  - getDatabaseName
```
public java.lang.String getDatabaseName()
```
    Return the name of the database.
    
    Specified by:
    
    getDatabaseName in interface Database
    
    Returns:
    
    Name of the database.
  - close
```
public abstract 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.
    
    Specified by:
    
    close in interface Database
    
    Throws:
    
    PersistenceException - An error occured while attempting to close the database
  - isClosed
```
public boolean isClosed()
```
    Returns true if the database is closed.
    
    Specified by:
    
    isClosed in interface Database
    
    Returns:
    
    True if the database is closed
  - isLocked
```
public boolean isLocked(java.lang.Class cls,
                        java.lang.Object identity)
                 throws PersistenceException
```
    Returns true if the specified object is currently locked.
    
    Specified by:
    
    isLocked in interface Database
    
    Parameters:
    
    cls - Class instance.
    
    identity - Object identity.
    
    Returns:
    
    True if the object specified is locked; false otherwise.
    
    Throws:
    
    PersistenceException
  - load
```
public <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.
    
    Specified by:
    
    load in interface Database
    
    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
```
public <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.
    
    Specified by:
    
    load in interface Database
    
    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
  - load
```
public <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.
    
    Specified by:
    
    load in interface Database
    
    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
  - create
```
public 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.
    
    Specified by:
    
    create in interface Database
    
    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
  - getCacheManager
```
public CacheManager getCacheManager()
```
    Get's the CacheManager instance. Call getCacheManager for every Database-instances.
    
    Specified by:
    
    getCacheManager in interface Database
    
    Returns:
    
    the CacheManager-instance.
  - update
```
public 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.
    
    Specified by:
    
    update in interface Database
    
    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
  - remove
```
public 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.
    
    Specified by:
    
    remove in interface Database
    
    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
  - isPersistent
```
public boolean isPersistent(java.lang.Object object)
```
    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.
    
    Specified by:
    
    isPersistent in interface Database
    
    Parameters:
    
    object - The entity.
    
    Returns:
    
    True if entity is persistent in this transaction.
  - getIdentity
```
public 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.
    
    Specified by:
    
    getIdentity in interface Database
    
    Parameters:
    
    object - The object.
    
    Returns:
    
    The object's identity, or null.
    
    Throws:
    
    PersistenceException - The class is not persistent capable.
  - lock
```
public 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.
    
    Specified by:
    
    lock in interface Database
    
    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
  - getOQLQuery
```
public OQLQuery getOQLQuery()
```
    Creates an OQL query with no statement. OQLQuery.create(java.lang.String) must be called before the query can be executed.
    
    Specified by:
    
    getOQLQuery in interface Database
    
    Returns:
    
    An OQL query
  - getNamedQuery
```
public final 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)
    
    Specified by:
    
    getNamedQuery in interface Database
    
    Parameters:
    
    name - Name of the (named) query to create.
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getNativeQuery
```
public final 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.
    
    Specified by:
    
    getNativeQuery in interface Database
    
    Parameters:
    
    sql - Native SQL query to be used.
    
    result - Class that is result of the query.
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getOQLQuery
```
public OQLQuery getOQLQuery(java.lang.String oql)
                     throws PersistenceException
```
    Creates an OQL query from the supplied statement.
    
    Specified by:
    
    getOQLQuery in interface Database
    
    Parameters:
    
    oql - An OQL query statement
    
    Returns:
    
    An OQL query
    
    Throws:
    
    PersistenceException
  - getQuery
```
public Query getQuery()
```
    Creates an empty query. The query must be created before it can be executed.
    
    Specified by:
    
    getQuery in interface Database
    
    Returns:
    
    A query
  - getTransaction
```
protected TransactionContext getTransaction()
                                     throws TransactionNotInProgressException
```
    Returns the currently active transaction, if any.
    
    Returns:
    
    The current active transaction.
    
    Throws:
    
    TransactionNotInProgressException - If there's no active transaction.
  - begin
```
public abstract void begin()
                    throws PersistenceException
```
    Begin a new transaction. A transaction must be open in order to query and persist objects.
    
    Specified by:
    
    begin in interface Database
    
    Throws:
    
    PersistenceException - A transaction is already open on this database, or an error reported by the persistence engine
  - commit
```
public abstract 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 Database.begin() to open a new transaction will not restore objects to their persistent stage.
    
    Specified by:
    
    commit in interface Database
    
    Throws:
    
    TransactionNotInProgressException - Method called while transaction is not in progress
    
    TransactionAbortedException - The transaction cannot commit and has been rolled back
  - rollback
```
public abstract 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.
    
    Specified by:
    
    rollback in interface Database
    
    Throws:
    
    TransactionNotInProgressException - Method called while transaction is not in progress
  - isActive
```
public boolean isActive()
```
    Returns true if a transaction is currently active.
    
    Specified by:
    
    isActive in interface Database
    
    Returns:
    
    True if a transaction is active
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - getJdbcConnection
```
public abstract 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.
    
    Specified by:
    
    getJdbcConnection in interface Database
    
    Returns:
    
    the underlying JDBC connection, if present; otherwise null
    
    Throws:
    
    PersistenceException - If the underlying JDBC connection cannot be obtained.
  - loadSynchronizables
```
protected void loadSynchronizables()
```
    Load the TxSynchronizable implementations from the properties file, if not loaded before.
  - registerSynchronizables
```
protected void registerSynchronizables()
```
    Register the TxSynchronizable implementations at the TransactionContect at end of begin().
  - unregisterSynchronizables
```
protected void unregisterSynchronizables()
```
    Unregister the TxSynchronizable implementations at the TransactionContect after commit() or rollback().
  - getCurrentTransaction
```
public TransactionContext getCurrentTransaction()
                                         throws TransactionNotInProgressException
```
    Gets the current Castor transaction in use.
    
    Returns:
    
    the current Castor
    
    Throws:
    
    TransactionNotInProgressException - If there's no transaction in progress.

Class AbstractDatabaseImpl

Field Summary

Fields inherited from interface org.exolab.castor.jdo.Database

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_scope

_ctx

_lockTimeout

_callback

_instanceFactory

_dbName

_autoStore

_classLoader

Constructor Detail

AbstractDatabaseImpl

Method Detail

getLockEngine

getScope

setAutoStore

isAutoStore

getClassLoader

getDatabaseName

close

isClosed

isLocked

load

load

load

create

getCacheManager

update

remove

isPersistent

getIdentity

lock

getOQLQuery

getNamedQuery

getNativeQuery

getOQLQuery

getQuery

getTransaction

begin

commit

rollback

isActive

toString

getJdbcConnection

loadSynchronizables

registerSynchronizables

unregisterSynchronizables

getCurrentTransaction