ExoLab     OpenEJB     OpenJMS     OpenORB     Castor     Tyrex     
 

Main
  Home
  Download
  API
  Schema
  Mailing Lists
  CVS / Bugzilla
  Support

XML
  Using XML
  Source Generator
  Schema Support
  XML Mapping
  XML FAQ

JDO
  Using JDO
  JDO Config
  Types
  JDO Mapping
  JDO FAQ
  Other Features

Advanced JDO
  OQL
  Trans. & Locks
  Design
  KeyGen
  Long Trans.
  Nested Attrs.
  Pooling Examples
  Blobs and PostgreSQL

More
  Presentations
  The Examples
  Extras and 3rd Party Tools
  Test Framework -- JDO
  Test Framework -- XML
  Configuration
  Tips & Tricks
  Full JavaDoc

About
  License
  Contributors
  Status, Todo
  Changelog
  Library
  Contact

  



The Castor configuration file
Sample Configuration File
Configuration For Various Databases
The JDO Configuration DTD

The Castor configuration file

The database configuration 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.

The application will access the database 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 1.0:

db2DB/2
genericGeneric JDBC support
hsqlHypersonic SQL
informixInformix
instantdbInstantDB
interbaseInterbase
mysqlMySQL
oracleOracle 7 - Oracle 9i
postgresqlPostgreSQL 7.1
sapdbSAP DB
sql-serverMicrosoft SQL Server
sybaseSybase 11

Note: 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 2.0 driver URL, as a JDBC 2.0 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 2.0 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 the param element (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:

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

The data-source element specifies the JDBC 2.0 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:

  <data-source class-name="org.postgresql.PostgresqlDataSource">
    <params server-name="host" port-number="5432" database-name="db"
           user="user" password="secret" />
  </data-source>
         

The jndi element specifies the JDBC 2.0 DataSource for obtaining new connections to the database server through 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:

  <jndi name="java:comp/env/jdbc/mydb" />
         

Sample Configuration File

The following configuration file uses an Oracle 8 thin JDBC driver and three mapping files:

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

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

  <database name="ebiz" engine="oracle">
    <jndi name="java:comp/env/jdbc/mydb" />
    <mapping href="ebiz.xml" />
  </database>
         

Configuration For Various Databases

Driver Configuration
Sybase jConnect
  <data-source class-name="com.sybase.jdbc2.jdbc.SybDataSource">
    <params user="user" password="secret"
            port-number="4100" server-name="host" />
  </data-source>
Oracle Thin Driver
  <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>
PostgreSQL
     <params server-name="host" port-number="5432"
             database-name="db"
             user="user" password="secret" />
   </data-source>
InstantDB
  <driver class-name="org.enhydra.instantdb.jdbc.idbDriver"
          url="jdbc:idb:C:\\castor-0.8.8\\db\\test\\test.prp">
    <param name="user" value="" />
    <param name="password" value="" />
  </driver>

NOTE:
Besides the examples listed above, a good source of configuraton examples are the JDO tests (src/tests/jdo). See the XML decriptor for each database type.

The JDO Configuration DTD

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

  <!DOCTYPE databases PUBLIC "-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
                             "http://castor.exolab.org/jdo-conf.dtd">
      
For XML Schema validation use:
  <!DOCTYPE databases PUBLIC "-//EXOLAB/Castor JDO Configuration Schema Version 1.0//EN"
                             "http://castor.exolab.org/jdo-conf.xsd">
      
The Castor namespace URI is http://castor.exolab.org/.

The Castor JDO database configuration DTD is:

  <!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 #IMPLIED>

  <!ELEMENT param EMPTY>
  <!ATTLIST param
            name  CDATA #REQUIRED
            value CDATA #REQUIRED>

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

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

 
   
  
   
 


Copyright ) 1999-2003 ExoLab Group. All rights reserved.
 
Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners.