mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 09:57:18 +00:00
218 lines
7.2 KiB
Plaintext
218 lines
7.2 KiB
Plaintext
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 <JE_HOME>/src/com/sleepycat/je/jca/ra/ra.xml.
|
|
|
|
(1) Search for "<transaction-support>"
|
|
|
|
(2) Select the appropriate value (LocalTransaction, NoTransaction, or
|
|
XATransaction), and comment out or delete the other two. Don't use
|
|
multiple values of <transaction-support>.
|
|
|
|
(3) Change the value of the <security-permission-spec> 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 <JE-HOME>/build.properties:
|
|
|
|
(1) Set j2ee.jarfile to an appropriate j2ee.jar. For example,
|
|
|
|
j2ee.jarfile = <JBOSS-HOME>/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 = <JE-HOME>/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 <JE-HOME>, execute
|
|
|
|
ant jca
|
|
|
|
This creates a jejca.rar Resource Adapter Archive in <JE_HOME>/build/lib.
|
|
The jejca.rar archive contains a je.jar file.
|
|
|
|
- Deploy the JE Resource Adapter (<JE_HOME>/build/lib/jejca.rar),
|
|
using an appropriate JBoss deployment tool or by simply copying it
|
|
to the JBoss deployment directory. For example,
|
|
|
|
copy <JE_HOME>/build/lib/jejca.rar <JBOSS>/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 <JE_HOME>/build.properties:
|
|
|
|
(1) Set example.jca.srcdir to <JE_HOME>/examples/jca/jboss
|
|
|
|
example.jca.srcdir = <JE_HOME>/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
|
|
<security-permission-spec> tag. This directory should exist and
|
|
the JBoss server should have write permission to that directory.
|
|
The source code for SimpleBean is in
|
|
|
|
<JE_HOME>/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
|
|
|
|
<JE_HOME>/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:
|
|
|
|
<jndi-name>java:/LocalTransJE</jndi-name>
|
|
<jndi-name>java:/NoTransJE</jndi-name>
|
|
<jndi-name>java:/XATransJE</jndi-name>
|
|
|
|
- Build the SimpleBean example and jar file.
|
|
|
|
ant jca-examples
|
|
|
|
This builds a jejca-example.jar file and places it in the
|
|
<JE_HOME>/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 <JE_HOME>/build/lib/jejca-example.jar <JBOSS>/server/default/deploy
|
|
|
|
- Depending on which transaction support you have selected, examine the
|
|
corresponding RA service configuration file in
|
|
|
|
<JE_HOME>/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 <JE_HOME>/examples/jca/jboss/je-localtx-ds.xml
|
|
<JBOSS>/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
|
|
|
|
<JE_HOME>/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.
|