mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
267 lines
8.9 KiB
Plaintext
267 lines
8.9 KiB
Plaintext
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 <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. OC4J needs this to file grant access
|
|
permission to JE, otherwise security exceptions will result.
|
|
|
|
- Edit <JE_HOME>/build.properties:
|
|
|
|
(1) Set j2ee.jarfile to an appropriate j2ee.jar. For example,
|
|
|
|
j2ee.jarfile = <OC4J-HOME>/j2ee/home/lib/ejb.jar:
|
|
<OC4J-HOME>/oc4j/j2ee/home/lib/connector.jar:
|
|
<OC4J-HOME>/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 = <JE-HOME>/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
|
|
<application-client>
|
|
<ejb-ref>
|
|
<ejb-ref-name>SimpleBean</ejb-ref-name>
|
|
<ejb-ref-type>Session</ejb-ref-type>
|
|
<home>jca.simple.SimpleHome</home>
|
|
<remote>jca.simple.Simple</remote>
|
|
</ejb-ref>
|
|
</application-client>
|
|
|
|
- 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 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 <your admin password>
|
|
|
|
or
|
|
|
|
java -jar <OC4J-HOME>/j2ee/home/admin_client.jar
|
|
deployer:oc4j:localhost:23791 oc4jadmin <password> -shutdown
|
|
|
|
- Deploy the JE Resource Adapter (<JE_HOME>/build/lib/jejca.rar),
|
|
using the Oracle Application Server Control web tool:
|
|
|
|
http://<hostname>: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 (<JE-HOME>/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 <JE_HOME>/build.properties:
|
|
|
|
(1) Set example.jca.srcdir to <JE_HOME>/examples/jca/oc4j
|
|
|
|
example.jca.srcdir = <JE_HOME>/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 <JE_HOME>/examples/jca/simple/ejb-jar.xml
|
|
Uncomment the <assembly-descriptor> 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
|
|
<security-permission-spec> tag. This directory should exist and
|
|
the OC4J 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 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 <transaction-support> (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
|
|
<JE_HOME>/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://<hostname>:8888
|
|
login if necessary
|
|
Applications tab
|
|
Select "Applications" from the "View" pulldown.
|
|
Select "Deploy"
|
|
Enter the location of the jejca-example.jar file
|
|
(<JE-HOME>/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
|
|
|
|
<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.
|