org.exolab.castor.jdo.engine
Class DatabaseImpl

java.lang.Object
  extended byorg.exolab.castor.jdo.engine.DatabaseImpl
All Implemented Interfaces:
Database, javax.transaction.Synchronization

public class DatabaseImpl
extends java.lang.Object
implements Database, javax.transaction.Synchronization

An implementation of the JDO database supporting explicit transaction demaracation.

Version:
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:16 $
Author:
Assaf Arkin

Field Summary
protected  TransactionContext _ctx
          The transaction context is this database was accessed with an XAResource.
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
DatabaseImpl(java.lang.String dbName, int lockTimeout, LogInterceptor logInterceptor, CallbackInterceptor callback, InstanceFactory instanceFactory, javax.transaction.Transaction transaction, java.lang.ClassLoader classLoader, boolean autoStore)
           
 
Method Summary
 void afterCompletion(int status)
           
 void beforeCompletion()
           
 void begin()
          Begin a new transaction.
 void checkpoint()
          Deprecated. Use commit() and rollback() instead
 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.
 void deletePersistent(java.lang.Object object)
          Deprecated.  
protected  void finalize()
           
 java.lang.ClassLoader getClassLoader()
          Gets the current application ClassLoader's instance.
 java.lang.Object getConnection()
          Get the underlying JDBC Connection.
 java.lang.String getDatabaseName()
          } Return the name of the database
 java.lang.Object getIdentity(java.lang.Object object)
          Returns the object's identity.
(package private)  LockEngine getLockEngine()
           
 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()
           
 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(java.lang.Object object)
          Returns true if the object is persistent.
 java.lang.Object load(java.lang.Class type, Complex identity)
          Load an object of the specified type and given identity which spans on more than one fields.
 java.lang.Object load(java.lang.Class type, Complex identity, short accessMode)
          Experimental
 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, java.lang.Object object)
          Experimental
 java.lang.Object load(java.lang.Class type, java.lang.Object identity, short accessMode)
          Experimental
 void lock(java.lang.Object object)
          Acquire a soft write lock on the object.
 void makePersistent(java.lang.Object object)
          Deprecated.  
 void remove(java.lang.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.
(package private)  void setTxMap(TxDatabaseMap txMap)
           
 java.lang.String toString()
           
 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, 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.

Constructor Detail

DatabaseImpl

public DatabaseImpl(java.lang.String dbName,
                    int lockTimeout,
                    LogInterceptor logInterceptor,
                    CallbackInterceptor callback,
                    InstanceFactory instanceFactory,
                    javax.transaction.Transaction transaction,
                    java.lang.ClassLoader classLoader,
                    boolean autoStore)
             throws DatabaseNotFoundException
Method Detail

getLockEngine

LockEngine getLockEngine()

getScope

public PersistenceInfoGroup getScope()
Specified by:
getScope in interface Database

setAutoStore

public void setAutoStore(boolean autoStore)
Description copied from interface: Database
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/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.

Specified by:
setAutoStore in interface Database

isAutoStore

public boolean isAutoStore()
Description copied from interface: Database
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.

Specified by:
isAutoStore in interface Database

getClassLoader

public java.lang.ClassLoader getClassLoader()
Gets the current application ClassLoader's instance. For use in OQLQueryImpl and TransactionContext.

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

close

public 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

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

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
Experimental

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
Throws:
PersistenceException - An error reported by the persistence engine
ObjectNotFoundException - No object of the given type and identity was found in persistent storage
TransactionNotInProgressException - Method called while transaction is not in progress
LockNotGrantedException - Timeout or deadlock occured attempting to acquire a lock on the object

load

public java.lang.Object load(java.lang.Class type,
                             Complex identity)
                      throws TransactionNotInProgressException,
                             ObjectNotFoundException,
                             LockNotGrantedException,
                             PersistenceException
Description copied from interface: Database
Load an object of the specified type and given identity which spans on more than one fields.

Specified by:
load in interface Database
Parameters:
type - The object's type
identity - The object's identity
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
PersistenceException - An error reported by the persistence engine
TransactionNotInProgressException - Method called while transaction is not in progress

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
Throws:
TransactionNotInProgressException - Method called while transaction is not in progress
ObjectNotFoundException - No object of the given type and identity was found in persistent storage
PersistenceException - An error reported by the persistence engine
LockNotGrantedException - Timeout or deadlock occured attempting to acquire a lock on the object

load

public java.lang.Object load(java.lang.Class type,
                             Complex identity,
                             short accessMode)
                      throws TransactionNotInProgressException,
                             ObjectNotFoundException,
                             LockNotGrantedException,
                             PersistenceException
Description copied from interface: Database
Experimental

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
accessMode - The access mode
Throws:
PersistenceException - An error reported by the persistence engine
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

load

public java.lang.Object load(java.lang.Class type,
                             java.lang.Object identity,
                             short accessMode)
                      throws ObjectNotFoundException,
                             LockNotGrantedException,
                             TransactionNotInProgressException,
                             PersistenceException
Description copied from interface: Database
Experimental

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
accessMode - The access mode
Throws:
TransactionNotInProgressException - Method called while transaction is not in progress
LockNotGrantedException - Timeout or deadlock occured attempting to acquire a lock on the object
ObjectNotFoundException - No object of the given type and identity was found in persistent storage
PersistenceException - An error reported by the persistence engine

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:
TransactionNotInProgressException - Method called while transaction is not in progress
PersistenceException - An error reported by the persistence engine
ClassNotPersistenceCapableException - The class is not persistent capable
DuplicateIdentityException - An object with this identity already exists in persistent storage

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

makePersistent

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

Specified by:
makePersistent in interface Database
Throws:
ClassNotPersistenceCapableException
DuplicateIdentityException
TransactionNotInProgressException
PersistenceException

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:
PersistenceException - An error reported by the persistence engine
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

deletePersistent

public void deletePersistent(java.lang.Object object)
                      throws ObjectNotPersistentException,
                             LockNotGrantedException,
                             PersistenceException
Deprecated.  

Specified by:
deletePersistent in interface Database
Throws:
ObjectNotPersistentException
LockNotGrantedException
PersistenceException

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

getIdentity

public java.lang.Object getIdentity(java.lang.Object object)
Description copied from interface: Database
Returns the object's identity. If the identity was determined when the object was created, or if the object was retrieved, that identity is returned. If the identity has been modified, this will not be reflected until the transaction commits. Null is returned if the identity is null, the object does not have any identity, or the object is not persistent.

Specified by:
getIdentity in interface Database
Parameters:
object - The object
Returns:
The object's identity, or null

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
TransactionNotInProgressException - Method called while transaction is not in progress
ObjectNotPersistentException - The object has not been queried or created in this transaction
PersistenceException - An error reported by the persistence engine

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

getOQLQuery

public OQLQuery getOQLQuery(java.lang.String oql)
                     throws QueryException
Description copied from interface: Database
Creates an OQL query from the supplied statement.

Specified by:
getOQLQuery in interface Database
Returns:
An OQL query
Throws:
QueryException - The query syntax is invalid

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

finalize

protected void finalize()
                 throws java.lang.Throwable
Throws:
java.lang.Throwable

getTransaction

protected TransactionContext getTransaction()
                                     throws TransactionNotInProgressException
Throws:
TransactionNotInProgressException

begin

public 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

commit

public 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

rollback

public 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

beforeCompletion

public void beforeCompletion()
Specified by:
beforeCompletion in interface javax.transaction.Synchronization

afterCompletion

public void afterCompletion(int status)
Specified by:
afterCompletion in interface javax.transaction.Synchronization

setTxMap

void setTxMap(TxDatabaseMap txMap)

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

checkpoint

public void checkpoint()
                throws TransactionNotInProgressException,
                       TransactionAbortedException
Deprecated. Use commit() and rollback() instead

Specified by:
checkpoint in interface Database
Throws:
TransactionNotInProgressException
TransactionAbortedException

toString

public java.lang.String toString()

getConnection

public java.lang.Object getConnection()
                               throws PersistenceException
Get the underlying JDBC Connection. Only for internal / advanced use ! Never try to close it (is done by castor).

Throws:
PersistenceException


Intalio Inc. (C) 1999-2003. All rights reserved http://www.intalio.com