License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     
 

Main
  Home
  About
  Features
  Download
  Maven 2 support
  API
  DTD & Schemas
  Recent changes
  RSS news feed

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

Related projects
  Spring ORM support
  Spring XML factories

XML
  Using XML
  XML Mapping
  XML FAQ
  XML HOW-TOs
  Custom Handlers
  Best practice

XML Code Generator
  Code Generator
  Properties
  Custom bindings
  Ant task
  Schema Support
  Example

JDO
  Introduction
  Using JDO
  JDO Config
  Types
  JDO Mapping
  JDO FAQ
  JDO Examples
  JDO HOW-TOs
  Other Features
  JDO sample JAR

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

More
  Presentations
  The Examples
  3rd Party Tools
  JDO Tests
  XML Tests
  Configuration
  Tips & Tricks
  Full JavaDoc
  CastorWiki
 
 

About
  License
  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.

 
   
  
   
 


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