Getting started with JDO on Jboss AS7 in Seven Steps

Jboss as7 is the latest JavaEE6 server while Datanucleus is the greatest peristance(JDO) implementation. Integrating these two softwares is straight forward. However to be able to leverage all the power of JavaEE and also enjoy power of JDO I will engage you in a seven step process

1.Download AS7 and Datanucleus
2.Install Jboss As 7
3.Install and configure jdbcdriver/ datasource
4.Install Datanucleus as jboss module
5.Install Datanucleus JCA
6.Configure Datanucleus
7.Access the PersistenceManager

Step 1. Download AS7 and Datanucleus

• http://www.jboss.org/as7 - I have jboss-as-7.0.0.Final
• http://sourceforge.net/projects/datanucleus/files/datanucleus-accessplatform/ - I have datanucleus-accessplatform-full-deps-3.0.0-m6.zip
• http://sourceforge.net/projects/datanucleus/files/datanucleus-jca/ - I have datanucleus-jca-3.0.0-m6.rar

Step 2. Install Jboss AS 7

• unzip into $home/jboss-as-7.0.0.Final -- Thats it

Jboss AS 7 is new server and its going to be a new new experice one stay with me on this wonderful flight. It loads fast <3s. Configuration is controlled by single file standalone.xml or domain.xml. Two modes of operation standalone and domain mode we will work in standalone mode. Modular server with osgi support Upgraded to JCA 1.6. Classloading is entirely fresh. Ofcource I have listed very few which are relavant here.
Start the server $home/jboss-as-7.0.0.Final/bin/standalone.sh and open http://localhost:8080/
Expect to see this banner “Welcome to AS 7”. Jboss7 runs runs in two modes standalone and domain. In standalone mode it uses standalone.xml and in Domain mode it looks for domain.xml. In this exercise we are intrested in standalone.xml

Step 3. Install and configure jdbcdriver/ datasource

Very simple drop the driver in $home/jboss-as-7.0.0.Final/standalone/deployments. Yes believe me you have installed the driver and ready for use.
Next we need two datasources one Managed and other non managed. So i created java:jboss/datasources/TradeDBDS which has jta="false" and java:jboss/datasources/TradeDBDSJTA with jta="true"
Every thing in Jboss as7 is a module and controlled by respective subsystem. The datasource is managed by

urn:jboss:domain:datasources:1.0.

Locate it in your standalone.xml. Below is the sample datasource

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
<datasource jndi-name="java:jboss/datasources/TradeDBDS" pool-name="TRADEDB_Pool" enabled="true" jta="false" use-java-context="true" use-ccm="true">
<connection-url>
jdbc:oracle:thin:@10.10.10.10:1521:orcl11g
</connection-url>
<driver>
ojdbc6.jar
</driver>
<pool>
<min-pool-size>
1
</min-pool-size>
<max-pool-size>
2
</max-pool-size>
<prefill>
true
</prefill>
<use-strict-min>
false
</use-strict-min>
<flush-strategy>
FailingConnectionOnly
</flush-strategy>
</pool>
<security>
<user-name>
tradedb
</user-name>
<password>
keepguessing
</password>
</security>
</datasource>
</subsystem>

Step 4. Install Datanucleus as jboss module
The libraries inside the webapplication cannot access the libraries in the JCA connector. Jboss takes care of JavaEE libraries such that all the webapplications have proper access. Since jdo is not part of javaEE we have to tell Jboss to share these libraries with all web applications. The trick is very easy
Create a folder $home/jboss-as-7.0.0.Final/modules/javax/jdo/main. Copy following files datanucleus-api-jdo-3.0.0-m6.jar, datanucleus-cache-3.0.0-m4.jar,datanucleus-core-3.0.0-m6.jar,datanucleus-jdo-query-3.0.0-m3.jar,datanucleus-rdbms-3.0.0-m6.jar,jdo-api-3.1-SNAPSHOT-20110319.jar.
Notice the folder main
Create a file module.xml. Contents as follows

<module name="javax.jdo" xmlns="urn:jboss:module:1.0">
<resources>
<resource-root path="datanucleus-api-jdo-3.0.0-m6.jar"></resource-root>
<resource-root path="datanucleus-cache-3.0.0-m4.jar"></resource-root>
<resource-root path="datanucleus-core-3.0.0-m6.jar"></resource-root>
<resource-root path="datanucleus-jdo-query-3.0.0-m3.jar"></resource-root>
<resource-root path="datanucleus-rdbms-3.0.0-m6.jar"></resource-root>
<resource-root path="jdo-api-3.1-SNAPSHOT-20110319.jar"></resource-root>
</resources>
<dependencies>
<module name="javax.api"></module>
<module name="javax.transaction.api"></module>
</dependencies>
</module>

Let the classlaoder majick take over

Step 5 Install Datanucleus JCA
Open the rar file remove all the jars except datanucleus-jca-3.0.0-m6.jar. Remove all xml files except plugin.xml. Edit ra.xml inside META-INF folder replace the contents with

<connector>
<display-name>DataNucleus Connector</display-name>
<description></description>
<vendor-name>DataNucleus</vendor-name>
<spec-version>1.0</spec-version>
<eis-type>JDO Adaptor</eis-type>
<version>1.0</version>
<resourceadapter>
<managedconnectionfactory-class>org.datanucleus.jdo.connector.ManagedConnectionFactoryImpl</managedconnectionfactory-class>
<connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface>
<connectionfactory-impl-class>org.datanucleus.jdo.connector.PersistenceManagerFactoryImpl</connectionfactory-impl-class>
<connection-interface>javax.resource.cci.Connection</connection-interface>
<connection-impl-class>org.datanucleus.jdo.connector.PersistenceManagerImpl</connection-impl-class>
<transaction-support>LocalTransaction</transaction-support>
<config-property>
<config-property-name>PersistenceUnitName</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>"pu"</config-property-value>
</config-property>
<config-property>
<config-property-name>PersistenceXmlFilename</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>file:///data1/jboss-as-7.0.0.Final/standalone/deployments/jdopersistence.xml</config-property-value>
</config-property>
<authentication-mechanism>
<authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
<credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
</authentication-mechanism>
<reauthentication-support>false</reauthentication-support>
</resourceadapter>
</connector>

The important properties are PersistenceUnitName and PersistenceXmlFilename.
PersistenceUnitName has to be same across other files ie, standalone.xml and jdopersistance.xml. I am using pu. To work around an known issue we have to xmlescape the characters around pu
PersistenceXmlFilename should point to the full path.
Add a file jboss-deployment-structure.xml in META-INF folder

<jboss-deployment-structure>
<deployment>
<exclusions>
</exclusions>
<dependencies>
<module name="javax.jdo"/>
</dependencies>
</deployment>
</jboss-deployment-structure>

This file tells jboss to load JCA after loading datanucleus(javax.jdo)

We can access the resource-adapter via JNDI. We need to inform Jboss the JNDI location where the persistanceManagerFactory should be available. Open standalone.xml and locate the subsystem for resource-adapter and copy the below configuration.

<subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
<resource-adapters>
<resource-adapter>
<archive>
datanucleus-jca-3.0.0-m6.rar
</archive>
<connection-definitions>
<connection-definition
class-name="org.datanucleus.jdo.connector.ManagedConnectionFactoryImpl"
jndi-name="java:/TraderDB-PU"
enabled="true" use-java-context="true"
pool-name="DNConnectionFactory"
use-ccm="true">
<config-property name="PersistenceUnitName">
pu
</config-property>
</connection-definitions>
</connection-definitions>
</resource-adapter>
</resource-adapters>
</subsystem>

Step 6. Configure Datanucleus
All the configuration of datanucleus is in jdopersistence.xml. The file name should be same as defined in PersistenceXmlFilename. The behaviour can be defined by adding properties. Detailed list of properties is here.
jdopersistance.xml

<?xml version="1.0" encoding="UTF-8" ?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
<persistence-unit name="pu">
<properties>
<property name="datanucleus.connection.resourceType" value="JTA"/>
<property name="datanucleus.storeManagerType" value="rdbms"/>
<property name="datanucleus.autoCreateSchema" value="false"/>
<property name="datanucleus.ConnectionFactoryName" value="java:jboss/datasources/TradeDBDSJTA"/>
<property name="datanucleus.ConnectionFactory2Name" value="java:jboss/datasources/TradeDBDS"/>
<property name="datanucleus.autoStartClassNames" value="com.blogspot.jkook.daytrader.jdo.JDOOrderData"/>
<property name="datanucleus.autoStartMechanism" value="Classes"/>
<property name="datanucleus.autoStartMechanismMode" value="Ignored"/>
<property name="datanucleus.jtaLocator" value="custom_jndi"/>
<property name="datanucleus.jtaJndiLocation" value="java:jboss/TransactionManager"/>
</properties>
</persistence-unit>
</persistence>

datanucleus.ConnectionFactoryName has to be JTA enabled datasource
datanucleus.ConnectionFactory2Name has to be non JTA
TransactionManger JNDI name in as7 has changed so we need to configure using datanucleus.jtaJndiLocation and datanucleus.jtaLocator
Almost done ! stay with me to start coding

Step 7. Access PersistenceManager
Alright enough configuiration show me some code. PersistenceManager can be accesed through JNDI either by injecting or by direct access using InitialContext(). I prefer to use CDI @Producer and @Inject here is the sample

PersistenceManagerFactory pmf = (PersistenceManagerFactory) 
context.lookup("java:/TraderDB-PU");
PersistenceManager pm = pmf.getPersistenceManager();

Appratus
Jdk 1.6, JbossAs7, NetBeans, ojdbc6.jar, Oracle11g, Datanucleus3.0.0-m6, JavaEE6, CDI, Ejb3.1