|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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();
JDO.getDatabase()
,
Query
Field Summary | |
static short |
DbLocked
Database lock access. |
static short |
Exclusive
Exclusive access. |
static short |
ReadOnly
Read only access. |
static short |
Shared
Shared access. |
Method Summary | |
void |
begin()
Begin a new transaction. |
void |
checkpoint()
Deprecated. Use commit() and rollback() instead;
this method cannot be implemented properly with multiple type
of locks and will not be supported in future versions of the
API |
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. See remove(java.lang.Object) |
java.lang.ClassLoader |
getClassLoader()
Returns the current ClassLoader if one has been set for this Database instance. |
java.lang.Object |
getIdentity(java.lang.Object object)
Returns the object's identity. |
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. |
org.exolab.castor.persist.PersistenceInfoGroup |
getScope()
|
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,
org.exolab.castor.persist.spi.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,
org.exolab.castor.persist.spi.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,
short accessMode)
Experimental |
void |
lock(java.lang.Object object)
Acquire a soft write lock on the object. |
void |
makePersistent(java.lang.Object object)
Deprecated. See create(java.lang.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)
True if autoStore is set on. |
void |
update(java.lang.Object object)
Experimental |
Field Detail |
public static final short ReadOnly
load(java.lang.Class, java.lang.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.
public static final short Shared
load(java.lang.Class, java.lang.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.
public static final short Exclusive
load(java.lang.Class, java.lang.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.
public static final short DbLocked
load(java.lang.Class, java.lang.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 |
public OQLQuery getOQLQuery()
OQLQuery.create(java.lang.String)
must be called before the query can be executed.public OQLQuery getOQLQuery(java.lang.String oql) throws QueryException
query
- An OQL query statementpublic Query getQuery()
public org.exolab.castor.persist.PersistenceInfoGroup getScope()
public java.lang.Object load(java.lang.Class type, java.lang.Object identity) throws TransactionNotInProgressException, ObjectNotFoundException, LockNotGrantedException, PersistenceException
type
- The object's typeidentity
- The object's identitypublic java.lang.Object load(java.lang.Class type, org.exolab.castor.persist.spi.Complex identity) throws ObjectNotFoundException, LockNotGrantedException, TransactionNotInProgressException, PersistenceException
type
- The object's typeidentity
- The object's identitypublic java.lang.Object load(java.lang.Class type, java.lang.Object identity, short accessMode) 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.
type
- The object's typeidentity
- The object's identityaccessMode
- The access modepublic java.lang.Object load(java.lang.Class type, org.exolab.castor.persist.spi.Complex identity, short accessMode) throws ObjectNotFoundException, LockNotGrantedException, TransactionNotInProgressException, 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 identityaccessMode
- The access modepublic void create(java.lang.Object object) throws ClassNotPersistenceCapableException, DuplicateIdentityException, TransactionNotInProgressException, PersistenceException
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 createpublic void remove(java.lang.Object object) throws ObjectNotPersistentException, LockNotGrantedException, TransactionNotInProgressException, PersistenceException
object
- The object to removepublic void update(java.lang.Object object) throws ClassNotPersistenceCapableException, 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 createpublic void lock(java.lang.Object object) throws LockNotGrantedException, ObjectNotPersistentException, TransactionNotInProgressException, PersistenceException
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 lockpublic void begin() throws PersistenceException
public boolean isAutoStore()
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.
public void setAutoStore(boolean autoStore)
public void commit() throws TransactionNotInProgressException, TransactionAbortedException
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.
public void rollback() throws TransactionNotInProgressException
public boolean isActive()
public boolean isClosed()
public void close() throws PersistenceException
public boolean isPersistent(java.lang.Object object)
object
- The objectpublic java.lang.Object getIdentity(java.lang.Object object)
object
- The objectpublic java.lang.ClassLoader getClassLoader()
null
if no
ClassLoader's instance has been explicitely set.public void makePersistent(java.lang.Object object) throws ClassNotPersistenceCapableException, DuplicateIdentityException, PersistenceException
create(java.lang.Object)
public void deletePersistent(java.lang.Object object) throws ObjectNotPersistentException, LockNotGrantedException, PersistenceException
remove(java.lang.Object)
public void checkpoint() throws TransactionNotInProgressException, TransactionAbortedException
commit()
and rollback()
instead;
this method cannot be implemented properly with multiple type
of locks and will not be supported in future versions of the
API
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |