|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Database
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();
JDOManager.getDatabase()
,
Query
Field Summary | |
---|---|
static AccessMode |
DbLocked
Deprecated. Use DBLOCKED instead. |
static AccessMode |
DBLOCKED
Database lock access. |
static AccessMode |
Exclusive
Deprecated. Use EXCLUSIVE instead. |
static AccessMode |
EXCLUSIVE
Exclusive access. |
static AccessMode |
ReadOnly
Deprecated. Use READONLY instead. |
static AccessMode |
READONLY
Read only access. |
static AccessMode |
Shared
Deprecated. Use SHARED instead. |
static AccessMode |
SHARED
Shared access. |
Method Summary | ||
---|---|---|
void |
begin()
Begin a new transaction. |
|
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. |
|
CacheManager |
getCacheManager()
Get's the CacheManager instance. |
|
java.lang.ClassLoader |
getClassLoader()
Returns the current ClassLoader if one has been set for this Database instance. |
|
java.lang.String |
getDatabaseName()
Return the name of the database. |
|
Identity |
getIdentity(java.lang.Object object)
Returns the object's identity. |
|
java.sql.Connection |
getJdbcConnection()
Gets the underlying JDBC connection. |
|
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()
|
|
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 entity)
Returns true if the entity is persistent. |
|
|
load(java.lang.Class<T> type,
java.lang.Object identity)
Load an object of the specified type and given identity. |
|
|
load(java.lang.Class<T> type,
java.lang.Object identity,
AccessMode mode)
Load an object of the specified type and given identity. |
|
|
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. |
|
void |
lock(java.lang.Object object)
Acquire a soft write lock on the 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)
Update a data object which is queried/loaded/created in another transaction. |
Field Detail |
---|
static final AccessMode READONLY
load(Class,Object)
method to load
objects as read-only.
static final AccessMode ReadOnly
load(Class,Object)
method to load
objects as read-only.
static final AccessMode SHARED
load(Class,Object)
method to load
objects with shared access.
static final AccessMode Shared
load(Class,Object)
method to load
objects with shared access.
static final AccessMode EXCLUSIVE
load(Class,Object)
method to load
objects with exclusive access.
static final AccessMode Exclusive
load(Class,Object)
method to load
objects with exclusive access.
static final AccessMode DBLOCKED
load(Class,Object)
method to
load objects with a database lock.
static final AccessMode DbLocked
load(Class,Object)
method to
load objects with a database lock.
Method Detail |
---|
OQLQuery getOQLQuery()
OQLQuery.create(java.lang.String)
must be called before the query can be executed.
OQLQuery getOQLQuery(java.lang.String oql) throws PersistenceException
oql
- An OQL query statement
PersistenceException
Query getQuery()
OQLQuery getNamedQuery(java.lang.String name) throws PersistenceException
OQLQuery.create(java.lang.String)
name
- Name of the (named) query to create.
PersistenceException
OQLQuery getNativeQuery(java.lang.String sql, java.lang.Class<?> result) throws PersistenceException
sql
- Native SQL query to be used.result
- Class that is result of the query.
PersistenceException
PersistenceInfoGroup getScope()
java.lang.String getDatabaseName()
<T> T load(java.lang.Class<T> type, java.lang.Object identity) throws PersistenceException
type
- The object's typeidentity
- The object's identity
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<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.
type
- The object's typeidentity
- The object's identitymode
- The access mode
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<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.
type
- The object's typeidentity
- The object's identityobject
- The object instance to be loaded into
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 enginevoid create(java.lang.Object object) throws 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 create
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 enginevoid remove(java.lang.Object object) throws PersistenceException
object
- The object to remove
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 enginevoid update(java.lang.Object object) throws PersistenceException
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
TransactionNotInProgressException
- Method called while
transaction is not in progress
ClassNotPersistenceCapableException
- The class is not
persistent capable
PersistenceException
- An error reported by the
persistence enginevoid lock(java.lang.Object object) throws 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 lock
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 enginevoid begin() throws PersistenceException
PersistenceException
- A transaction is already open on
this database, or an error reported by the persistence engineboolean 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.
void setAutoStore(boolean autoStore)
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.void commit() throws TransactionNotInProgressException, TransactionAbortedException
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.
TransactionNotInProgressException
- Method called while
transaction is not in progress
TransactionAbortedException
- The transaction cannot
commit and has been rolled backvoid rollback() throws TransactionNotInProgressException
TransactionNotInProgressException
- Method called while
transaction is not in progressboolean isActive()
boolean isClosed()
boolean isLocked(java.lang.Class cls, java.lang.Object identity) throws PersistenceException
cls
- Class instance.identity
- Object identity.
PersistenceException
void close() throws PersistenceException
PersistenceException
- An error occured while
attempting to close the databaseboolean isPersistent(java.lang.Object entity)
entity
- The entity.
Identity getIdentity(java.lang.Object object) throws PersistenceException
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.
object
- The object.
PersistenceException
- The class is not persistent capable.java.lang.ClassLoader getClassLoader()
null
if no
ClassLoader's instance has been explicitely set.CacheManager getCacheManager()
java.sql.Connection getJdbcConnection() throws PersistenceException
PersistenceException
- If the underlying JDBC connection cannot be obtained.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |