# Castor JDO - Configuration

Castor JDO allows for two simple ways of specifying its required configuration, e.g. by the means of supplying Castor JDO with an XML-based configuration file, and by specifying its configuration programmatically via the org.exoalb.castor.util.jdo.JDOConfFactory class.

## The Castor configuration file

The default way to configure how Castor interacts with a specific database system is by using a configuration file. It specifies the means to obtain a connection to the database server, the mapping between Java classes and tables in that database server, and the service provider to use for talking to that server (For a more flexible, programmatic way without configuration files see section JDOConfFactory).

The application will access the database(s) by its given name (`database/name`) and will be able to persist all objects specified in the included mapping file(s).

The `engine` attribute specifies the persistence engine for this database server. Different database servers vary in the SQL syntax and capabilites they support, and this attribute names the service provider to use.

The following names are supported in Castor:

Supported engine names

engine name | RDBMS
--- | ---
db2 | DB/2
derby | Derby
generic | Generic JDBC support
hsql | Hypersonic SQL
informix | Informix
instantdb | InstantDB
interbase | Interbase
mysql | MySQL
oracle | Oracle 7 - Oracle 9i
postgresql | PostgreSQL 7.1
sapdb | SAP DB / MaxDB
sql-server | Microsoft SQL Server
sybase | Sybase 11
pointbase | Borland Pointbase
progress | Progress RDBMS

Castor doesn't work with JDBC-ODBC bridge from Sun. In particular, MS Access is not supported.

The means to acquire a database connection is specified in one of three ways: as a JDBC driver URL, as a JDBC DataSource, or as a DataSource to lookup through JNDI. When Castor is used inside a J2EE application server it is recommended to use JNDI lookup (see the `jndi` element), allowing the application server to manage connection pooling and distributed transactions.

The class mapping is included from an external mapping file, allowing multiple mappings to be included in the same database configuration, or two databases to share the same mappings. For concurrency and integrity reasons, two database configurations should never attempt to use overlapping mappings. It is recommended to use one database configuration per database server.

The mapping file is specified using a URL, typically a `file:` URL. If the database configuration file and mapping file reside in the same directory, use a relative URL. Relative URLs also work if the database configuration and mapping files are obtained from the application JAR and reside in the same classpath.

The `driver` element specifies the JDBC driver for obtaining new connections to the database server. The driver is obtained from the JDBC `DriverManager` and must be located in the class path. The JDBC URL locates the driver and provides the access properties. Additional properties may be specified using `param` elements (e.g. buffer size, network protocol, etc).

Use the `class-name` attribute to specify the driver class for automatic registration with the JDBC `DriverManager`. If missing, the driver must be registered in any other means, including properties file, `Class.forName()`, etc.

For example, to configure an Oracle 8 thin driver, use:

      <jdo-conf>
         <database name="ebiz" engine="oracle">
            <driver class-name="oracle.jdbc.driver.OracleDriver"
                    url="jdbc:oracle:thin:@host:port:SID">
               <param name="user" value="scott" />
               <param name="password" value="tiger" />
            </driver>
            ...
         </database>
         ...
      </jdo-conf>

The `data-source` element specifies the JDBC DataSource for obtaining new connections to the database server. DataSources are defined in the JDBC 2.0 standard extension API which is included with Castor, and implement the interface `javax.sql.DataSource`.

The DataSource implementation class name is specified by the `class-name` attribute and configured through Bean-like accessor methods specified for the `param` element. The DTD for the `param` element is undefined and depends on the DataSource being used.

For example, to configure a PostgreSQL 7.1 DataSource, use:

      <jdo-conf>
         <database name="ebiz" engine="oracle">
            <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>
            ...
         </database>
         ...
      </jdo-conf>

The `jndi` element specifies the JDBC DataSource for obtaining new connections to the database server through a JNDI lookup. The JNDI environment naming context (ENC) is used to obtain a suitable DataSource..

When running inside a J2EE application server, this is the preferred method for obtaining database connections. It enables the J2EE application server to configure the connection, maintain a connection pool, and manage distributed transactions.

For example, to specify a J2EE DataSource, use:

      <jdo-conf>
         <database name="ebiz" engine="oracle">
            <jndi name="java:comp/env/jdbc/mydb" />
         </database>
         ...
      </jdo-conf>

### Transaction demarcation

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.

#### Local Mode

When using Castor JDO stand-alone and you want Castor to control transaction demarcation, please use the `<transaction-demarcation>` element as follows:

    <transaction-demarcation mode="local" />

#### 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:

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.

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>

### Sample Configuration File

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>

### Prepared statement pooling

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.

### Sample configurations for various databases

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.

#### Sybase JConnect (JDBC data source)

      ...
      <!-- 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>
      ...

#### PostgreSQL (JDBC 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>
       ...

#### Oracle (JDBC Driver)

      ...
      <!-- 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>
      ...

#### mySQL (JDBC 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>
      ...

#### InstantDB

      ...
      <!-- 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>
      ...

## JDOConfFactory - A programmatic way of configuring Castor JDO

Many applications need to connect to a database using varying user accounts or database instances. To accomplish this, the utility class org.exolab.castor.jdo.util.JDOConfFactory">JDOConfFactory and a JDOManager.loadConfiguration(org.exolab.castor.jdo.conf.JdoConf) method has been added to Castor.

The following code snippet shows an example how to create a JDO configuration without the use of a default XML-based database configuration file:

      private static final String DRIVER = "oracle.jdbc.driver.OracleDriver";
      private static final String CONNECT = "jdbc:oracle:thin:localhost:1521:SID";
      private static final String USERNAME = "scott";
      private static final String PASSWORD = "tiger";
      private static final String MAPPING = "mapping.xml";
      private static final String DATABASE = "mydb";
      private static final String ENGINE = "oracle";

      // create driver configuration
      org.castor.jdo.conf.Driver driverConf =
          JDOConfFactory.createDriver(DRIVER, CONNECT, USERNAME, PASSWORD);

      // create mapping configuration
      org.castor.jdo.conf.Mapping mappingConf =
          JDOConfFactory.createMapping(getClass().getResource(MAPPING).toString());

      // create database configuration
      org.castor.jdo.conf.Database dbConf =
          JDOConfFactory.createDatabase(DATABASE, ENGINE, driverConf, mappingConf);

      // create and load jdo configuration
      JDOManager.loadConfiguration(JDOConfFactory.createJdoConf(dbConf));

      // Construct a new JDOManager for the database
      jdoManager = JDOManager.createInstance(DATABASE);

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

As an alternative to using a org.exolab.castor.jdo.conf.Driver, you can also configure Castor to use a JDBC 2.0 DataSource:

      private static final String DS = "oracle.jdbc.pool.OracleConnectionCacheImpl";
      private static final String CONNECT = "jdbc:oracle:thin:localhost:1521:SID";
      private static final String USERNAME = "scott";
      private static final String PASSWORD = "tiger";
      private static final String MAPPING = "mapping.xml";
      private static final String DATABASE = "mydb";
      private static final String ENGINE = "oracle";

      // setup properties for datasource configuration
      Properties props = new Properties();
      props.put("URL", CONNECT);
      props.put("user", USERNAME);
      props.put("password", PASSWORD);

      // create datasource configuration
      org.castor.jdo.conf.DataSource dsConf =
          JDOConfFactory.createDataSource(DS, props);

      // create mapping configuration
      org.castor.jdo.conf.Mapping mappingConf =
          JDOConfFactory.createMapping(getClass().getResource(MAPPING).toString());

      // create database configuration
      org.castor.jdo.conf.Database dbConf =
          JDOConfFactory.createDatabase(DATABASE, ENGINE, dsConf, mappingConf);

      // create and load jdo configuration
      JDOManager.loadConfiguration(JDOConfFactory.createJdoConf(dbConf));

      // Construct a new JDOManager for the database
      jdoManager = JDOManager.createInstance(DATABASE);

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

## References

### The JDO Configuration DTD

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>