Extensions : JTA Locator

Plugin

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the locator for JTA TransactionManagers (since J2EE doesnt define a standard mechanism for location). DataNucleus provides several plugins for the principal application servers available but is structured so that you can easily add your own variant and have it usable within your DataNucleus usage.

Locators for JTA TransactionManagers can be plugged using the plugin extension org.datanucleus.jta_locator. These are of relevance when running with JTA transaction and linking in to the JTA transaction of some controlling application server.

Plugin extension-point Key Description Location
org.datanucleus.jta_locator jboss JBoss datanucleus-core
org.datanucleus.jta_locator jonas JOnAS datanucleus-core
org.datanucleus.jta_locator jotm JOTM datanucleus-core
org.datanucleus.jta_locator oc4j OC4J datanucleus-core
org.datanucleus.jta_locator orion Orion datanucleus-core
org.datanucleus.jta_locator resin Resin datanucleus-core
org.datanucleus.jta_locator sap SAP app server datanucleus-core
org.datanucleus.jta_locator sun Sun ONE app server datanucleus-core
org.datanucleus.jta_locator weblogic WebLogic app server datanucleus-core
org.datanucleus.jta_locator websphere WebSphere 4/5 datanucleus-core
org.datanucleus.jta_locator custom_jndi Custom JNDI datanucleus-core
org.datanucleus.jta_locator atomikos Atomikos datanucleus-core

The following sections describe how to create your own JTA Locator plugin for DataNucleus.

Interface

If you have your own JTA Locator you can easily use it with DataNucleus. DataNucleus defines a TransactionManagerLocator interface and you need to implement this. Javadoc.

package org.datanucleus.jta;

import javax.transaction.TransactionManager;
import org.datanucleus.ClassLoaderResolver;

public interface TransactionManagerLocator
{
    /**
     * Method to return the TransactionManager.
     * @param clr ClassLoader resolver
     * @return The TransactionManager
     */
    TransactionManager getTransactionManager(ClassLoaderResolver clr);
}

So you need to create a class, MyTransactionManagerLocator for example, that implements this interface.

Plugin Specification

Once you have this implementation you then need to make the class available as a DataNucleus plugin. You do this by putting a file plugin.xml in your JAR at the root of the CLASSPATH. The file plugin.xml will look like this

<?xml version="1.0"?>
<plugin id="mydomain.mylocator" name="DataNucleus plug-ins" provider-name="My Company">
    <extension point="org.datanucleus.jta_locator">
        <jta_locator name="MyLocator" class-name="mydomain.MyTransactionManagerLocator"/>
    </extension>
</plugin>

Note that you also require a MANIFEST.MF file as per the Extensions Guide.

Plugin Usage

The only thing remaining is to use your JTA Locator plugin. To do this you specify the persistence property datanucleus.jtaLocator as MyLocator (the name in plugin.xml).