How to use the Berkeley DB Java Edition JCA Resource Adapter in the Oracle Containers for J2EE version 10.1.3.2.0. Prerequisites: - OC4J version 10.1.3.2.0 - ant 1.5.4 or later - J2EE jar files (available in the OC4J distribution) This HOWTO describes: (1) how to build and deploy the Berkeley DB Java Edition JCA Resource Adapter under OC4J version 10.1.3.2.0 (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 be built. 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. OC4J needs this to file grant access permission to JE, otherwise security exceptions will result. - Edit /build.properties: (1) Set j2ee.jarfile to an appropriate j2ee.jar. For example, j2ee.jarfile = /j2ee/home/lib/ejb.jar: /oc4j/j2ee/home/lib/connector.jar: /oc4j/j2ee/home/lib/oc4j-internal.jar The value specified for j2ee.jarfile should contain all the classes necessary for proper execution of the JCA Resource Adapter (for example, JNDI). (2) Set example.resources to an appropriate value, e.g. example.resources = /examples/resources/oc4j/oc4j.jar The oc4j.jar file contains an application-client.xml file which looks like this: bash-3.00$ cat examples/resources/oc4j/META-INF/application-client.xml SimpleBean Session jca.simple.SimpleHome jca.simple.Simple - With the current directory set to , execute ant jca This creates a jejca.rar Resource Adapter Archive in /build/lib. The jejca.rar contains a je.jar file. - If OC4J is not already started, start it now. oc4j -start Note: The server can be stopped with the asadmin stop-domain command. e.g. oc4j -shutdown -port 23791 -password or java -jar /j2ee/home/admin_client.jar deployer:oc4j:localhost:23791 oc4jadmin -shutdown - Deploy the JE Resource Adapter (/build/lib/jejca.rar), using the Oracle Application Server Control web tool: http://:8888 login if necessary Applications tab In the "View" pulldown, select 'Standalone Resource Adapters' Select "Deploy" In the "Archive" section of the screen, enter the file name of the jejca.rar file (/build/lib/jejca.rar). Select "Next" Enter "JEConnection" for Resource Adapter Name Select "Next" Select "Deploy" - Create the connector connection pool and connector resource: After the RA has been successfully deployed, select "Return" On the Home | Applications | Stand Alone Resource Adapters page, select "Berkeley DB Java Edition JCA Adapter" link Select "Connection Factories" Under "Shared Connection Pools", select "Create" Enter "JEConnectionPool" for Connection Pool Name and Select "OK" Above "JNDI Location" select "Create" Make sure that com.sleepycat.je.jca.ra.JEConnectionFactory is selected in the pull down menu and select "Continue" Enter "ra/JEConnectionPool" for "JNDI Location" Select "Use Shared Connection Pool" and chose "JEConnectionPool" in the menu. Select "Finish" - If you change or rebuild the jejca.rar file, you must redeploy the Resource Adapter file with the same steps above. 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 OC4J server. You can use this example to test the JE RA that you just deployed. - Edit /build.properties: (1) Set example.jca.srcdir to /examples/jca/oc4j example.jca.srcdir = /examples/jca/oc4j This is the directory where the OC4J specific deployment descriptor for the "simple" EJB resides. (2) Set example.jca.descriptorname to orion-ejb-jar.xml. example.jca.desciptorname = orion-ejb-jar.xml This is the name of the OC4J specific deployment descriptor for the "simple" EJB. - Edit /examples/jca/simple/ejb-jar.xml Uncomment the section at the end of the file. - 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 OC4J 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 source code for SimpleBean to have the correct value for TRANSACTIONAL. If you set it to true, you should also set the proper value in the ra.xml for (either LocalTransaction or XATransaction). - Edit the SimpleClient.java file to have correct values for the JNDI lookup properties (java.naming.*). - Edit the SimpleClient.java file to change the value of OC4J to true. - 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 sun-ejb-jar.xml descriptor files. - Deploy the jejca-example jar using the Oracle Application Server Control web tool: http://:8888 login if necessary Applications tab Select "Applications" from the "View" pulldown. Select "Deploy" Enter the location of the jejca-example.jar file (/build/lib/jejca-example.jar) in the "Location on Server" box in the "Archive" section. Select "Next". Enter "Simple" in the "Application Name" box. Select "Next". On the "Deploy: Deployment Settings" page, click the pencil next to "Map Environment References". In the "Map Resource References" section, enter "ra/JEConnectionFactory" in the form box for the "ra/JEConnectionFactory" Resource Reference. Select "OK". Select "Deploy". Running the "SimpleBean" Example: --------------------------------- - Verify that the OC4J 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.log 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.