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();
begin
public void begin()
throws PersistenceException
Begin a new transaction. A transaction must be open in order
to query and persist objects.
PersistenceException
- A transaction is already open on
this database, or an error reported by the persistence engine
close
public 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.
commit
public 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.
create
public void create(Object object)
throws ClassNotPersistenceCapableException,
DuplicateIdentityException,
TransactionNotInProgressException,
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.
object
- The object to create
getCacheManager
public CacheManager getCacheManager()
Get's the CacheManager instance.
Call getCacheManager for every Database-instances.
- the CacheManager-instance.
getClassLoader
public ClassLoader getClassLoader()
Returns the current ClassLoader if one has been set for this Database instance.
- ClassLoader the current ClassLoader instance,
null
if no
ClassLoader's instance has been explicitely set.
getDatabaseName
public String getDatabaseName()
Return the name of the database
getIdentity
public Identity getIdentity(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.
- The object's identity, or null.
getJdbcConnection
public 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.
- the underlying JDBC connection, if present; otherwise null
getOQLQuery
public OQLQuery getOQLQuery()
getOQLQuery
public OQLQuery getOQLQuery(String oql)
throws PersistenceException
Creates an OQL query from the supplied statement.
oql
- An OQL query statement
getQuery
public Query getQuery()
Creates an empty query. The query must be created before
it can be executed.
isActive
public boolean isActive()
Returns true if a transaction is currently active.
- True if a transaction is active
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.
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.
- True if the current transaction is set to 'autoStore'.
isClosed
public boolean isClosed()
Returns true if the database is closed.
- True if the database is closed
isLocked
public boolean isLocked(Class cls,
Object identity)
throws PersistenceException
Returns true if the specified object is currently locked.
cls
- Class instance.identity
- Object identity.
- True if the object specified is locked; false otherwise.
isPersistent
public boolean isPersistent(Object object)
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.
- True if persistent in this transaction
load
public Object load(Class type,
Object identity)
throws TransactionNotInProgressException,
ObjectNotFoundException,
LockNotGrantedException,
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.
type
- The object's typeidentity
- The object's identity
load
public Object load(Class type,
Object identity,
Object object)
throws ObjectNotFoundException,
LockNotGrantedException,
TransactionNotInProgressException,
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.
type
- The object's typeidentity
- The object's identityobject
- The object instance to be loaded into
lock
public void lock(Object object)
throws LockNotGrantedException,
ObjectNotPersistentException,
TransactionNotInProgressException,
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.
object
- The object to lock
rollback
public 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.
setAutoStore
public void setAutoStore(boolean autoStore)
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.
autoStore
- True if this feature should be enabled.
update
public void update(Object object)
throws ClassNotPersistenceCapableException,
TransactionNotInProgressException,
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.
object
- The object to create