<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>Configuration, Libraries and Building Castor</title><link rel="stylesheet" href="default.css"></head><body bgcolor="#ffffff" link="#6763a9" vlink="#6763a9" topmargin="0" bottommargin="0" leftmargin="0" marginheight="0" marginwidth="0"><a name="top"></a><table border="0" cellpadding="0" cellspacing="0" height="400"><tr><td width="10" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="115" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="7" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="70" height="6" border="0"></td><td width="400" valign="top" align="left"><img src="images/top_2.gif" width="400" height="6" border="0"></td><td width="120" valign="top" align="left"><img src="images/line_purple.gif" width="120" height="6" border="0"></td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="7" bgcolor="#ffffff" valign="top" align="left"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="400" valign="middle" align="left"><a href="http://www.exolab.org"><span class="menuTopOff">ExoLab</span></a> <a href="http://openejb.sf.net"><span class="menuTopOff">OpenEJB</span></a> <a href="http://openjms.sf.net"><span class="menuTopOff">OpenJMS</span></a> <a href="http://openorb.sf.net"><span class="menuTopOff">OpenORB</span></a> <a href="http://castor.exolab.org"><span class="menuTopOn">Castor</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img src="images/dotTrans.gif" width="1" height="2" border="0"></td><td width="120" height="20" valign="top" align="left"> </td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="3" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="right"><img src="images/line_sm.gif" width="105" height="3" border="0"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/line_sm.gif" width="7" height="3" border="0"></td><td width="70" valign="top" align="left"><img src="images/line_light.gif" width="70" height="3" border="0"></td><td width="400" valign="top" align="left"><img src="images/line_light.gif" width="400" height="3" border="0"></td><td width="120" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td></tr><tr><td bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="10" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="2" border="0"><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Main</span></td></tr><tr><td valign="top" align="left"> <a href="index.html"><span class="subMenuOff">Home</span></a></td></tr><tr><td valign="top" align="left"> <a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td valign="top" align="left"> <a href="api/overview-summary.html"><span class="subMenuOff">API</span></a></td></tr><tr><td valign="top" align="left"> <a href="schema.html"><span class="subMenuOff">Schema</span></a></td></tr><tr><td valign="top" align="left"> <a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td valign="top" align="left"> <a href="cvs.html"><span class="subMenuOff">CVS / Bugzilla</span></a></td></tr><tr><td valign="top" align="left"> <a href="support.html"><span class="subMenuOff">Support</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">XML</span></td></tr><tr><td valign="top" align="left"> <a href="xml-framework.html"><span class="subMenuOff">Using XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="sourcegen.html"><span class="subMenuOff">Source Generator</span></a></td></tr><tr><td valign="top" align="left"> <a href="xmlschema.html"><span class="subMenuOff">Schema Support</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-mapping.html"><span class="subMenuOff">XML Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-faq.html"><span class="subMenuOff">XML FAQ</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">JDO</span></td></tr><tr><td valign="top" align="left"> <a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td valign="top" align="left"> <a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td valign="top" align="left"> <a href="castor-one.html"><span class="subMenuOff">Other Features</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td valign="top" align="left"> <a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td valign="top" align="left"> <a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td valign="top" align="left"> <a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td valign="top" align="left"> <a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td valign="top" align="left"> <a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td valign="top" align="left"> <a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td valign="top" align="left"> <a href="pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="postgresql-blobs.html"><span class="subMenuOff">Blobs and PostgreSQL</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">More</span></td></tr><tr><td valign="top" align="left"> <a href="presentations.html"><span class="subMenuOff">Presentations</span></a></td></tr><tr><td valign="top" align="left"> <a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="extras.html"><span class="subMenuOff">Extras and 3rd Party Tools</span></a></td></tr><tr><td valign="top" align="left"> <a href="test-framework.html"><span class="subMenuOff">Test Framework -- JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="ctf.html"><span class="subMenuOff">Test Framework -- XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td valign="top" align="left"> <a href="tips-tricks.html"><span class="subMenuOff">Tips & Tricks</span></a></td></tr><tr><td valign="top" align="left"> <a href="javadoc/overview-summary.html"><span class="subMenuOff">Full JavaDoc</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">About</span></td></tr><tr><td valign="top" align="left"> <a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td valign="top" align="left"> <a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td valign="top" align="left"> <a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td valign="top" align="left"> <a href="changelog.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td valign="top" align="left"> <a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td valign="top" align="left"> <a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr></table><br></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" valign="top" align="left"> </td><td rowspan="4" width="400" valign="top"><table cols="2" rows="2" border="0" cellpadding="0" cellspacing="0" width="400"><tr><td valign="top" align="left"><br><img border="0" height="34" hspace="0" src="images/castor.gif" vspace="0" width="115"><br><img border="0" height="10" hspace="0" src="images/dotTrans.gif"></td><td width="120" height="5" valign="top" align="right"><a href="http://www.exolab.org"><img src="images/logo_exolab.gif" hspace="0" vspace="10" width="77" height="20" border="0"></a></td></tr></table><p></p><p></p><br><span class="bodyGrey"><a href="#The-Castor-configuration-file">The Castor configuration file</a><br></span><span class="bodyGrey"><a href="#Dependent-Libraries">Dependent Libraries</a><br></span><span class="bodyGrey"><a href="#Castor-XML">Castor XML</a><br></span><span class="bodyGrey"><a href="#Castor-JDO">Castor JDO</a><br></span><span class="bodyGrey"><a href="#Castor-DSML">Castor DSML</a><br></span><span class="bodyGrey"><a href="#Building-Castor">Building Castor</a><br></span><span class="bodyGrey"><a href="#Directory-Structure">Directory Structure</a><br></span><br><a name="The-Castor-configuration-file"><h2>The Castor configuration file</h2></a> <p><span class="bodyGrey">Castor uses a configuration file for environmental properties that are shared across all the Castor sub systems. The configuration file is specified as a Java properties file with the name <tt>castor.properties</tt>.</span></p> <p><span class="bodyGrey">The Castor JAR includes a default configuration file. A configuration file in the Java library directory (e.g. <tt>/jdk1.2/lib</tt>) can be used to override the default configuration file with system wide properties. In addition, a configuration file can be placed in the classpath and will override both the system wide properties and default configuration.</span></p> <p><span class="bodyGrey">When running the provided examples, Castor will use the configuration file located in the examples directory which specifies additional debugging information and pretty printing of all produced XML documents.</span></p> <p><span class="bodyGrey">The following properties are currently supported in the configuration file:</span></p> <span class="bodyGrey"><pre>
# Defines the default XML parser to be used by castor
# The parser must implement org.xml.sax.Parser
#
org.exolab.castor.parser=org.apache.xerces.parsers.SAXParser
# Defines the default XML serializer to be used by castor
# The serializer must implement org.apache.xml.serialize.Serializer
#
org.exolab.castor.serializer=org.apache.xml.serialize.XMLSerializer
# True if all documents should be indented on output by default
#
org.exolab.castor.indent=false
# True if all documents should be validated on input by default
#
org.exolab.castor.validation=true
# Comma separated list of SAX 2 features that should be enabled
# for the default parser
#
org.exolab.castor.features=
# True if should produce verbose messages
#
org.exolab.castor.debug=false
# List of collection handlers for Java 1.1 and Java 1.2 run-times
#
org.exolab.castor.mapping.collections=\
org.exolab.castor.mapping.loader.J1CollectionHandlers,\
org.exolab.castor.mapping.loader.J2CollectionHandlers
# List of persistence factories for the supported database servers
#
org.exolab.castor.jdo.engines=\
org.exolab.castor.jdo.drivers.OracleFactory,\
org.exolab.castor.jdo.drivers.PostgreSQLFactory,\
org.exolab.castor.jdo.drivers.SybaseFactory,\
org.exolab.castor.jdo.drivers.SQLServerFactory,\
org.exolab.castor.jdo.drivers.DB2Factory,\
org.exolab.castor.jdo.drivers.GenericFactory
# List of key generator factories
#
org.exolab.castor.jdo.keyGeneratorFactories=\
org.exolab.castor.jdo.drivers.MaxKeyGeneratorFactory,\
org.exolab.castor.jdo.drivers.HighLowKeyGeneratorFactory,\
org.exolab.castor.jdo.drivers.IdentityKeyGeneratorFactory,\
org.exolab.castor.jdo.drivers.SequenceKeyGeneratorFactory
# Collection handlers for the source code generator
#
org.exolab.castor.builder.type.j2=\
org.exolab.castor.builder.FieldInfoFactoryJ2
org.exolab.castor.builder.type.j1=\
org.exolab.castor.builder.FieldInfoFactory
org.exolab.castor.builder.type.odmg=\
org.exolab.castor.builder.FieldInfoFactoryODMG30
</pre></span> <a name="Dependent-Libraries"><h2>Dependent Libraries</h2></a> <p><span class="bodyGrey">JARs required to build Castor and dependencies for various packages are contained in the <tt>lib</tt> directory. JARs required for distribution are marked with bold text:</span></p> <table cellpadding="4" border="1"> <tr><td><span class="bodyGrey">ant.jar</span></td><td><span class="bodyGrey">The Ant build tool</span></td></tr> <tr><td><span class="bodyGrey"><b>jdbc-se2.0.jar</b></span></td><td><span class="bodyGrey">JDBC 2.0 standard extension (JDO)</span></td></tr> <tr><td><span class="bodyGrey"><b>jndi.jar</b></span></td><td><span class="bodyGrey">The JNDI API (DSML/JNDI)</span></td></tr> <tr><td><span class="bodyGrey"><b>jta1.0.1.jar</b></span></td><td><span class="bodyGrey">The JTA API (transactions)</span></td></tr> <tr><td><span class="bodyGrey">jtf-0.1.jar</span></td><td><span class="bodyGrey">The Java Testing Framework</span></td></tr> <tr><td><span class="bodyGrey"><b>ldapjdk.jar</b></span></td><td><span class="bodyGrey">Mozilla Directory SDK (DSML/MDS)</span></td></tr> <tr><td><span class="bodyGrey">ldapsp.jar</span></td><td><span class="bodyGrey">JNDI LDAP service provider from Mozilla</span></td></tr> <tr><td><span class="bodyGrey">postgresql-6.3.jar</span></td><td><span class="bodyGrey">PostgreSQL 6.3 driver with DataSource support (used in default example)</span></td></tr> <tr><td><span class="bodyGrey">servlet.jar</span></td><td><span class="bodyGrey">Used by the Servlet examples</span></td></tr> <tr><td><span class="bodyGrey"><b>xerces.jar</b></span></td><td><span class="bodyGrey">Xerces XML library</span></td></tr> <tr><td><span class="bodyGrey">xslp.jar</span></td><td><span class="bodyGrey">XSL processor, used for documentation</span></td></tr> </table> <a name="Castor-XML"><h3>Castor XML</h3></a> <p><span class="bodyGrey">Castor XML is dependent on the latest release of Xerces available from the library directory and XML Apache. Other XML parser may be used instead of Xerces, however, Xerces is required to provide the XML serializer package for XML document production.</span></p> <a name="Castor-JDO"><h3>Castor JDO</h3></a> <p><span class="bodyGrey">Castor JDO uses Castor XML for processing the XML mapping file and has the same dependency on Xerces.</span></p> <p><span class="bodyGrey">In addition applications that use Castor JDO must include <tt>jdbc-se2.0.jar</tt> or any alternative JAR that includes the <tt>javax.sql.DataSource</tt> interface.</span></p> <p><span class="bodyGrey">The JDO example uses the PostgreSQL database and depends on the provided JDBC driver which includes <tt>javax.sql.DataSource</tt> support. This driver is not required for distribution or if a different database server is used.</span></p> <a name="Castor-DSML"><h3>Castor DSML</h3></a> <p><span class="bodyGrey">Castor DSML is dependent on the latest release of Xerces available from the library directory and XML Apache. Other XML parser may be used instead of Xerces, however, Xerces is required to provide the XML serializer package for XML document production.</span></p> <p><span class="bodyGrey">Castor DSML has two implementations, one that uses JNDI and one that uses the Mozilla Directory SDK. Applications that use the JNDI package (<tt>org.exolab.castor.dsml.jndi</tt>) are required to include <tt>jndi.jar</tt> or any alternative JAR that includes the JNDI 1.2 API. Applications that use the Mozilla Directory SDK (<tt>org.exolab.castor.dsml.mozilla</tt>) are required to include <tt>ldapjdk.jar</tt> or any alternative JAR that includes version 4.0 of the Mozilla Directory SDK.</span></p> <p><span class="bodyGrey">We recommend using the Mozilla Directory SDK as the JNDI LDAP service provider and have positive experience using it with OpenLDAP. The JNDI LDAP service provider is included in the <tt>ldapsp.jar</tt>.</span></p> <a name="Building-Castor"><h2>Building Castor</h2></a> <p><span class="bodyGrey">Castor uses Ant as the build environment. To build Castor from the source run <tt>build.sh</tt> or <tt>build.bat</tt> in the Castor root directory with one (or any) of the following targets:</span></p> <table cellpadding="4" border="1"> <tr><td><span class="bodyGrey">targets</span></td><td><span class="bodyGrey">Lists the build targets</span></td></tr> <tr><td><span class="bodyGrey">clean</span></td><td><span class="bodyGrey">Cleans the build and distribution directories</span></td></tr> <tr><td><span class="bodyGrey">all</span></td><td><span class="bodyGrey">Cleans and builds all the packages and examples</span></td></tr> <tr><td><span class="bodyGrey">release</span></td><td><span class="bodyGrey">Cleans and builds all the release packages (JAR, source, doc, tarball) in the dist directory</span></td></tr> <tr><td><span class="bodyGrey">main</span></td><td><span class="bodyGrey">Builds the main packages (including debugging info)</span></td></tr> <tr><td><span class="bodyGrey">examples</span></td><td><span class="bodyGrey">Builds the example packages (including debugging info)</span></td></tr> <tr><td><span class="bodyGrey">tests</span></td><td><span class="bodyGrey">Builds the test packages (including debugging info)</span></td></tr> <tr><td><span class="bodyGrey">jar</span></td><td><span class="bodyGrey">Builds the binary JAR in the dist directory</span></td></tr> <tr><td><span class="bodyGrey">doc</span></td><td><span class="bodyGrey">Builds the documentation</span></td></tr> <tr><td><span class="bodyGrey">api</span></td><td><span class="bodyGrey">Builds the API JavaDocs</span></td></tr> <tr><td><span class="bodyGrey">javadoc</span></td><td><span class="bodyGrey">Builds the full JavaDocs</span></td></tr> <tr><td><span class="bodyGrey">source</span></td><td><span class="bodyGrey">Builds the source tarball in the dist directory</span></td></tr> <tr><td><span class="bodyGrey">tarball</span></td><td><span class="bodyGrey">Builds the binary distribution in the dist directory</span></td></tr> <tr><td><span class="bodyGrey">cvs</span></td><td><span class="bodyGrey">Update the sources from the CVS</span></td></tr> </table> <p><span class="bodyGrey">The tarball will includes the Castor JAR, all dependent library JARs, readme and license files, and all DTDs and XML schemas in the <tt>schema</tt> directory.</span></p> <a name="Directory-Structure"><h2>Directory Structure</h2></a> <table cellpadding="4" border="1"> <tr><td><span class="bodyGrey">src/main</span></td><td><span class="bodyGrey">The source base for all the Castor modules</span></td></tr> <tr><td><span class="bodyGrey">src/doc</span></td><td><span class="bodyGrey">Documentation (in XML form)</span></td></tr> <tr><td><span class="bodyGrey">src/schema</span></td><td><span class="bodyGrey">DTD and XML schema for Castor mapping files</span></td></tr> <tr><td><span class="bodyGrey">src/examples</span></td><td><span class="bodyGrey">Examples for the various packages</span></td></tr> <tr><td><span class="bodyGrey">src/tests</span></td><td><span class="bodyGrey">Test cases for the various packages</span></td></tr> <tr><td><span class="bodyGrey">src/etc</span></td><td><span class="bodyGrey">Additional files that are not part of the code base</span></td></tr> <tr><td><span class="bodyGrey">lib</span></td><td><span class="bodyGrey">JARs required to build Castor and distributable JARs</span></td></tr> <tr><td><span class="bodyGrey">build/classes</span></td><td><span class="bodyGrey">When using Ant the Java classes are build in this directory</span></td></tr> <tr><td><span class="bodyGrey">build/doc</span></td><td><span class="bodyGrey">When using Ant the HTML documentation is build in this directory</span></td></tr> <tr><td><span class="bodyGrey">build/examples</span></td><td><span class="bodyGrey">When using the examples are build in this directory</span></td></tr> <tr><td><span class="bodyGrey">build/test</span></td><td><span class="bodyGrey">When using the test cases are build in this directory</span></td></tr> <tr><td><span class="bodyGrey">dist</span></td><td><span class="bodyGrey">The distribution directory</span></td></tr> </table> </td></tr><tr height="5"><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" height="5" bgcolor="#7270c2" valign="top"><img src="images/dotTrans.gif" width="1" height="15" border="0"><br><img src="images/line_sm.gif" width="105" height="3" border="0" align="right"></td><td width="7" height="5" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="5" valign="top" align="left"> </td><td width="120" height="5" valign="top" align="left"> </td></tr><tr><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" bgcolor="#7270c2" valign="top" align="left"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="120" valign="top" align="left"> </td></tr><tr height="5"><td width="10" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripes1.gif" width="10" height="125" border="0"></td><td width="115" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripe105.gif" width="105" height="125" border="0"></td><td width="7" rowspan="2" height="100%" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="100%" valign="top" align="left"> </td><td width="120" height="100%" valign="top" align="left"> </td></tr><tr height="5"><td width="70" height="25" valign="top" align="left"> </td><td width="400" height="25" valign="bottom" align="left"><br><br><img src="images/line_light.gif" border="0" width="400" height="3"><br><p></p><span class="bodyGrey"><small><notice> Copyright ) 1999-2003 <a href="http://www.exolab.org">ExoLab Group</a>. All rights reserved. </notice><br> <br></small><small><notice> 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. </notice><br> <br></small></span><p></p> </td><td width="120" height="25" valign="top" align="left"> </td></tr></table></body></html>
