org.exolab.castor.jdo.engine

Class AbstractDatabaseImpl

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: 6230 $ $Date: 2006-04-22 11:05:30 -0600 (Sat, 22 Apr 2006) $

Author:

Assaf Arkin, Bruce Snyder

Field Summary

Fields

Modifier and Type	Field and 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 and 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

Modifier and Type	Method and 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	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 object is persistent.
java.lang.Object	load(java.lang.Class type, java.lang.Object identity) Load an object of the specified type and given identity.
java.lang.Object	load(java.lang.Class type, java.lang.Object identity, AccessMode mode) Load an object of the specified type and given identity.
java.lang.Object	load(java.lang.Class 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.
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

See Also:

Database.getScope()

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

Description copied from interface: Database

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

See Also:

Database.close()

isClosed

public boolean isClosed()

Description copied from interface: Database

Returns true if the database is closed.

Specified by:

isClosed in interface Database

Returns:

True if the database is closed

See Also:

Database.isClosed()

isLocked

public boolean isLocked(java.lang.Class cls,
                        java.lang.Object identity)
                 throws PersistenceException

Description copied from interface: Database

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

See Also:

Database.isLocked(java.lang.Class, java.lang.Object)

load

public java.lang.Object load(java.lang.Class type,
                             java.lang.Object identity)
                      throws ObjectNotFoundException,
                             LockNotGrantedException,
                             TransactionNotInProgressException,
                             PersistenceException

Description copied from interface: Database

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

See Also:

{@inheritDoc}

load

public java.lang.Object load(java.lang.Class type,
                             java.lang.Object identity,
                             java.lang.Object object)
                      throws TransactionNotInProgressException,
                             ObjectNotFoundException,
                             LockNotGrantedException,
                             PersistenceException

Description copied from interface: Database

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:

TransactionNotInProgressException - Method called while transaction is not in progress

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

PersistenceException - An error reported by the persistence engine

See Also:

{@inheritDoc}

load

public java.lang.Object load(java.lang.Class type,
                             java.lang.Object identity,
                             AccessMode mode)
                      throws TransactionNotInProgressException,
                             ObjectNotFoundException,
                             LockNotGrantedException,
                             PersistenceException

Description copied from interface: Database

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:

TransactionNotInProgressException - Method called while transaction is not in progress

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

PersistenceException - An error reported by the persistence engine

See Also:

{@inheritDoc}

create

public void create(java.lang.Object object)
            throws ClassNotPersistenceCapableException,
                   DuplicateIdentityException,
                   TransactionNotInProgressException,
                   PersistenceException

Description copied from interface: Database

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:

ClassNotPersistenceCapableException - The class is not persistent capable

DuplicateIdentityException - An object with this identity already exists in persistent storage

TransactionNotInProgressException - Method called while transaction is not in progress

PersistenceException - An error reported by the persistence engine

See Also:

Database.create(java.lang.Object)

getCacheManager

public CacheManager getCacheManager()

Description copied from interface: Database

Get's the CacheManager instance. Call getCacheManager for every Database-instances.

Specified by:

getCacheManager in interface Database

Returns:

the CacheManager-instance.

See Also:

Database.getCacheManager()

update

public void update(java.lang.Object object)
            throws ClassNotPersistenceCapableException,
                   ObjectModifiedException,
                   TransactionNotInProgressException,
                   PersistenceException

Description copied from interface: Database

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:

ClassNotPersistenceCapableException - The class is not persistent capable

TransactionNotInProgressException - Method called while transaction is not in progress

PersistenceException - An error reported by the persistence engine

ObjectModifiedException

See Also:

Database.update(java.lang.Object)

remove

public void remove(java.lang.Object object)
            throws ObjectNotPersistentException,
                   LockNotGrantedException,
                   TransactionNotInProgressException,
                   PersistenceException

Description copied from interface: Database

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:

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

TransactionNotInProgressException - Method called while transaction is not in progress

PersistenceException - An error reported by the persistence engine

See Also:

Database.remove(java.lang.Object)

isPersistent

public boolean isPersistent(java.lang.Object object)

Description copied from interface: Database

Returns true if the object is persistent. An object is persistent if it was created or queried in this transaction. If the object was created or queried in another transaction, or there is no open transaction, this method returns null.

Specified by:

isPersistent in interface Database

Parameters:

object - The object

Returns:

True if persistent in this transaction

See Also:

Database.isPersistent(java.lang.Object)

getIdentity

public Identity getIdentity(java.lang.Object object)
                     throws PersistenceException

Description copied from interface: Database

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.

See Also:

Database.getIdentity(java.lang.Object)

lock

public void lock(java.lang.Object object)
          throws LockNotGrantedException,
                 ObjectNotPersistentException,
                 TransactionNotInProgressException,
                 PersistenceException

Description copied from interface: Database

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:

LockNotGrantedException - Timeout or deadlock occured attempting to acquire a lock on the object

ObjectNotPersistentException - The object has not been queried or created in this transaction

TransactionNotInProgressException - Method called while transaction is not in progress

PersistenceException - An error reported by the persistence engine

See Also:

Database.lock(java.lang.Object)

getOQLQuery

public OQLQuery getOQLQuery()

Description copied from interface: Database

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

See Also:

Database.getOQLQuery()

getNamedQuery

public OQLQuery getNamedQuery(java.lang.String name)
                       throws PersistenceException

Description copied from interface: Database

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

See Also:

Database.getNamedQuery(java.lang.String)

getOQLQuery

public OQLQuery getOQLQuery(java.lang.String oql)
                     throws PersistenceException

Description copied from interface: Database

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

See Also:

Database.getOQLQuery(java.lang.String)

getQuery

public Query getQuery()

Description copied from interface: Database

Creates an empty query. The query must be created before it can be executed.

Specified by:

getQuery in interface Database

Returns:

A query

See Also:

Database.getQuery()

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

Description copied from interface: Database

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

See Also:

Database.begin()

commit

public abstract void commit()
                     throws TransactionNotInProgressException,
                            TransactionAbortedException

Description copied from interface: Database

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

See Also:

Database.commit()

rollback

public abstract void rollback()
                       throws TransactionNotInProgressException

Description copied from interface: Database

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

See Also:

Database.rollback()

isActive

public boolean isActive()

Description copied from interface: Database

Returns true if a transaction is currently active.

Specified by:

isActive in interface Database

Returns:

True if a transaction is active

See Also:

Database.isActive()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

getJdbcConnection

public abstract java.sql.Connection getJdbcConnection()
                                               throws PersistenceException

Description copied from interface: Database

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.

See Also:

Database.getJdbcConnection()

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.