The Java Data Objects API

Version:
  $Revision: 1.4 $ $Date: 2005/04/21 20:21:05 $
Author:
  Assaf Arkin

The class {@link org.exolab.castor.jdo.JDOManager} 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 {@link org.exolab.castor.jdo.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 {@link org.exolab.castor.jdo.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.

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

      // Define a new database source
      JDOManager.loadConfiguration ("jdo-conf.xml");
      JDOManager jdo = JDOManager.createInstance ( "mydb" );

      // 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();

A {@link org.exolab.castor.jdo.CacheManager} instance can be optained by issueing the following code:

Database db = jdo.getDatabase(); CacheManager manager = ((DatabaseImpl) db.getCacheManager();

This instance can subsequently be used to selectively clear the Castor performance cache one of the {@link org.exolab.castor.jdo.CacheManager#clearCache()} methods.