|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## Castor JDO and JBoss

Documentation Author(s):
Patrick van Kann
Bruce Snyder

Introduction
Dependencies
Configuring JBoss 3.2.1
Install The Dependencies
Create A Datasource
Configure Castor
Configure Castor JDO MBean
Test And Troubleshoot
Developing Applications With Castor JDO and JBoss 3.x
Frequently Asked Questions

## Introduction

This document describes the advantages of using Castor with JBoss, an overview of the JBoss MBean approach and directions on configuring JBoss to use Castor JDO. The advantage of using Castor JDO within JBoss is that you have access to key J2EE features such as JNDI, JDBC datasources and transaction management (JTA). Although it is possible in principle to achieve this with other commercial J2EE servers, a ready-to-use plug-in is available to integrate Castor JDO within JBoss.

Once integrated, Castor JDO can be used with session beans and BMP entity beans as an alternative to CMP entity beans and in many cases is faster and more efficient. An example of using Castor JDO with a stateless session bean has been created and is available here. This is a demonstration of the transient entity design pattern, described here.

Castor JDO is integrated with JBoss through the JMX server environment provided by JBoss. The plug-in consists of a JMX MBean or managed bean that implements the Castor DataObjects interface by wrapping a JDO object. The MBean accomplishes the following tasks at the startup of JBoss 3.x:

1. Creates a Castor JDO object
2. Obtains the JDO configuration information (see below) and configures the JDO object.
3. Registers itself in the JBoss JNDI tree using the name supplied in the configuration. As it implements DataObject, it therefore provides access to the JDO functionality.
4. Calls setTransactionManager() on the JDO object with the JNDI address of the JBoss TransactionManager to provide Container Managed Transactions.

## Dependencies

There are two jars needed to use Castor JDO with JBoss:

- | Castor 0.9.5 (download)
- | Castor JDO plugin for JBoss 3.2.1 (download)

Note: Xerces is required also, but is distributed with JBoss 3.2.1.

## Configuring JBoss 3.2.1

This section details the steps required to integrate Castor JDO with JBoss 3.x. In brief, these are:

1. Install the dependencies
2. Configuring a datasource in JBoss. Many people automatically assume that it is necessary to get a `java.sql.Datasource` from JBoss. This is an incorrect assumption... Explain further
3. Put Castor's configuration files for your application in the correct location
4. Configuring the Castor JDO Mbean
5. Test and troubleshoot

### Install The Dependencies

Installing JBoss 3.x is outside of the scope of this discussion and is adequately covered by the JBoss documentation. Once JBoss is installed it is necessary to copy the two other dependencies (Castor and the Castor plugin) to the `lib` directory of the JBoss server instance you wish to install Castor for. The following path assumes you wish to install Castor on the "default" server: `(JBOSS_HOME/server/default/lib)`.

### Create A Datasource

It is desirable to use Castor with a javax.sql.Datasource as this will allow you to use connection pooling and distributed transactions, assuming your driver supports these. Datasources are configured by placing a config file ending in -ds.xml in the `deploy` directory of the server instance you wish to use. For example, to configure a Microsoft SQL Server XADatasource for the default server using the InetSoft Opta 2000 driver you would place a file with the information below in the `JBOSS_HOME/server/default/deploy` directory:

    <datasources>
        <xa-datasource>
            <jndi-name>MSSQLXaDS</jndi-name>
            <xa-datasource-class>com.inet.tds.XDataSource</xa-datasource-class>
            <xa-datasource-property name="ServerName">10.1.8.100</xa-datasource-property>
            <xa-datasource-property name="DatabaseName">mydatabase</xa-datasource-property>
            <xa-datasource-property name="SelectMethod">cursor</xa-datasource-property>
            <user-name>secret</user-name>
            <password>squirrel</password>
        </xa-datasource>
    </datasources>

### Configure Castor

Copy your database.xml and mapping.xml to the configuration directory for your JBoss server instance: for example, `JBOSS_HOME/server/default/conf`.

Your database.xml should reference the datasource you created in the previous step. For the datasource above:

    <database name="test" engine="sql-server" >
        <jndi name="java:/MSSQLXaDS"/>
        <mapping href="mapping.xml" />
    </database>

Note that if you are not using Microsoft SQL Server, you should not use the sql-server engine - consult the Castor documents here to find out what engine you should use for your RDBMS.

### Configure Castor JDO MBean

The JBoss MBean server looks for MBean configuration files in the deploy directory of a server instance: `JBOSS_HOME/server/default/deploy`. These files will end in -service.xml. The MBean parses the xml file, creates the MBean instance and uses introspection to set properties on the MBean based on the attributes in the configuration.

To configure the JBoss MBean, place a file called `castor-jdo-service.xml` in `JBOSS_HOME/server/default/deploy` with the following contents:

    <server>
        <mbean code="org.jboss.jdo.castor.CastorJDOImpl"  name="jboss:service=CastorJDO,name=CookietimeJDO">
            <attribute name="Configuration">../conf/database.xml</attribute>
            <attribute name="JndiName">MyAppJDO</attribute>
            <attribute name="LockTimeout">10000</attribute>
            <attribute name="LoggingEnabled">true</attribute>
            <attribute name="CommonClassPath">false</attribute>
            <attribute name="AutoStore">true</attribute>
            <attribute name="DatabasePooling">true</attribute>
        </mbean>
    </server>

Note the following features of the configuration:

- | the `org.jboss.jdo.castor.CastorJDOImpl` is inside the castor-jdo-plugin.jar.
- | the use of a relative path to the `database.xml` configuration from the previous step.
- | JndiName is the name by which you will obtain your JDO object from JNDI within your EJB or DAO.
- | Autostore will cause castor to automatically "walk" the object graph on updates in long transactions and attempt to persist every reachable class.

### Test And Troubleshoot

To test your configuration, try and start the JBoss server instance you are attempting to configure. Watch the console carefully for any stacktraces or other error messages. With any luck, at some stage you should see something like:

                11:12:59,025 INFO  [MainDeployer] Starting deployment of package: file:/C:/jboss
                /server/default/deploy/castor-jdo-service.xml
                11:12:59,181 INFO  [CastorJDOImpl] Creating
                11:12:59,196 INFO  [CastorJDOImpl] Created
                11:12:59,212 INFO  [CastorJDOImpl] Starting
                11:13:00,759 INFO  [CastorJDOImpl] Started

Go to the JMX Console (http://localhost:8080/jmx-console) of your JBoss machine. You should see the following link under the jboss entry:

    name=MyAppJDO,service=CastorJDO

Click on the link to see the status of the service. It should be started.

You can also check the status of your datasource by looking for it under the jca entry in the console.

## Developing Applications With Castor JDO and JBoss 3.x

To do:

1. Transient Entity (better description of Rooms example)
2. Entity Bean with delegates (An example of this needs to be created.)

## Frequently Asked Questions

Check the JDO FAQ here for common questions regarding JDO usage.

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<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>