Client applications are responsible for defining the JDO configuration, and managing the transaction explicitly. The database is by default configured through a separate XML file which links to the mapping file. Alternatively, it can be configured using the utility class org.exolab.castor.jdo.util.JDOConfFactory.

In the example code I refer to the JDO configuration file as jdo-conf.xml, but any name can be used. See Castor JDO Configuration for more information.

As of release 0.9.6, a new JDOManager class is provided, that replaces the former JDO class. Any new features will be implemented against the new JDOManager class only.

As with its predecessor, org.exolab.castor.jdo.JDOManager defines the database name and properties and is used to open a database connection. An instance of this class is constructed with a two-step approach:

The org.exolab.castor.jdo.Database object represents an open connection to the database. By definition the database object is not thread safe and should not be used from concurrent threads. There is little overhead involved in opening multiple Database objects, and a JDBC connection is acquired only per open transaction.

The following code fragment creates an instance of JDOManager for a database 'mybd', opens a database, performs a transaction, and closes the database - as it will typically appear in client applications (for brevity, we have ommitted any required exception handling):

 
JDOManager jdoManager;
Database db;
 
// load the JDO configuration file and construct a new JDOManager for the database 'mydb'
JDOManager.loadConfiguration("jdo-conf.xml");
jdoManager = JDOManager.createInstance("mydb");

// Obtain a new database
Database db = jdoManager.getDatabase();
    
// Begin a transaction
db.begin();

// Do something
. . .

// Commit the transaction and close the database
db.commit();
db.close();
        

For an example showing how to set up a database configuration on the fly without the need of a preconfigured XML configuration file) see JdoConfFactory.

J2EE applications depend on the J2EE container (Servlet, EJB, etc) to configure the database connection and use JNDI to look it up. This model allows the application deployer to configure the database properties from a central place, and gives the J2EE container the ability to manage distributed transactions across multiple data sources.

Instead of constructing a org.exolab.castor.jdo.JDOManager the application uses the JNDI namespace to look it up. We recommend enlisting the JDOManager object under the java:comp/env/jdo namespace, compatible with the convention for listing JDBC resources.

The following code fragment uses JNDI to lookup a database, and uses the JTA UserTransaction interface to manage the transaction:

InitialContext  ctx;
UserTransaction ut;
Database        db;

// Lookup databse in JNDI
ctx = new InitialContext();
db = (Database) ctx.lookup( "java:comp/env/jdo/mydb" );

// Begin a transaction
ut = (UserTransaction) ctx.lookup( "java:comp/UserTransaction" );
ut.begin();
// Do something
. . .
// Commit the transaction, close database
ut.commit();
db.close();
        

If the transaction is managed by the container, a common case with EJB beans and in particular entity beans, there is no need to begin/commit the transaction explicitly. Instead the application server takes care of enlisting the database in the ongoing transaction and executes commit/rollback at the proper time.

The following code snippet relies on the container to manage the transaction

InitialContext  ctx;
UserTransaction ut;
Database        db;

// Lookup database in JNDI
ctx = new InitialContext();
db = (Database) ctx.lookup( "java:comp/env/jdo/mydb" );

// Do something
. . .
// Close the database
db.close();
        

All JDO operations occur within the context of a transaction. JDO works by loading data from the database into an object in memory, allowing the application to modify the object, and then storing the object's new state when the transaction commits. All objects can be in one of two states: transient or persistent.

Transient: Any object whose state will not be saved to the database when the transaction commits. Changes to transient objects will not be reflected in the database.

Persistent: Any object whose state will be saved to the database when the transaction commits. Changes to persistent objects will be reflected in the database.

An object becomes persistent in one of two ways: it is the result of a query, (and the query is not performed in read-only mode) or it is added to the database using org.exolab.castor.jdo.Database.create(java.lang.Object) or org.exolab.castor.jdo.Database.update(java.lang.Object). All objects that are not persistent are transient. When the transaction commits or rolls back, all persistent objects become transient.

In a client application, use org.exolab.castor.jdo.Database.begin(), org.exolab.castor.jdo.Database.commit() and org.exolab.castor.jdo.Database.rollback() to manage transactions. In a J2EE application, JDO relies on the container to manage transactions either implicitly (based on the transaction attribute of a bean) or explicitly using the javax.transaction.UserTransaction interface.

If a persistent object was modified during the transaction, at commit time the modifications are stored back to the database. If the transaction rolls back, no modifications will be made to the database. Once the transaction completes, the object is once again transient. To use the same object in two different transactions, you must query it again.

An object is transient or persistent from the view point of the database to which the transaction belongs. An object is generally persistent in a single database, and calling org.exolab.castor.jdo.Database">isPersistent(java.lang.Object) from another database will return false. It is possible to make an object persistent in two database, e.g. by querying it in one, and creating it in the other.

OQL queries are used to lookup and query objects from the database. OQL queries are similar to SQL queries, but use object names instead of SQL names and do not require join clauses. For example, if the object being loaded is of type TestObject, the OQL query will load FROM TestObject, whether the actual table name in the database is test, test_object, or any other name. If a join is required to load related objects, Castor will automatically perform the join.

The following code snippet uses an OQL query to load all the objects in a given group. Note that product and group are related objects, the JDBC query involves a join:

OQLQuery     oql;
QueryResults results;

// Explicitly begin transaction
db.begin();

// Construct a new query and bind its parameters
oql = db.getOQLQuery("SELECT p FROM Product p WHERE Group=$1");
oql.bind(groupId);

// Retrieve results and print each one
results = oql.execute();
while (results.hasMore()) {
  System.out.println(results.next());
}

// Explicitly close the QueryResults
results.close();

// Explicitly close the OQLQuery
oql.close();

// Explicitly commit transaction
db.commit();
db.close();
        

The following code snippet uses the previous query to obtain products, mark down their price by 25%, and store them back to the database (in this case using a client application transaction):

OQLQuery     oql;
QueryResults results;

// Explicitly begin transaction
db.begin();

// Construct a new query and bind its parameters
oql = db.getOQLQuery("SELECT p FROM Product p WHERE Group=$1");
oql.bind(groupId);

// Retrieve results and mark up each one by 25%
Product prod;
while (results.hasMore()) {
  prod = (Product) results.next();
  prod.markDown(0.25);
  prod.setOnSale(true);
}

// Explicitly close the QueryResults
results.close();

// Explicitly close the OQLQuery
oql.close();

// Explicitly commit transaction
db.commit();
db.close();
        

As illustrated above, a query is executed in three steps. First a query object is created from the database using an OQL statement. If there are any parameters, the second step involves binding these parameters. Numbered parameters are bound using the order specified in their names. (e.g. first $1, after that $2, and so on...) The third step involves executing the query and obtaining a result set of type org.exolab.castor.jdo.QueryResults.

A query can be created once and executed multiple times. Each time it is executed the bound parameters are lost, and must be supplied a second time. The result of a query can be used while the query is being executed a second time.

There is also a special form of query that gives a possibility to call stored procedures:

oql = db.getOQLQuery("CALL sp_something($) AS myapp.Product");

Here sp_something is a stored procedure returning one or more ResultSets with the same sequence of fields as Castor-generated SELECT for the OQL query "SELECT p FROM myapp.Product p" (for objects without relations the sequence is: identity, then all other fields in the same order as in mapping.xml).

The method org.exolab.castor.jdo.Database.create(java.lang.Object) creates a new object in the database, or in JDO terminology makes a transient object persistent. An object created with the create method will remain in the database if the transaction commits; if the transaction rolls back the object will be removed from the database. An exception is thrown if an object with the same identity already exists in the database.

The following code snippet creates a new product with a group that was previously queried:

Database db = ...;
db.begin();        

//load product group
ProductGroup furnitures = db.load(...);

// Create the Product object
Product prod;
prod = new Product();
prod.setSku(5678);
prod.setName("Plastic Chair");
prod.setPrice(55.0 );
prod.setGroup(furnitures);

// Make it persistent
db.create(prod);

db.commit();
        

The method org.exolab.castor.jdo.Database.remove(java.lang.Object) has the reverse effect, deleting a persistent object. Once removed the object is no longer visible to any transaction. If the transaction commits, the object will be removed from the database, however, if the transaction rolls back the object will remain in the database. An exception is thrown when attempting to remove an object that is not persistent.

The following code snippet deletes the previously created Product instance:

Database db = ...;
db.begin();        

// load the Product instance with sku = 5678
Product prod = db.load (Product.class, new Integer(5678);

// delete the Product instance
db.remove(prod);

db.commit();
        

There's no special method offering on the org.exolab.castor.jdo.Database to update an existing persistent object. Simply load the object to be updated, change one or more of its properties, and commit the transaction. Castor JDO will automatically figure that that the object in question has changed and will persist these changes to the underlying database.

The following code snippet loads a previously created Product instance, changes its description property and commits the transaction.

Database db = ...;
db.begin();        

// load the Product instance with sku = 5678
Product prod = db.load (Product.class, new Integer(5678);

// change the object properties
prod.setDescription("New plastic chair");

//commit the transaction
db.commit();
        

As opposed to release pre 0.9.6, transaction demarcation is now configured in the JDO configuration file. As such, the user has to specify which transaction demarcation to use. Transactions when used with Castor JDO can either be local or global, and you instruct Castor to use a specific mode by supplying a <transaction-demarcation> element.

<transaction-demarcation mode="local" />
           

3.4.1.1.2. Global Mode

When running inside a J2EE application server, and you want to use global (XA) transactions, please make use the <transaction-demarcation> element as follows:

<transaction-demarcation mode="global">
   <transaction-manager name="jndi" />
</transaction-demarcation>
           

In this mode, the <transaction-manager> element specifies the transaction manager that is used by your J2EE container to control these transactions.

The following transaction managers are supported in Castor:

Table 3.2. Supported transaction managers

Name	Description
jndi	TM looked up in the JNDI ENC
websphere	IBM WebSphere 4 and previous releases
websphere5	IBM WebSphere 5
websphere51	IBM WebSphere 5.1
jotm	JOTM
atomikos	Atomikos

In addition to specifying the transaction manager name, it is possible to pass arbitrary name/value pairs to the transaction manager instance.

	Note
	At the moment, only the JNDI transaction manager factory supports such an attribute. In this context, the jndiEnc attribute can be used to specify what JNDI ENC to use to lookup the transaction manager as shown below:

  <transaction-demarcation mode="global">
     <transaction-manager name="jndi">
        <param name="jndiEnc" value="java:comp/env/TransactionManager"/>
     </transaction-manager>
  </transaction-demarcation>

The following configuration file instructs Castor JDO to execute against an Oracle RDBMS using the thin (type 4) JDBC driver, and refers to three mapping files that define mappings for product, order and customer related data.

  <?xml version="1.0"?>
  <jdo-conf name="order-system">
     <database name="ebiz" engine="oracle">
        <driver class-name="oracle.jdbc.driver.OracleDriver"
                url="jdbc:oracle:thin:@machine:post:SID">
           <param name="user" value="scott"/>
           <param name="password" value="tiger"/>
        </driver>
        <mapping href="products.xml"/>
        <mapping href="orders.xml"/>
        <mapping href="customers.xml"/>
     </database>
     <transaction-demarcation mode="local"/>
  </jdo-conf>

The following configuration file uses a connection obtained from the J2EE application server and a single mapping file:

  <?xml version="1.0"?>
  <jdo-conf>
     <database name="ebiz" engine="oracle">
        <jndi name="java:comp/env/jdbc/mydb"/>
        <mapping href="ebiz.xml"/>
     </database>
     <transaction-demarcation mode="global">
        <transaction-manager name="jndi">
           <param name="jndiEnc" value="java:comp/env/TransactionManager"/>
        </transaction-manager>
     </transaction-demarcation>
  </jdo-conf>

Castor JDO uses JDBC prepared statements to execute SQL statements against the specified RDBMS of your choice. Per definition, Castor JDO does not provide any prepared statement pooling. As such, Castor relies on prepared statement pooling being provided by different means.

One such way is to use Jakarta's Commons DBCP as database connection pool, and to turn prepared statement pooling on by configuring DBCP accordingly.

Please check with Using Pooled Database Connections for general information about hot to use DBCP with Castor.

Besides the examples listed above, more configuraton examples can be found in the configuration files for the Castor JDO tests, which can be found in src/tests/jdo once you have downloaded and expanded the Castor source package. For each database (vendor) supported, you are going to find a database-specific JDO configuration file in this directory, e.g. src/tests/jdo/mysql.xml for mySQL™ or src/tests/jdo/oracle.xml for Oracle™.

  ...
  <!-- JDBC data source for Sybase using jConnect -->
  <data-source class-name="com.sybase.jdbc2.jdbc.SybDataSource">
    <param name="user" value="user" />
    <param name="password value="secret" />
    <param name="portNumber" value="4100" />
    <param name="serverName" value="host" />
  </data-source>
  ...

  ...
  <!-- JDBC data source for PostgreSQL -->
  <data-source class-name="org.postgresql.PostgresqlDataSource">
     <param name="serverName" value="host" />
     <param name="portNumber" value="5432" />
     <param name="databaseName" value="db" />
     <param name="user" value="user" />
     <param name="password" value="secret" />
   </data-source>
   ...
          

  ...
  <!-- JDBC driver definition for Oracle -->
  <driver class-name="oracle.jdbc.driver.OracleDriver"
          url="jdbc:oracle:thin:@host:post:SID">
    <param name="user" value="scott" />
    <param name="password" value="tiger" />
  </driver>
  ...
          

  ...
  <!-- JDBC data source for mySQL -->
  <driver class-name="com.mysql.jdbc.Driver"
          url="jdbc:mysql:/localhost:2206/test">
    <param name="user" value="scott" />
    <param name="password" value="tiger" />
  </driver>
  ...
          

  ...
  <!-- JDBC data source for InstantDB -->
  <driver class-name="org.enhydra.instantdb.jdbc.idbDriver"
          url="jdbc:idb:C:\\castor-1.0\\db\\test\\test.prp">
    <param name="user" value="" />
    <param name="password" value="" />
  </driver>
  ...
          

For validation, the configuration file should include the following document type definition. For DTD validation use:

  <!DOCTYPE jdo-conf PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                            "http://castor.org/jdo-conf.dtd">

             

For XML Schema validation use:

  <!DOCTYPE jdo-conf PUBLIC "-//EXOLAB/Castor JDO Configuration Schema Version 1.0//EN"
                             "http://castor.org/jdo-conf.xsd">

             

The Castor namespace URI is http://castor.org/.

The Castor JDO database configuration DTD is:

  <!ELEMENT jdo-conf ( database+, transaction-demarcation )>

  <!ATTLIST jdo-conf
            name CDATA "jdo-conf">

  <!ELEMENT database ( ( driver | data-source | jndi )?, mapping+ )>
                       
  <!ATTLIST database
            name ID      #REQUIRED
            engine CDATA "generic">

  <!ELEMENT mapping EMPTY>
  <!ATTLIST mapping
            href CDATA #REQUIRED>

  <!ELEMENT driver ( param* )>
  <!ATTLIST driver
            url        CDATA #REQUIRED
            class-name CDATA #REQUIRED>

  <!ELEMENT data-source ( param* )>
  <!ATTLIST data-source
            class-name CDATA #REQUIRED>

  <!ELEMENT jndi ANY>
  <!ATTLIST jndi
            name CDATA #REQUIRED>

  <!ELEMENT transaction-demarcation ( transaction-manager? )>
  <!ATTLIST transaction-demarcation
            mode CDATA #REQUIRED>

  <!ELEMENT transaction-manager ( param* )>
  <!ATTLIST transaction-manager
            name CDATA #REQUIRED>
            
  <!ELEMENT param EMPTY>
  <!ATTLIST param
            name  CDATA #REQUIRED
            value CDATA #REQUIRED>


             

Castor XML converts all Java fields into XML element and attribute values.

Castor JDO converts Java fields into SQL columns which are persisted through the JDBC driver. Due to implementation details, the field type expected by the JDBC driver is not always the field type defined for the mapped object.

The most common occurrences of mistyping is when using fields of type FLOAT, DOUBLE, NUMERIC, and DECIMAL. SQL type FLOAT actually maps to Java type java.lang.Double. SQL types NUMERIC and DECIMAL map to Java type java.math.BigDecimal.

When such an inconsistency occurs, Castor JDO will throw an IllegalArgumentException during object persistence with a message indicating the two conflicting types.

In order to avoid runtime exceptions, we recommend explicitly specifying types in the mapping file using the SQL typing convention. See SQL Type Conversion.

Castor DAX converts all Java fields into LDAP attribute values. LDAP attribute values are always textual and are represented as the string value of the field, e.g. "5" or "true".

LDAP attributes may also contain binary values. When storing byte arrays or serialized Java objects, DAX will store them as byte arrays.

  <!ELEMENT mapping ( description?, include*, class*, key-generator* )>

The <mapping> element is the root element of a mapping file. It contains:

A mapping file look like this:

  <?xml version="1.0"?>
  <!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN"
                           "http://castor.org/mapping.dtd">

  <mapping>
     <description>Description of the mapping</description>
     <include href="other_mapping_file.xml"/>

     <class name="A">
         ...
     </class>

     <class name="B">
        ...
     </class>
  </mapping>

  <!ELEMENT class ( description?, cache-type?, map-to?, field+ )>
  <!ATTLIST class
            name            ID       #REQUIRED
            extends         IDREF    #IMPLIED
            depends         IDREF    #IMPLIED
            auto-complete   ( true |false ) "false"
            identity        CDATA    #IMPLIED
            access          ( read-only | shared | exclusive | db-locked )  "shared"
            key-generator   IDREF    #IMPLIED >

The <class> element contains all the information used to map a Java object to a relational database. The content of <class> is mainly used to describe the fields that will be mapped.

Description of the attributes:

Description of the elements:

  <!ELEMENT map-to EMPTY>
  <!ATTLIST map-to
            table      NMTOKEN  #IMPLIED
            xml        NMTOKEN  #IMPLIED
            ns-uri     NMTOKEN  #IMPLIED
            ns-prefix  NMTOKEN  #IMPLIED
            ldap-dn    NMTOKEN  #IMPLIED
            ldap-oc    NMTOKEN  #IMPLIED>

<map-to> is used to specify the name of the item that should be associated with the given Java object. The <map-to> element is only used for the root Java object.

Description of the attributes:

  <!ELEMENT field ( description?, sql?, xml?, ldap? )>
  <!ATTLIST field
            name           NMTOKEN  #REQUIRED
            type           NMTOKEN  #IMPLIED
            required       ( true | false )  "false"
            direct         ( true | false )  "false"
            lazy           ( true | false )  "false"
            transient      ( true | false )  "false"
            identity       ( true | false )  "false"
            get-method     NMTOKEN  #IMPLIED
            set-method     NMTOKEN  #IMPLIED
            create-method  NMTOKEN  #IMPLIED
            collection     ( array | enumerate | collection | set | 
                             arraylist | vector | map | hashtable | sortedset | iterator )  #IMPLIED
            comparator     NMTOKEN  #IMPLIED>

The <field> element is used to describe a property of a Java object. It provides:

From this information, Castor is able to access a given property in the Java object.

In order to determine the signature that Castor expects, there are two easy rules to apply.

1. Determine <type>.

It is necessary to use a collection when the content model of the element expects more than one element of the specified type. This is how the 'to-many' portion of a relationship is described.

	Note
	It is not possible to use a collection of type 'iterator' or 'enumerate' with lazy loading enabled.

2. Determine the signature of the method

Description of the attributes:

  <!ELEMENT sql EMPTY>
  <!ATTLIST sql
            name        NMTOKENS  #IMPLIED
            type        NMTOKENS  #IMPLIED
            many-key    NMTOKENS  #IMPLIED
            many-table  NMTOKEN   #IMPLIED
            transient   ( true | false )    "false"
            read-only   ( true | false )    "false"
            dirty       ( check | ignore )  "check">
            cascading	( create | delete | update | all | none ) "none"

The <sql> element is used to denote information about the database column to which a Java object is mapped. It should be declared for all <field> elements. Each <field> element contains one <sql> element. The <sql> element correlates directly to the <map-to> element for the containing <class> element. The <sql> elements contains the following attributes:

There are two more attributes used only with 'to-many' relations.

No, Castor JDO doesn't comply with the SUN's JDO specification.

Although Castor JDO carries very similar goals as SUN's JDO, it has been developed independently from the JSR.

Although it is not impossible to shape (perhaps "hammer" is a more descriptive verb) Castor JDO into the SUN's JDO specification, there are several major technical differences which make it unfavorable to do so. Castor is RDBMS centric. Each persistence object loaded by Castor is locked. Locks in Castor are observable, meaning that locks may not be granted because of timeout or deadlock. On the other hand, the SUN's JDO hides details about locks.

Internally, Castor JDO maintains a single copy of lock (and cache) for each active persistence object for all transaction. SUN's JDO specification implicitly requires a copy of cache per object per transaction. SUN's JDO also implicitly requires a bytecode modifier which Castor doesn't require.

Castor also provides other features, such as key generators, long transaction support and OQL query which cannot be found in SUN's JSR.

The relation between JDO and EJB Container-Managed Persistence is more complicated than simply saying, "one is better than the other".

An Entity Bean may manage persistence itself - the EJB specification calls this Bean Managed Persistence (BMP). Alternatively, the Entity Bean may rely on an EJB container to manage all peersistence automatically - the EJB specification calls this Container Managed Persistence (CMP). When implementing BMP, an Entity Bean may use Castor JDO as its persistence mechanism, or it may use others methods, such as dealing with JDBC directly. During CMP, an EJB Container vendor may implement their CMP on top of Castor JDO. In such an implementation, Castor JDO will be used to persist the Entity Bean.

If a developer would like to take advantage of an EJB's life-cycle management, security, the "write once deploy anywhere" promise and other distributed business application facilities, then EJB will be the right choice. Otherwise, the fact that Castor is simple, is Open Source (you can always include Castor in your application or product), has much less overhead, provides more design freedom, and is integrated with Castor XML may be enough of a reason to choose Castor JDO.

No. The decision of putting XML and JDO together is NOT intended to make XML marshalling transactional. Instead, the integration is done to help developers of a typical client-server situation whereby an application server receives incoming XML messages, process the messages and replies to the client.

With Castor, incoming XML messages can be unmarshaled into data objects. Required information can be obtained from a database using JDO in form of data objects. With this approach, all data manipulation can be done in an object-oriented way. Changes to JDO data objects can be committed transactionally, and result data objects can be marshaled into XML and returned to the client.

No, Castor does not provide an OQL query facility on a XML file. If querying is important for you, you should consider using a DBMS to store your data instead of using XML files, especially if querying performance is a concern.

Another alternative is parse an XML Document directly and use XPath to retrieve Nodes and/or NodeSets from an XML Document. Other open source tools which provide this functionality are:

Download the full SVN snapshot and look into the src/tests/jdo directory.

It cannot be used with Castor, because it doesn't allow more than one open ResultSet at the same time. Either use JDBC driver of type > 1, or use some other JDBC-ODBC bridge without such a restriction (for example, from Easysoft).

You should initialize the Collection yourself:

private Collection _children = new ArrayList();

public Collection getChildren() {
    return _children;
}
            

In general, no. If you need some behavior that is not directly supported by Castor, you can implement interface org.exolab.castor.jdo.Persistent. In order to use dirty checking for long transaction you should implement interface org.exolab.castor.jdo.TimeStampable. If you need an example of use of these interfaces, see Persistent.java and TestPersistent.java among Castor JDO tests.

First of all, let's agree upon terminology. We distinguish dependent and independent objects:

Thus, dependent objects are created/removed automatically, when their parent object is created/removed, while all operations on independent objects should be performed explicitly.

However, with Castor 0.8.x you cannot describe explicitly the kind of object. Instead, the following rule applies: if you have one-to-many relation, and each side of the relation refers to another (Collection attribute on "one" side, simple attribute on "many" side), then "many" side is a dependent object. All other objects are independent. In particular, related objects via one-to-one relation are not created/removed automatically.

With Castor 0.9 dependent objects should be described via "depends" attribute of "class" element in mapping configuration file.

If you wish some independent object was created and/or removed automatically on operations on other independent object, you may use interface Persistent to code the desired behavior.

No, Castor JDO doesn't have any built-in JDBC resource pooling. However the framework can transparently use any resource pooling facilities provided through DataSource implementation or -even better- through JDNI. In fact we even recommend people to use some Connection and PreparedStatement pool with Castor as this can increase Castor's performance 3-5 fold.

For example the following set of statements:

db.begin();
db.execute(...)
db.commit()
	            

will be executed in much less time with the resource pooling because it will avoid creating a new physical JDBC connection at every execution.

With Oracle, instead of specifying the usual JDBC driver you can use a DataSource that specifically provides some Connection caching/pooling.

Thus if your jdo config file looks like :

        <database name="..." engine="oracle" >
            <driver class-name="oracle.jdbc.driver.OracleDriver"
                    URL="jdbc:oracle:thin:@localhost:1521:TEST" >
                <param name="user" value="SYSTEM"/>
                <param name="password" value="manager"/>
            </driver>
            ...
        </database>
		        

then it can be changed into (for example):

        <database name="..." engine="oracle" >
            <data-source class-name="oracle.jdbc.pool.OracleConnectionCacheImpl">
                <params URL="jdbc:oracle:thin:@localhost:1521:TEST"
                        user="scott" 
                        password="tiger"
                />
            </data-source>
            ...
        </database>
		        

When Castor is used inside a Container such as an EJB container (within BMP or Session Bean), then the Container usually provides the JDBC resource through the JNDI ENC, which implicitely includes pooling facilities.

Probably castor.jar file is in jre/lib/ext directory. In this case you should call:

      jdo.setClassLoader(getClass().getClassLoader());
	            

before jdo.getDatabase().

In this case as well as in many others you can get more information with the help of logging. Call:

  jdo.setLogWriter(Logger.getSystemLogger());
	        

and seek in the output for warnings and errors.

You should not add/remove dependent objects directly. In order to add/remove the dependent object you should just add/remove it from the collection in the master object and call db.commit()

Dependent objects cannot be created/removed explicitly. It's created automatically when it is added to a master object, and removed automatically when it de-linked/dereferenced from a master object.

Otherwise, we will be encounter into problem where a dependent object created explicitly but removed implicitly (delinked from a master object), or vice versa. It can also lead to other problems that are harder to detect.

It is recommended to replace literals with parameters and to set them via OQLQuery.bind(), for example:

OQLQuery query = db.getOQLQuery(
        "SELECT p FROM Person p "
      + "WHERE name LIKE $1 AND dob>$2 AND married=$3");
query.bind("John %");
query.bind((new SimpleDateFormat("yyyy-MM-dd"))
       .parse("1960-01-01"));
query.bind(false);
         

Your JDBC driver is not JDBC 2.0 compliant, upgrade it or find another one.

Typcially a relationship between two objects is either one-way (aka uni-directional) or two-way (aka bi-directional). Officially, Castor currently only supports bi-directional relationships. For example, if an Order object contains a reference to a LineItem object, the LineItem object must contain a reference to the Order object. However, this requirement is not enforced in all situations.

This is a very complex problem to solve. So until Castor is expanded the support uni-directional relationships, the best policy is to implement the bi-directionalality for all relationships. This will ensure proper functionality.

This is a very common occurrence in an object model and is known as a self-referenential relationship. Unfortunately, Castor does not currently support self-referential relationships. An example of such a relationship occurs when a Folder object contains a reference to another Folder object. Castor does not currently support this. However, there are ways around this limitation.

One way is to manage this type of relationship manually. For example, let's say that a parent object FolderA needs to hold references to child objects FolderB, FolderC and FolderD. The Folder object contains not only a property to hold its own id, but also a property to hold its parent id (we'll call this parentId). The parentId property is used to determine if there is a relationship to another Folder object. If parentId is null, there is no relationship. If parentId is populated, there is a relationship and the object tree can be walked by comparing the object id to the parentId. When the two properties are equal, you're at the top of the tree.

Another say to solve this problem is to make use of an intermediary object. For example, a Folder object contains a Reference object in lieu of the actual Folder object. The Reference object is somewhat of a proxy object whereby it only contains enough information to identify the object to which the Reference object refers. Then the Folder object can be easily instantiated via the information contained in the Reference object.

The dirty checking engine will throw an ObjectModifiedException when the values in the cache and in the database are different. This can happen when someone else changed the database content, but also when type mapping is not reversible.

For example, if a java timestamp (java.util.Date) is stored as a DATE, the time part is lost and the dirty checking will fail. Oracle cannot tell the difference between an empty String and a null value: if an attribute value is an empty String, dirty checking will also fail. Some precision loss sometimes occur with floating point numbers.

To avoid this, always use reversible mapping conversions. If this is not possible, mark the fields with dirty="ignore" in the mapping file.

When using Weblogic Portal 4.0 with Oracle I am receiving the following error:

java.sql.SQLException: ORA-01461: can bind a LONG value only for insert into a LONG column
	            

According to Weblogic Release Notes, this error can remedied by setting a Weblogic environment variable.

Most probably the object that is being updated has more than 100 related objects of one class and the cache size for this class is not enough. You should either increase the size of the cache or change the cache type to time-limited (the default cache type is count-limited, the default size is 100), for example:

<class ...>
  <cache-type type="count-limited" capacity="1000"/>
  ...
</class>
		        

As of release 0.9.5.3, you cannot. When using a cache of type 'none' with your 'Timestampable' objects, a MappingException is thrown when performing long transactions. Currently, Castor requires a (performance) cache of type other than 'none' to be used with classes that implement the TimeStampable interface. In other words, if you want to use long transactions, please make sure that you use one of these cache types: 'unlimited', 'count-limited' or 'time-limited'.

The next entry has some more information about a potential cause of confusion in the context of long transactions and a cache type other than 'unlimited'.

With long transactions, sometimes update() throws a PersistenceException. As of release 0.9.5.3, Castor requires a (performance) cache (of type other than 'none') to be used with classes that implement the TimeStampable interface.

Please note that if you are using a cache type other than 'unlimited', it is possible that objects expire from the cache. This case will be highlighted to you by a PersistenceException being thrown.

In this cases, please consider switching to cache type 'unlimited' (if possible) or increase the size of the cache according to your needs when using 'count-limited' (which has a default capacity of 100).

Yes. It is available from the Castor website: Advanced JDO —> OQL

We are currently working on Phase 3.

Not yet

Yes or no. Castor OQL supports implicit joins. And, in most case, you simply don't need explicit join.

Consider the following example,

SELECT o FROM Order o, LineItem i WHERE o.id = i.id AND i.price > 100
	            

It is simply equivalent to the following OQL

SELECT o FROM Order o WHERE o.lineItem.price > 100
	            

Yes. Just put "CALL SQL" keywords in front of your SQL statement. For example,

OQLQuery oql = castorDb.getOQLQuery(
    "CALL SQL SELECT id, name, date "
   +"FROM user WHERE upper(name) like $1 AS myapp.Product");
	            

But remember that the order of the fields listed must match what is defined in the mapping file.

No, Castor OQL doesn't support struct. For example, the following query CANNOT be done:

select c.name, c.age from Client c
	            

A query using the 'LIKE' expression includes the use of the SQL wildcard '%'. The wildcard must be included in the bind() statement:

        OQLQuery oql = castorDb.getOQLQuery(
                "SELECT p FROM Product p WHERE p.name LIKE $1" );
        oql.bind( "%widget%" );
	            

Yes. However, the full expression is a bit different using the LIST keyword. The following example provides a demonstration:

SELECT p FROM Product p WHERE p.id IN LIST ( 123, 456, 789 )
	            

If identifiers other than numbers are used, those identifiers must be quoted:

SELECT p FROM Product p WHERE p.name IN LIST ( "abc", "jkl", "xyz" )
	            

To include NULL values in the 'IN' list, use the 'nil' keyword:

SELECT p FROM Product p WHERE p.name IN LIST( "ABC", nil )
	            

It is even possible to include bind values in the 'IN' lists using the following syntax:

SELECT p FROM Product p WHERE p.id IN LIST( $(int)1, $2, $3 )
	            

Unfortunately, the answer is no. We're aware that many users need this feature so it is a very high priority in our todo list.

If foreign key is the primary key, as a workaround you may consider using the 'extends' relationship.

Unfortunately, the answer is no.

In version 0.8.11, we tried to enable polymorphic collection by introducing the notation of Object Reloading. Object Reloading delegates the determination of the class to a data object. However, it is proved that reloading can only be done before any instance of the target object is returned to user, and we have no way to determine that. As a result, we removed the support in version 0.9.x.

In the near future, we are going to use a new mechanism to provide extends. The new mechanism loads a table with an SQL statement that outer-joins all of the extending tables with the base. The existence of an extended table row can be used to determine the class of a data object. Notice that all extended table rows of the same entity should always be stored in the same data-store.

In the further future, we also want to let users to define a discriminator column (or determinance field). Basing on the value of discriminator columns in the base table, the bridge layer fetches the additional information and returns the combined entity with the appropriate list of entity classes.

Yes, if the two tables share the same identity, you can specify one data object to "extends" the other. When the extended data object is loaded, its table (specified in <map-to/> will be joined with all the tables of its super classes'.

Another solution (in my opinion more flexible) is having two set of methods in the main object. One for Castor JDO and another for application.

Consider the following example:

class Employee {
   private int _employeeNumber;
   private Address _address;
   private Collection _workGroup;

   public int getEmployeeNumber() {
        return _employeeNumber;
   }
   public void setEmployeeNumber( int id ) {
        _employeeNumber = id;
   }

   // methods for Castor JDO
   public Address getAddress() {
       return _address;
   }
   public void setAddress( Address address ) {
        _address = address;
   }
   public Collection getWorkGroup() {
        return _workGroup;
   }
   public Collection setWorkGroup( Collection workGroup ) {
        _workGroup = workGroup;
   }

   // methods for application
   public String getAddressCity() {
       return _address.getCity();
   }
   public String getAddressZip() {
       return _address.getZip();
   }
   // ...
}
	            

Yes, as long as the deleted object is the same instance as the one being recreated.

Dependent object is actually a concept from the object-oriented database world. A dependent object's lifetime depends on its master object. So, create/delete/update of the master object will trigger the proper actions, newly linked dependent object will be automatically created and de-referenced dependent object will be removed.

The concept was also used in the earlier CMP 2.0 draft, although it is later removed.

No

Let's use object loading as an example.

When an application invoke db.load, the underneath TransactionContext is invoked. If the object with the requested identity exists in the TransactionContext, previously loaded object in the TransactionContext is returned. Otherwise, TransactionContext creates a new instance of the interested type and invokes LockEngine to "fill" the object.

LockEngine acquires a lock of the object, and it makes sure ClassMolder has a thread-safe environment when it invokes ClassMolder. In ClassMolder, if the interested set of fields representing the object is not existed in the cache yet, SQLEngine will be invoked and the set of fields from the underneath data store will be returned. ClassMolder binds the loaded or cached fields into the new instance. ClassMolder requests the TransactionContext to load the related and the dependent objects. Eventually, the object is returned after all of the relationships are resolved.

The process of commit has several states. The first state is preStore. In preStore state, objects existing in the TransactionContext are checked for modification one by one, including dependent and related objects. De-referenced dependent objects are marked as delete-able, and reachable dependent objects are added into TransactionContext. An object is marked "dirty" if it is modified. Also, if any modification should cause any related or dependent to be dirty, the related or dependent object is marked as dirty as well.

After the preStore state, all dirty object is properly stored. And, all marked delete object will be removed. Then, the connection is committed. If succeed, all cache with be updated. Finally, all lock is released.

Yes, via javax.transaction.Synchronization interface.

For Castor to work with global transactions, Castor must be configured to use global transaction demarcation in its main configuration file:

<jdo-conf>
   ...
   <transaction-demarcation mode="global" >
      <transaction-manager name="jndi" />
   </transaction-demarcation>
</jdo-conf>
            

When retrieving a Database instance via

...
JDOManager.loadConfiguration("jdo-conf.xml");
JDOManager jdo = JDOManager.createInstance("mydb");
...
Database db = jdo.getDatabase();
            

the Database implementation will authomatically be registered with the transaction manager, as it implements javax.jta.Synchronization interface. Subsequently, the transaction manager communicates with Castor via the beforeCompletion() and afterCompletion() calls.

No

Yes, starting from PostgreSQL 7.1, where outer joins support has been added.

Yes, starting from MySQL version 3.23, where transaction support has been added. Note: if you use Mark Matthews MySQL JDBC driver, then you need version 2.0.3 or higher.

For now only with PostgreSQL 7.1 and SAP DB you get a full set of Castor features. Other Open Source databases don't support select with write lock, so db-locked locking mode doesn't work properly (it works in the same way as exclusive locking mode).

All other Castor features are supported with MySQL, Interbase, InstantDB and Hypersonic SQL.

Please see this message from the mailing list. It includes an adapter class that will provide this functionality. (Thanks John!)

Yes, you can. By default, Castor uses JDBC proxy classes (wrapping java.sql.Connection and java.sql.PreparedStatement) that capture the core SQL statements as generated by Castor and the user-supplied parameters at execution timeof the various persistence operations, and outputs them to the standard logger used by Castor. By default, these output statements are not visible, as the log level is set to level 'info'. To see these SQL statements, please increase the log level to level 'debug' in log4j.xml.

As of release 0.9.7, a new property

org.exolab.castor.persist.useProxies

has been added to castor.properties to allow configuration of the JDBC proxy classes mentioned above. If enabled, JDBC proxy classes will be used for logging SQL statements. When turned off, no logging statements will be generated at all.

Let us convert one of the classes from the JDO examples to use lazy-loading.

In the example model, every Product belongs to one ProductGroup. This is reflected in the conventional mapping as below. Here's the mapping for Product:

<!--  Mapping for Product  -->
<class name="myapp.Product"
       identity="id">
   <description>Product definition</description>
   <map-to table="prod" xml="product" />
   <field name="id" type="integer">
       <sql name="id" type="integer" />
       <xml name="id" node="attribute"/>
   </field>
 
   <!-- more fields ... -->

    <!--  Product has reference to ProductGroup,
          many products may reference same group  -->
    <field name="group" type="myapp.ProductGroup">
      <sql name="group_id" />
      <bind-xml name="group" node="element" />
    </field>
    
</class>

Let us now make the relationship between Product and ProductGroup use lazy loading. The relevant field in Product can be re-written like so:

    <field name="group" type="myapp.ProductGroup" lazy="true">
      <sql name="group_id" />
      <bind-xml name="group" node="element" />
    </field>
           

There have been one change only. We have placed the attribute lazy="true" in the field element. Note that no change is required in the ProductDetail mapping.

Please note that Castor does not support full serialization of lazy-loaded objects at this time. Rather than serializing just the information required to re-build the underlying proxy implementation during deserialization, Castor will materialize (read: load from the persistence store) all objects before serialization. As this can lead to a lot of database accesses, please use this feature carefully. A full working solution will be provided with the next release.

Let us convert one of the classes from the JDO examples to use lazy-loading.

In the example model, one Product can contain many ProductDetails. This is reflected in the conventional mapping as below. First, the mapping for Product:

<!--  Mapping for Product  -->
<class name="myapp.Product"
       identity="id">
   <description>Product definition</description>
   <map-to table="prod" xml="product" />
   <field name="id" type="integer">
       <sql name="id" type="integer" />
       <xml name="id" node="attribute"/>
   </field>
 
   <!-- more fields ... -->

   <!-- Product has reference to ProductDetail
            many details per product  -->
   <field name="details" type="myapp.ProductDetail" required="true"
           collection="vector">
       <sql many-key="prod_id"/>
       <xml name="detail" node="element" />
   </field>
</class>
	            

Now let us examine ProductDetail. Note, the relationship is mapped bi-directionally as must be all relationships when using Castor JDO.

<!--  Mapping for Product Detail -->
<class name="myapp.ProductDetail" identity="id" depends="myapp.Product" >
   <description>Product detail</description>
    <map-to table="prod_detail" xml="detail" />
   <field name="id" type="integer">
       <sql name="id" type="integer"/>
       <xml node="attribute"/>
    </field>
    <field name="product" type="myapp.Product">
       <sql name="prod_id" />
       <xml name="product" node="element" />
    </field>
   
       <!-- more fields ... -->
   
</class>
	           
	           

Let us now make the relationship between Product and ProductDetail use lazy loading. We need only change the way that the relationship to ProductDetail is specified in the mapping of Product. The relevant field in Product can be re-written like so:

<field name="details" type="myapp.ProductDetail" required="true" lazy="true"
            collection="collection">
   <sql many-key="prod_id"/>
   <xml name="detail" node="element" />
</field>
           
           

There have been two changes.

Note that no change is required in the ProductDetail mapping.

To use lazy loading you must also change the persistent class that will hold the related objects. At the very highest level, you need to provide a set method that accepts a java.util.Collection for the field in question. This is demonstrated by changing the JDO examples below.

In the original Product class we have the following code:

import java.util.Vector;
...
private Vector _details = new Vector();
...
public Vector getDetails()
{
   return _details;
}


public void addDetail( ProductDetail detail )
{
   _details.add( detail );
   detail.setProduct( this );
}
	           

Let us now make the necessary changes to set up lazy loading. As stated above we now require a special set method for the related ProductDetails (stored originally as a java.util.Vector) that accepts a java.util.Collection as an argument. This mandates that we must also use a java.util.Collection to hold our ProductDetails. If this is not added, you will receive the errors above.

import java.util.Collection;
...
private Collection _details;
...
public Collection getDetails()
{
   return _details;
}


public void setDetails( Collection details )
{
   _details = details;
}

	           

Due to a product limitation, AUTO_INCREMENT sequences in HSQL begin with 0 rather 1, as is the case with most other RDBMS. As a result of this, long transactions will not work for the object with the identity 0, and a ObjectModifiedException will be thrown.

To avoid this issue, we recommend inserting a temp object into the database in question, and removing thereafter so that no object with identity 0 is stored.

The following fragment shows the Java class declaration for the Product class:

package myapp;

public class Product {

    private int       _id;

    private String    _name;

    private float     _price;

    private ProductGroup _group;


    public int getId() { ... }

    public void setId( int anId ) { ... }

    public String getName() { ... }

    public void setName( String aName ) { ... }

    public float getPrice() { ... }

    public void setPrice( float aPrice ) { ... }

    public ProductGroup getProductGroup() { ... }

    public void setProductGroup( ProductGroup aProductGroup ) { ... }
}

The following fragment shows the Java class declaration for the ProductGroup class:

public class ProductGroup {

    private int       _id;

    private String    _name;

    public int getId() { ... }

    public void setId( int id ) { ... }

    public String getName() { ... }

    public void setName( String name ) { ... }

}

The following sections show the DDL for the relational database tables PROD, PROD_GROUP, and PROD_DETAIL:

PROD:

create table prod (
  id        int           not null,
  name      varchar(200)  not null,
  price     numeric(18,2) not null,
  group_id  int           not null
);

PROD_GROUP:

create table prod_group (
  id        int           not null,
  name      varchar(200)  not null
);

PROD_DETAIL:

create table prod_detail (
  id        int           not null,
  prod_id   int           not null,
  name      varchar(200)  not null
);

The following code fragment shows the object mapping for the ProductGroup class:

<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN"
                         "http://castor.org/mapping.dtd">
<mapping>

  <class name="myapp.ProductGroup" identity="id">

    <description>Product group</description>

    <map-to table="prod_group" xml="group" />

    <field name="id" type="integer" >
      <sql name="id" type="integer"/>
    </field>

    <field name="name" type="string">
      <sql name="name" type="char" />
    </field>

  </class>

</mapping>

As a result of that declaration, Castor JDO will create the following SQL statements for creating, deleting, loading and updating instances of ProductGroup:

create: INSERT INTO prod_group (id, name) VALUES (?,?)
delete: DELETE FROM prod_group WHERE id=?
load:   SELECT prod_group.id, prod_group.name FROM prod_group WHERE prod_group.id=?;
update: UPDATE prod_group SET name=? WHERE id=?
       

  <class name="myapp.ProductGroup" identity="id">

    ...
    <field name="name" type="string">
      <sql name="name" type="char" read-only="true" />
    </field>

  </class>

create: INSERT INTO prod_group (id) VALUES (?)
delete: DELETE FROM prod_group WHERE id=?
load:   SELECT prod_group.id, prod_group.name FROM prod_group WHERE prod_group.id=?;
update: /* no statement will be generated */
          

  <class name="myapp.ProductGroup" identity="id">

    ...
    <field name="name" type="string" >
      <sql name="name" type="char" transient="true" />
    </field>

  </class>

As of release 0.9.9, Castor supports polymorphic queries on extend hierarchies. (That is, hierarchies where some entities "extend" other entities.) To highlight this new feature, let's add two new classes to what we have currently.

package myapp;

public class Computer extends Product {

    private int       _id;

    private String    _make;

    public int getId() { ... }

    public void setId( int anId ) { ... }

    public String getmake() { ... }

    public void setMake( String aMake ) { ... }

}

public class Car extends Product {

    private int       _id;

    private Date    _registeredIn;

    public int getId() { ... }

    public void setId( int anId ) { ... }

    public Date getRegisteredIn() { ... }

    public void setRegisteredIn( Date aRegisteredIn ) { ... }
}

The corresponding DDL statements for the relational database tables COMP and CAR would look as follows:

COMP:

create table comp (
  id        int           not null,
  make      varchar(200)  not null
);

CAR:

create table car (
  id        int           not null,
  regIn     int           not null
);

Based upon the mapping defined for the Product class as shown above, the following code fragment shows the mapping for the Computer and Car classes.

    <class name="myapp.Computer" extends="myapp.Product" identity="id">

        <map-to table="COMP" />

        <field name="id" type="integer">
            <sql name="id" type="integer" />
        </field>

        <field name="make" type="string">
            <sql name="make" type="char" />
        </field>

    </class>

    <class name="myapp.Car" extends="myapp.Product" identity="id">

        <map-to table="CAR" />

        <field name="id" type="integer">
            <sql name="id" type="integer" />
        </field>

        <field name="registeredIn" type="date">
            <sql name="regIn" type="long" />
        </field>

    </class>

Based upon this mapping, it is possible to execute the following OQL queries against this class model:

OQLQuery query = d.getOQLQuery("SELECT c FROM myapp.Computer c");
        

To return all computers:

OQLQuery query = d.getOQLQuery("SELECT c FROM myapp.Computer c WHERE c.make = $");
        

To return all computers of a particular make:

OQLQuery query = d.getOQLQuery("SELECT p FROM myapp.Product p");
        

To return all products (where Castor will return the actual object instances, i.e. a Computer instance if the object returned by the query is of type Computer or a Car instance if the object returned by the query is of type Car):

OQLQuery query = d.getOQLQuery("SELECT p FROM myapp.Product p WHERE p.group.name = $");
        

To return all products that belong to the specified product group (where Castor will return the actual object instances, i.e. a Computer instance if the object returned by the query is of type Computer or a Car instance if the object returned by the query is of type Car):

Based upon above definitions, here are a few OQL sample queries that highlight various artifacts of the OQL support of Castor JDO.

To Be Written

As of release 0.9.6, Castor supports lazy-loading of 1:1 relations. Imagine the following class mapping:

<mapping>
    <class name="com.xzy.Department">
       ...
       <field "employee" type="com.xyz.Employee" lazy="true" />
       ...
    </class>
</mapping>
            

Per definition, when an instance of Department is loaded through e.g. Database.load(), Castor will not (pre-)load the Employee instance referenced (as such reducing the size of the initial query as well as the size of the result set returned). Only when the Emplyoee instance is accessed through Department.getEmployee(), Castor will load the actual object into memory from the persistence store.

This means that if the Employee instance is not accessed at all, not only will the initial query to load the Department object have had its complexity reduced, but no performance penalty will be incurred for the additional access to the persistence store either.

The elements in the collection are only loaded when the application asks for the object from the collection, using, for example, iterator.next(). The iterator in Castor's lazy collection is optimized to return a loaded object first.

In the mapping file, lazy loading is specified in the element of the collection's <field>, for example,

<mapping>
    <class name="com.xzy.Department">
       ...
        <field name="employee" type="com.xyz.Employee" lazy="true"
               collection="collection"/>
    </class>
</mapping>

declares that the collection of type Employee in a Department is lazy loaded.

If lazy loading is specified for a field of a class, Castor will set the field with a special collection which contains only the identities of the objects. Because of that, it requires the data object to have the method setDepartment( Collection department) in the data object class which was not required in previous versions.

	Note
	Please note that currently only the java.util.Collection type is supported.