Castor Taglibs and Tomcat 4.1.8 (Standalone)

To properly install Castor JDO taglibs with Tomcat, it is necessary to first install Castor in a satisfactory way. The following steps will show you how to:

  • Download dependencies - get all the JARS you need.
  • Prepare Tomcat 4.1.8 - set up a context.
  • Set up Tyrex 1.0 - write a basic domain.xml.
  • Set up a Tyrex XADatasource with a JDBC 1.0 compliant JDBC driver (Postrges 7.2 in this case)
  • Set up Tyrex 1.0 with Tomcat 4.1.8 - add required entries to server.xml.
  • Set up Castor 0.9.4.2 with Tomcat 4.1.8 and Tyrex 1.0.
  • Configure Castor to use the XADataSource created above
  • Install the taglib

Download Dependencies.

If you haven't built the Castor Taglib from source, you can download the JAR here .

In addition, you will need at least the following (place in TOMCAT_HOME/common/lib).

  • Tyrex 1.0
  • Java OTS and JTS API
  • Castor 0.9.4.2
  • JDBC 2.0 Standard Extensions
  • Java Transaction API (JTA 1.0.1)
  • Log4j
  • Xerces 1.4
  • A JDBC driver for your database.

The Castor Taglib needs to go in your-app-name/WEB-INF/lib, in addition to the Castor 0.9.4.2 jar.

For more information about the project dependencies go to the dependencies page.

Prepare Tomcat 4.1.8

You will need to create a context in the server.xml. We will add things to this context as we proceed, but this is the initial entry point. 

<Context 	path="/my-app-name" 
			docBase="my-app-name" 
			reloadable="true"
			debug="10">
<!-- more entries in here later -->
</context>

Set up Tyrex 1.0

Tyrex is configured through a file usually called domain.xml. This file allows various types of transactional resources such as JDBC connections to be managed by Tyrex. However, to simply obtain a UserTransaction or TransactionManager from Tyrex, a minimalist domain.xml can be used. 

<domain>
	<name>tyrexDomain</name>
</domain>

To get Tyrex to manage your JDBC datasource, read the next section.

Set up a Tyrex managed XADatasource

This is an optional step but desirable if your JDBC driver lacks the full JDBC 2.0 Standard Extensions. Otherwise, you can set up your driver as you would normally with Tomcat. Simply replace your domain.xml with the config below. 

<domain>
	<name>tyrexDomain</name>
	<resources>
		<dataSource>
			<name>postgresqlDataSource</name>
			<jar>C:/jdbc/postgresql.jar</jar>
			<class>tyrex.resource.jdbc.xa.EnabledDataSource</class>
			<config>
				<driverClassName>org.postgresql.Driver</driverClassName>
				<driverName>jdbc:postgresql://server.url.com:5432/castor</driverName>
				<user>castor</user>
				<password>castor</password>
			</config>
			<limits>
				<maximum>50</maximum>
				<minimum>5</minimum>
				<initial>5</initial>
				<maxRetain>300</maxRetain>
				<timeout>10</timeout>
				<trace>true</trace>
			</limits>
		</dataSource>
	</resources>
</domain>

Note the path to the jar must be hardcoded. It is safest to use an absolute path. You could use this technique on any JDBC 1.0 driver.

Set up Tyrex 1.0 with Tomcat 4.1.8

There are several things to bear in mind. First, all Tyrex and required jars must be on the Tomcat classpath (usually stick them in /tomcat/common/lib). Next, you need to make some changes to the server.xml. Finally, you need to put your domain.xml somewhere on your application classpath - I have had good results in putting it in /WEB-INF/classes. The following must be added to your server.xml, in the context you created above. 

<Context 	path="/my-app-name" 
			docBase="my-app-name" 
			reloadable="true"
			debug="10">
	<!-- 
	Tyrex Environment entries 
	- name of transaction domain (must match domain.xml)
	- location of domain config (assumes we are in WEB-INF/classes)
	-->
	<Environment name="tyrexDomainConfig" type="java.lang.String" value="domain.xml"/>
	<Environment name="tyrexDomainName" type="java.lang.String" value="tyrexDomain"/>
</context>

It is nice to use Tyrex as a TransactionManager for Castor. To do this, you will need to use an ObjectFactory to expose the Tyrex TransactionManager through JNDI in Tomcat. This is part of the Castor Taglib distribution. It is configured by adding the following to your context in the server.xml 

<!-- 
TransactionManager object : binds a Transaction Manager to java:comp/env/<name>
In the case below, java:comp/env/TransactionManager
-->
<Resource 	name="TransactionManager" 
			auth="Container"
			type="javax.transaction.TransactionManager" />

<ResourceParams name="TransactionManager">
	<parameter>
		<name>factory</name>
		<value>com.fc.taglibs.castor.integration.tomcat.TyrexTransactionManagerFactory</value>
	</parameter>
</ResourceParams>

If you used Tyrex to manage your datasource, you will need to further configure your context in the server.xml. 

<!--
Tyrex managed Datasource
-->
<Resource name="jdbc/postgresqlDb" auth="Container" type="tyrex.resource.Resource"/>

<ResourceParams name="jdbc/postgresqlDb">
	<parameter>
		<name>name</name>
		<value>postgresqlDataSource</value>
	</parameter>
</ResourceParams>

Set up Castor 0.9.4.2

Having set up Tyrex it is now possible to nicely install Castor 0.9.4.2 on Tomcat. To do this, the ObjectFactory class that exposes Castor JDO through JNDI as part of the Castor Taglib needs to be set up in the server.xml. This class configures the JDO object so pay careful attention to the parameters. You need to add something like the following to your context in the server.xml. Note the last parameter tells Castor to use the TransactionManager we set up in the step above. 

<!-- 
Castor JDO object (binds to java:comp/env/jdo/CastorJdo)
-->
<Resource 	name="jdo/CastorJdo" 
			auth="Container"
			type="org.exolab.castor.jdo.DataObjects" />

<ResourceParams name="jdo/CastorJdo">
	<parameter>
		<name>factory</name>
		<value>com.fc.taglibs.castor.integration.tomcat.CastorJdoObjectFactory</value>
	</parameter>
	<parameter>
		<name>Description</name>
		<value>Castor JDO instance</value>
	</parameter>
	<parameter>
		<name>Configuration</name>
		<value>database.xml</value>
	</parameter>
	<parameter>
		<name>LockTimeout</name>
		<value>10000</value>
	</parameter>
	<parameter>
		<name>LoggingEnabled</name>
		<value>true</value>
	</parameter>
	<parameter>
		<name>CommonClassPath</name>
		<value>false</value>
	</parameter>
	<parameter>
		<name>AutoStore</name>
		<value>false</value>
	</parameter>
	<parameter>
		<name>DatabasePooling</name>
		<value>true</value>
	</parameter>
	<parameter>
		<name>TransactionManager</name>
		<value>java:comp/env/TransactionManager</value>
	</parameter>
</ResourceParams>

The parameters explained:

  • Factory: The ObjectFactory that creates the JDO DataObjects instance and puts it in JNDI.
  • Description: Words that describe it.
  • Configuration: The name of the Castor JDO configuration (NB: assumes it is in WEB-INF/classes).
  • LockTimeout: The time in millis for Castor to wait for Lock Timeouts
  • LoggingEnabled: Whether to display verbose logging to System.out (recommended for beginners!)
  • CommonClassPath: Whether to use the application server's classpath.
  • Autostore: Set to true if you want Castor to automatically update related classes.
  • Database Pooling: Set to true if you want Castor to use the application server's database pools.
  • TransactionManager: Make Castor use the TyrexTransactionManager above - ensure that the JNDI name specified what you set above!

Next, the resource needs to be added to the web.xml. 

<resource-ref>
	<description>
		Object factory for JDO instances.
	</description>
	<res-ref-name>
		jdo/CastorJdo
	</res-ref-name>
	<res-type>
		org.exolab.castor.jdo.DataObjects
	</res-type>
	<res-auth>
		Container
	</res-auth>
</resource-ref>

Configure Castor 0.9.4.2 to use your Datasource

You need to ensure that the database.xml file specified above for Castor contains the correct configuration for your datasource. This means, the JNDI name specified in database.xml matches the JNDI name chosen in server.xml. 

<!DOCTYPE databases PUBLIC 	"-//EXOLAB/Castor JDO Configuration DTD Version 1.0//EN"
        					"http://cookietime.fortune-cookie.com/jdo-conf.dtd">

<database name="test" engine="postgresql" >
	<jndi name="java:comp/env/jdbc/postgresqlDb"/>
	<mapping href="mapping.xml" />
</database>

Install Taglib

This is standard procedure - move the castor-taglib.jar to WEB-INF/lib and the castor.tld to WEB-INF. For each JSP, add the following to the prolog... 

<%@ taglib uri='/WEB-INF/castor.tld' prefix='castor' %>