1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
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.
|
