How to use the Berkeley DB Java Edition JCA Resource Adapter in JBoss 3.2.6 Prerequisites: JBoss 3.2.6 ant 1.5.4 or later J2EE jar files (available in the JBoss distribution) This HOWTO describes: (1) how to build and deploy the Berkeley DB Java Edition JCA Resource Adapter under the JBoss Application Server (v3.2.6). (2) how to run a simple smoke test to test that the RA has been deployed correctly. (3) some notes on writing applications that use the RA. The Berkeley DB Java Edition (JE) JCA code depends on J2EE libraries, but the regular JE code does not require these libraries in order to build. Therefore, the "ant compile" target only builds the non-J2EE based code. To build the JE JCA libraries and examples, it is necessary to have the appropriate J2EE jar files available and to use additional ant targets. Building the Resource Adapter ----------------------------- - Edit /src/com/sleepycat/je/jca/ra/ra.xml. (1) Search for "" (2) Select the appropriate value (LocalTransaction, NoTransaction, or XATransaction), and comment out or delete the other two. Don't use multiple values of . (3) Change the value of the to refer to the JE environment directory. JBoss needs this to grant access permission to JE, otherwise security exceptions will result. Note: If you use XATransaction, all your databases must be transactional. - Edit /build.properties: (1) Set j2ee.jarfile to an appropriate j2ee.jar. For example, j2ee.jarfile = /client/jbossall-client.jar The value specified for j2ee.jarfile should contain all the classes necessary for proper execution of the JCA Resource Adapter (for example, JNDI). The jbossall-client.jar is sufficient. (2) Set example.resources to an appropriate value, e.g. example.resources = /examples/resources/jboss The example.resources property should contain a jndi.properties file that is correct for the target environment. If you are using the jndi.properties supplied in the {examples.resources} directory, review it to make sure it has correct values. - With the current directory set to , execute ant jca This creates a jejca.rar Resource Adapter Archive in /build/lib. The jejca.rar archive contains a je.jar file. - Deploy the JE Resource Adapter (/build/lib/jejca.rar), using an appropriate JBoss deployment tool or by simply copying it to the JBoss deployment directory. For example, copy /build/lib/jejca.rar /server/default/deploy - If the JBoss server is not already running, start it now. Building the "SimpleBean" Example: ---------------------------------- The SimpleBean example is an EJB that has two methods, get() and put(), which get and put data using the JE Resource Adapter on the JBoss server. You can use this example to test the JE Resource Adapter that you just deployed. - Edit /build.properties: (1) Set example.jca.srcdir to /examples/jca/jboss example.jca.srcdir = /examples/jca/jboss This is the directory where the JBoss specific deployment descriptor for the "simple" EJB resides. (2) Set example.jca.descriptorname to jboss.xml. example.jca.desciptorname = jboss.xml This is the name of the jboss specific deployment descriptor for the "simple" EJB. - Edit the source code for SimpleBean to refer to the correct directory for the JE Environment. The JE Environment directory is the same one that was specified in the ra.xml file under the tag. This directory should exist and the JBoss server should have write permission to that directory. The source code for SimpleBean is in /examples/jca/simple/SimpleBean.java To set the directory, change the value of JE_ENV at the top of the class. For example, private final String JE_ENV = "/tmp/je_store"; - Edit the jboss.xml descriptor in /examples/jca/jboss/jboss.xml to use the jndi-name that corresponds to the transaction-support value in the ra.xml file above. That is, select one of the following three lines and comment out or remove the other two: java:/LocalTransJE java:/NoTransJE java:/XATransJE - Build the SimpleBean example and jar file. ant jca-examples This builds a jejca-example.jar file and places it in the /build/lib directory. The jar file contains the SimpleBean classes, and the ejb-jar.xml and jboss.xml descriptor files. - Deploy the jejca-example jar by copying it to a deployment directory (or use an appropriate deployment tool). For example, copy /build/lib/jejca-example.jar /server/default/deploy - Depending on which transaction support you have selected, examine the corresponding RA service configuration file in /examples/jca/jboss (e.g. je-localtx-ds.xml). Ensure that the jndi-name matches the name that you selected in the jboss.xml file in the same directory. - Deploy the RA service configuration file (e.g. je-localtx-ds.xml) by copying it to the JBoss server deployment directory or using an appropriate deployment tool. For example, copy /examples/jca/jboss/je-localtx-ds.xml /server/default/deploy Running the "SimpleBean" Example: --------------------------------- - Verify that the JBoss server has been started. - Run the client: ant testex-jejcasimple -Dkey=foo -Ddata=bar This should produce: Buildfile: build.xml testex-jejcasimple: [java] Created Simple [java] Simple.get('foo') = bar BUILD SUCCESSFUL Total time: 3 seconds If you don't see [java] Simple.get('foo') = bar printed (for example, you see Simple.get('foo') = null), there may be a configuration problem. Check the server logfile for details. Implementation Notes for Applications Using the RA -------------------------------------------------- Please refer to the SimpleBean example in /examples/jca/simple/SimpleBean.java - Obtain a JEConnection using the JEConnectionFactory.getConnection() method and passing it an environment home directory and EnvironmentConfig object. Once the JEConnection has been obtained, you can obtain the Environment handle by calling JEConnection.getEnvironment(); - Database handle cache available Because bean business methods may be relatively short, the underlying ManagedConnection object for JE provides a Database handle cache. This speeds up the Database open operation since the handle (generally) already exists in the cache. Normally, a program opens a database using the Environment.openDatabase() method. In the EJB environment, the program should call JEConnection.openDatabase() instead. Database handles obtained using this method should not be close()'d as the ManagedConnection code does that when the ManagedConnection is closed. - Databases under XA must be transactional If you are using the XATransaction environment (as specified in the ra.xml file), all JE Databases used in that environment must be transactional.