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

## How to use Castor with(in) distributed J2EE transactions

Overview
Intended audience
Steps
Make Castor participate in a J2EE transaction
Make Castor participate in container-managed J2EE transaction
Resource enlisting
Tips
References

## Overview

J2EE applications depend on the J2EE container (hosting Servlet, EJB, etc) to configure a database connection (as well as other resource managers) and use JNDI to look it up. This model allows the application deployer to configure the database properties from a central place, and gives the J2EE container the ability to manage distributed transactions across multiple data sources.

This HOW-TO shows how to seamlessly use Castor JDO in such a managed environment, and how to make Castor participate in a distributed transaction.

## Intended audience

Anyone who wants to use Castor JDO with(in) distributed J2EE transactions.

## Steps

The following sections highlight the steps necessary to use Castor JDO seamlessly in such a (managed) environment, and how to make Castor participate in a distributed transaction.

### Make Castor participate in a J2EE transaction

The following code fragment shows how to use JNDI to lookup a database and how to use a JTA `UserTransaction` instance to manage the J2EE (aka distributed) transaction:

    // Lookup databse in JNDI
    Context ctx = new InitialContext();
    Database db = (Database) ctx.lookup( "java:comp/env/jdo/mydb" );

    // Begin a transaction
    UserTransaction ut = (UserTransaction) ctx.lookup( "java:comp/UserTransaction" );
    ut.begin();
    // Do something
    . . .
    // Commit the transaction, close database
    ut.commit();
    db.close();

### Make Castor participate in container-managed J2EE transaction

If the transaction is managed by the container, a common case with EJB beans and in particular entity beans, there is no need to begin/commit the transaction explicitly. Instead the application server takes care of enlisting the database used by Castor JDO to insert domain entities into a database in the ongoing transaction and commiting/rolling back at the relevant time.

The following code snippet relies on the container to manage the transaction.

    InitialContext  ctx;
    UserTransaction ut;
    Database        db;

    // Lookup databse in JNDI
    ctx = new InitialContext();
    db = (Database) ctx.lookup( "java:comp/env/jdo/mydb" );

    // Do something
    . . .
    // Close the database
    db.close();

As transaction enregistration is dealt with at the J2EE container, it is not necessary anymore to obtain a `UserTransaction` and start/commit the transaction manually.

### Resource enlisting

Instead of constructing required resources directly, a typical J2EE application uses the JNDI API to look up resources from centrally managed place such as a naming and directory service. In such an environment, Castor JDO takes on the role of a managed resource as well. It follows that, instead of constructing a <api>org.exolab.castor.jdo.JDOManager</api> directly, a typical J2EE application should use JNDI to look it up.

We thus recommend enlisting the `JDOManager` object under the `java:comp/env/jdo` namespace, compatible with the convention for listing JDBC resources.

## Tips

-

When using Castor JDO in a J2EE environment, Castor allows you to enable a special Database instance pooling support. This option is configured via the <api>org.exolab.castor.jdo.JDOManager'setDatabasePooling(boolean)</api> method; by default, it is turned off. This option only affects JDOManager if J2EE transactions are used and if a transaction is associated with the thread that calls {@link #getDatabase}.
If database pooling is enabled, JDOManager will first search in this special pool to see if there is already a <api>org.exolab.castor.jdo.Database</api> instance for the current transaction. If found, it returns this <api>org.exolab.castor.jdo.Database</api> instance; if not, it creates a new one, associates it will the transaction and returns the newly created <api>org.exolab.castor.jdo.Database</api> instance.
Please makes ure that you call this method before calling {@link #getDatabase}.

## References

- | Other pooling examples

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