Package org.exolab.castor.jdo

The Java Data Objects API

See:
Description

Interface Summary

Database	An open connection to the database.
DataObjects	A factory for Database connections.
OQLQuery	An OQL query object.
Persistent	A callback informs objects about changes to their state.
Query	A query object.
QueryResults	An iteration of the results of a query.
TimeStampable	A callback get/set the timestamp.

Class Summary

JDO	Implementation of the JDO engine used for obtaining database connection.

Exception Summary

ClassNotPersistenceCapableException	Exception thrown to indicate objects of this class are not persistent capable.
DatabaseNotFoundException	This exception is thrown when attempting to open a database that does not exist.
DataObjectAccessException	An exception encapsulating another exception which occurs during operation to data object.
DuplicateIdentityException	Exception indicating that a duplicate identity has been found and an object with the same identity already exists in persistent storage.
FatalPersistenceException	A fatal exception indicates the persistence engine is no longer usable.
LockNotGrantedException	Exception thrown when failed to acquire a lock on an object, a timeout occured waiting to acquire the lock, or a deadlock has been detected.
ObjectDeletedException	This exception is thrown when accessing an object that was deleted.
ObjectModifiedException	Indicates transaction has been aborted as a result of object being modified by a concurrent transaction.
ObjectNotFoundException	An attempt to load an object failed, an object of that type with that primary key was not found in persistent storage.
ObjectNotPersistentException	Exception indicating object is not persistent.
PersistenceException	An exception representing another exception (an SQL exception, a JNDI naming exception, etc) raised by the underlying persistence engine.
QueryException	Reports an exception with the query, either syntax, query parameters or inability to perform the query against the persistence engine.
TransactionAbortedException	Informs that the user transaction has been explicitly aborted by the database due to some failure and the reason for that failure.
TransactionNotInProgressException	Indicates the operation cannot be performed since a transaction is not in progress.

Package org.exolab.castor.jdo Description

The Java Data Objects API

Version:

$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:08 $

Author:

Assaf Arkin

The class JDO provides the Castor JDO engine used for obtaining database connection. A JDO object is constructed with the name of a database and other properties, and getDatabase} is used to obtain a new database connection.

The class Database 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.

The class OQLQuery is obtained from the database and used to construct and execute a query on that database. All query operations are bound to the database transaction.

The following example opens a connection to the database 'mydb' configured from the configuration file 'database.xml', retrieves all the products in the specified groups and marks them down with a 25% discount and on-sale status.

  JDO          jdo;
  Database     db;
  Query        oql;
  QueryResults results;

  // Define a new database source
  jdo = new JDO( "mydb" );
  jdo.setConfiguration( "database.xml" );

  // Open a new database, begin a transaction
  db = jdo.getDatabase();
  db.begin();

  // Select all the products in a given group
  oql = db.getQuery( "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();