Kodo deployment includes choosing a factory deployment strategy, and in a managed environment, optionally integrating with your application server's managed and XA transactions. This chapter examines each aspect of deployment in turn.
Kodo offers several
EntityManagerFactory
and
PersistenceManagerFactory
deployment options.
The JPA Overview describes the
javax.persistence.Persistence
class. You can use
Persistence
to obtain
EntityManagerFactory
instances, as demonstrated in
Chapter 6, Persistence
. Kodo also extends
Persistence
to add additional
EntityManagerFactory
creation methods. The
org.apache.openjpa.persistence.OpenJPAPersistence
class
Javadoc
details these extensions.
Chapter 6, JDOHelper
of the JDO Overview describes the
JDOHelper
class.
Section 6.3, “PersistenceManagerFactory Construction”
shows how to use the
JDOHelper
to construct
PersistenceManagerFactory
objects in a vendor-neutral fashion.
After obtaining the factory, you can cache it for all
EntityManager
or
PersistenceManager
creation duties.
Java EE 5 application servers allow you to
inject
entity managers into your session beans using the
PersistenceContext
annotation. See your application server documentation
for details.
Kodo can deploy Kodo JPA through the Java Connector Architecture (JCA) in any JCA-compliant application server that supports JDK 1.5 (all EJB 3 implementations require JDK 1.5). We present the deployment steps for the most common servers below.
First, ensure that your JDBC driver is in your
system classpath. In addition, you will be adding
the Kodo and specification API jars to the system
classpath. You can accomplish this by editing
startWebLogic.sh/.cmd
.
Warning | |
---|---|
Currently WebLogic ships with an old version of
the EJB 3 libraries. Be sure to put
|
The next step is to deploy
kodo-persistence.rar
from the
jca/persistence
directory of your Kodo installation. Copy this file
to the
autodeploy
directory of your domain.
We will now extract
META-INF/ra.xml
and
META-INF/weblogic-ra.xml
to edit our configuration:
jar xvf kodo-persistence.rar META-INF/ra.xml META-INF/weblogic-ra.xml
Now you should configure Kodo JCA by editing
META-INF/ra.xml
substituting
config-property-value
stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or you can leave them at their default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now we can re-jar the manifest files back into the
RAR
file.
jar uvf kodo-persistence.rar META-INF/ra.xml META-INF/weblogic-ra.xml rm META-INF/ra.xml META-IN/weblogic-ra.xml rmdir META-INF
Now you can start WebLogic and WebLogic should deploy Kodo for you. If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
First you must add the JPA specification jar,
jpa.jar
, which is found in the
lib
directory of the disribution,
to the server library directory: e.g.
jboss-4.0.3/server/default/lib
).
In addition, you should also place the appropriate JDBC
driver jar and openjpa.jar into that same
directory.
Note | |
---|---|
JBoss currently ships with a stale version of the
JPA specification jar. You should remove the
old copy of this jar,
|
The jca/persistence
directory of the Kodo
distribution includes
kodo-persistence-jboss40-ds.xml
. This file
should be edited to reflect your configuration, most notably
connection values. Enter a JNDI name for Kodo
to bind to (the default is kodo-persistence
).
Stop JBoss. Copy kodo-persistence.rar
and
kodo-ejb-jboss40-ds.xml
to the deploy
directory of your JBoss server installation (e.g.
jboss-4.0.3/server/default/deploy
). Once you
have done this, you can restart JBoss to deploy Kodo.
To verify your installation, watch the console output for
exceptions. In addition, you can check to see if Kodo was
bound to JNDI. Open up your jmx-console (
http://yourhost:yourport/jmx-console
) and
select the JNDIView service. If Kodo was installed correctly,
you should see the Kodo connection factory bound at the JNDI
name you specified. You have now installed Kodo JPA JCA.
Kodo can be deployed as a Java Connector Architecture (JCA) module or as shared application libraries. The sample user applications provided in the Kodo distribution demonstrate access patterns for both kinds of deployment.
The Kodo JCA Connector module for JPA is available in
jca/persistence/kodo-persistence.rar
. The
JCA Connector module is configured in
META-INF/ra.xml
in kodo-persistence.rar
archive file. The configuration file ra.xml
must be edited for your environment before it can be deployed.
Go to the %KODO_HOME%/jca/persistence
directory:
$ cd %KODO_HOME%/jca/persistence
Extract ra.xml
:
$ jar xvf kodo-persistence.jar META-INF/ra.xml
With a text or XML editor, edit META-INF/ra.xml
as follows:
Specify appropriate values for database connection
properties namely <ConnectionDriver>
,
<ConnectionURL>
,
<ConnectionUserName>
; and
<ConnectionPassword>
properties.
Specify <value>buildSchema</value>
for <SynchronizeMappings>
property.
This setting ensures that Kodo will define the database
schema for the persistent classes.
The JCA Connector module will be bound to the JNDI tree of GlassFish.
The JNDI name for the JCA connector is specified in the
sun-ra.xml
file. The Kodo distribution provides the
jca/persistence/sun-ra.xml
file, which specifies the JNDI name
for JPA JCA Connector as kodo-persistence
.
You can edit sun-ra.xml
to specify a different name.
After making edits appropriate for your environment, update the
kodo-persistence.rar
archive with the edited
version of ra.xml
and sun-ra.xml
, as follows:
$ cp sun-ra.xml META-INF/sun-ra.xml
$ jar uvf kodo-persistence.rar META-INF
Copy the following application libraries from
%KODO_HOME%/lib
to %GLASSFISH%/lib
:
commons-collections-3.2.jar
commons-lang-2.1.jar
commons-pool-1.3.jar
jpa.jar
openjpa.jar
serp.jar
Start the GlassFish application server:
$ cd %GLASSFISH_HOME%/bin $ asadmin -start-domain domain1
Deploy the JCA Connector module
$ asadmin deploy %KODO_HOME%/jca/persistence/kodo-persistence.rarOr, if you prefer, open the GlassFish Administration Console in a browser. If you are running Glassfish on your local machine with the default configuration, the Administration Console is available at
http://localhost:4848/
.
Activate Connector Modules > Deploy
and select the file
%KODO_HOME%/jca/persistence/kodo-jar.rar
.
The Kodo distribution provides a set of samples to demonstrate usage within a J2EE Application Server. Some of the samples access Kodo persistence services by looking up JNDI for JCA Connector modules while others use the direct bootstrap API.
For both the JSP and EJB samples described below, perform the following step first:
Edit META-INF/persistence.xml
and
specify the appropriate values for these
database connection properties:
ConnectionDriverName
, ConnectionURL
,
ConnectionUserName
, and
ConnectionPassword
.
Make sure these values are consistent with the setting in
META-INF/ra.xml
in
jca/persistence/kodo-persistence.rar
.
This sample is available in %KODO_HOME%/samples/persistence/j2ee
.
It uses Kodo JPA by looking for the JPA JCA Connection module in JNDI.
The sample also demonstrates the use of EJB 2.0 Beans using persistent classes.
The steps to run the sample are presented in the build.xml
Ant script.
Follow these instructions to run this sample:
Deploy the JPA JCA Connector module. The sample is configured for
the HSQL database, and a JDBC driver is provided in
%KODO_HOME%/lib
. Copy the HSQL driver to
%GLASSFISH%/lib
. If you are using any other database,
add the appropriate JDBC driver to %GLASSFISH%/lib
.
Change to the %KODO_HOME%/samples/persistence/j2ee directory
.
Ensure that the JNDI name in the setSessionContext()
method in ejb/CarBean.java
matches your JCA installation.
This defaults to java:/kodo-ejb
, but the actual value
depends on the configuration of your JCA deployment and your application server's
JNDI context. For example, the default name for a WebLogic 9 install would be simply
kodo-ejb
.
Compile the source files in place both in this base directory as well as
the nested ejb
and jsp
directories:
javac *.java ejb/*.java jsp/*.java
Enhance the Car class:
kodoc -p persistence.xml Car.java
Run the mapping tool; make sure that your META-INF/persistence.xml
file includes the same connection information (e.g. Driver, URL, etc.) as your
JCA installation, although note that when you deploy via JCA, the configuration
information used at runtime will be the information provided in the JCA
configuration file, not the persistence.xml
file. You should
update your JCA configuration to include samples.persistence.j2ee.Car
in the Types
parameter of the of the MetaDataFactory
property:
<config-property name="MetaDataFactory">Types=samples.persistence.j2ee.Car</config-property/> mappingtool -p persistence.xml Car.java
Build a J2EE application archive by running Ant against the build.xml
file.
This will create kodo-persistence-j2ee-sample.ear
. This ear can now be
deployed to your application server. Be sure to add the class samples.j2ee.Car
to the kodo.MetaDataFactory
Kodo configuration property. This will
automatically register the Entity.
ant -f build.xml
Deploy the enterprise application in GlassFish:
$ cd %GLASSFISH%/bin $ asadmin deploy %KODO_HOME%/samples/persistence/j2ee/samplej2ee.ear
You can browse the running application at
http://<server>:<port>/samples/
.
Kodo can deploy through the Java Connector Architecture (JCA) in any JCA-compliant application server. We present the deployment steps for the most common servers below.
Installation of Kodo into WebLogic requires 3 steps. First
ensure that Kodo jars, the specification jars, and the
appropriate JDBC driver are in the system
classpath. In WebLogic 6.1.x, the classpath is set in the
startWebLogic.sh/cmd
in your domain
directory ($WL_HOME/config/mydomain
). In
WebLogic 7, this file is the startWLS.sh/cmd
file in the $WL_HOME/server/bin
directory.
Make sure to also add the JDO base jar
(jdo.jar
)
and the OpenJPA jar (openjpa.jar
) to
the classpath so that your enhanced classes can be loaded.
While this jar can be placed
inside an ear
file, putting
it in the system classpath will reduce class resolution
conflicts.
The kodo-jdo.rar
file must then either
be copied to the applications directory of your domain,
or uploaded through the web admin interface. To upload using
the web admin console, select
mydomain/Deployments/Connectors
in the left navigation bar and then select "Install a new
Connector Component." Browse to
kodo-jdo.rar
and upload it to the server.
You should see kodo-jdo
listed
now in the Connectors
folder in the
navigation pane. Select it and select
Edit Connector Descriptor
.
Under RA
,
expand Config Properties
in
the left pane and enter the appropriate values for each
property. Be sure to select Apply
for every property. In addition,
you should provide a JNDI name for Kodo by selecting
Weblogic RA
from the
navigation panel, entering an appropriate JNDI name, and
selecting Apply
. When you
are done configuring Kodo,
select the root (kodo-jdo.rar) of the navigation pane. Select
Persist
to save your
configuration properties and propagate them to the active
domain configuration.
You should see WebLogic attempt to deploy Kodo in the system
console. When it is done, return to the main admin web console.
Ensure that Kodo is deployed to your server by selecting
Targets
and adding your server
to the chosen area. Kodo should now be deployed to your
application server.
To verify the installation, you can view the JNDI tree
for your server. Select the server from the admin
navigation panel, right click on it, and select
View JNDI Tree
from the context menu.
You should now see Kodo at the JNDI name you provided. You
have now installed Kodo JDO JCA.
Note | |
---|---|
When using WebLogic 7, you may get invalid DTD exceptions when loading JDO metadata files, due to a problem with loading resources that are in jar files inside a resource archive. You can work around these problems by specifying a non-public DTD in your metadata files, like so: <!DOCTYPE jdo SYSTEM "http://java.sun.com/dtd/jdo_2_0.dtd"> |
Note | |
---|---|
In its current version (8.1.0), there are a number
of issues with classloaders in WebLogic's handling
of |
First, ensure that your JDBC driver is in your system classpath.
In addition, you will be adding the Kodo and specification API
jars to the system classpath. You can accomplish this by
editing startWebLogic.sh/.cmd
.
The next step is to deploy kodo-jdo.rar
from the jca/jdo
directory of your Kodo
installation. Create a directory named kodo-jdo.rar
in the applications
directory
of your domain. Un-jar kodo-jdo.rar
into this new directory (without copying kodo-jdo.rar itself).
Now you should configure Kodo JCA by editing
META-INF/ra.xml
substituting
config-property-value
stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or leaving at default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now you can start WebLogic and use the
console to deploy Kodo JCA. Browse
to your WebLogic admin port (http://yourhost:7001/console)
and browse to the Connectors
(Deployments -> Connector Modules) section
and select Deploy a new Connector
.
Browse to and select kodo-jdo.rar
and select Target Modules
to
ensure that Kodo is accessible to the proper servers.
If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
First, ensure that your JDBC driver is in your system classpath.
In addition, you will be adding the Kodo and specification API
jars to the system classpath. You can accomplish this by
editing startWebLogic.sh/.cmd
.
Warning | |
---|---|
Currently WebLogic ships with an old version
of the EJB 3 libraries. Be sure to put
|
The next step is to deploy the RAR
appropriate to the default specification you want to use.
For example, to default to JPA, copy kodo-persistence.rar
from the jca/ejb
directory
to the autodeploy
directory
of your domain.
We will now extract META-INF/ra.xml
and META-INF/weblogic-ra.xml
to edit our configuration:
jar xvf kodo-persistence.rar META-INF/ra.xml META-INF/weblogic-ra.xml
Now you should configure Kodo JCA by editing
META-INF/ra.xml
substituting
config-property-value
stanzas
with your own values. You can comment out
properties (config-property stanzas) which you are
not using or leaving at default settings.
Edit META-INF/weblogic-ra.xml
to configure the JNDI location to which you
want Kodo to be bound.
Now we can re-jar the manifest files back into the
RAR
file.
jar uvf kodo-persistence.rar META-INF/ra.xml META-INF/weblogic-ra.xml rm META-INF/ra.xml META-IN/weblogic-ra.xml rmdir META-INF
Now you can start WebLogic and WebLogic should deploy Kodo for you. If you have installed Kodo correctly, at this point, one should be able to see Kodo bound to the JNDI location which you specified earlier.
The jca/jdo
directory of the Kodo
distribution includes
kodo-jdo-jboss30-service.xml
. This file
should be edited to reflect your configuration, most notably
connection values. Enter a JNDI name for Kodo
to bind to (the default is kodo-jdo
). Stop
JBoss. Copy kodo-jdo.rar
and
kodo-jdo-jboss30-service.xml
to the deploy
directory of your JBoss server installation (e.g.
jboss-3.0.6/server/default/deploy
). Then copy the
jdo.jar and openjpa.jar files to the lib directory of
the JBoss server installation (e.g.,
jboss-3.0.6/server/lib/
), so that the
Kodo and the common specification APIs are available globally
in the JBoss installation. In addition, you should also place
the appropriate JDBC driver jar in the lib directory of your
JBoss installation (e.g. jboss-3.0.6/lib
).
To verify your installation, watch the console output for
exceptions. In addition, you can check to see if Kodo was
bound to JNDI. Open up your jmx-console (
http://yourhost:yourport/jmx-console
) and
select the JNDIView service. If Kodo was installed correctly,
you should see the Kodo connection factory bound at the JNDI
name you specified. You have now installed Kodo JDO JCA.
Installing in JBoss 3.2 is very similar to JBoss 3.0.
Instead of editing and deploying
kodo-jdo-jboss30-service.xml
, configuration
is controlled by kodo-jdo-jboss32-ds.xml
,
also in the jca/jdo
directory. Again,
configuration involves supplying a JNDI name to bind Kodo, and
setting up configuration values. These values are simple XML
elements with the configuration property name as element name.
kodo-jdo-jboss32-ds.xml
and
kodo-jdo.rar
should be deployed to the
deploy directory of JBoss. The installation is otherwise the
same as JBoss 3.0.
Installing in JBoss 4.x is very similar to JBoss 3.0 and 3.2.
Instead of editing and deploying
kodo-jdo-jboss30-service.xml
, configuration
is controlled by kodo-jdo-jboss40-ds.xml
,
also in the jca/jdo
directory. Again,
configuration involves supplying a JNDI name to bind Kodo, and
setting up configuration values. These values are simple XML
elements with the configuration property name as element name.
kodo-jdo-jboss4-ds.xml
and
kodo-jdo.rar
should be deployed to the
deploy directory of JBoss. The installation is otherwise the
same as JBoss 3.0.
Websphere installation is easiest through the web admin
interface. Open the admin console either by the Start
menu item (in Windows), or by manually navigating to
the admin port and URL appropriate to your installation. Select
Resources / Resource Adapters
from the left navigation panel. Select
Install Rar
on the list page. On the
following screen upload kodo-jdo.rar
to the
server. On the New
page,
enter a name for the new Kodo installation such as Kodo JDO JCA
and select Ok
.
You should now be back to the Resource Adapters list page.
Select the name of the Kodo installation you provided. Click
on the link marked J2C Connection
Factories
. This is where you can configure a
particular instance of Kodo's JCA implementation. Select
New
and you will be brought to
a configuration page. Be sure to fill in property
values for Name and JNDI Name. Select
Apply
.
After the page refreshes, select the Custom
Properties
link at the bottom of the page.
On the Custom Properties
page,
you can enter in your connection and other configuration
properties as necessary.
When you are done providing configuration values, you will
want to save your changes back to the system configuration.
Select the Save
link on the
page or the Save
link in the
menu bar. You have now installed Kodo JDO JCA.
Installation in SunONE / Sun JES application server requires
first providing JDO the proper permissions. This is
accomplished by editing the config/server.policy
for the server you are dealing with. Edit the
file to include the following line into a grant { } stanza.
permission javax.jdo.spi.JDOPermission "*";
Now restart the application server.
SunONE / Sun JES requires a Sun-specific deployment file in
addition to the generic ra.xml
. Edit the
sun-ra.xml
file provided in the
jca/jdo
directory of your Kodo installation
by setting
jndi-name
attribute to the JNDI name of your
choice. Then add <property>
elements
that correspond to the <config-property-name>
in ra.xml
to configure
connection info and other configuration elements. Now update
kodo-jdo.rar
to include
sun-ra.xml
in the
META-INF
virtual directory in the archive:
mkdir META-INF copy sun-ra.xml META-INF jar -uvf kodo-jdo.rar META-INF/sun-ra.xml
Browse to the web admin console of SunONE / Sun JES in your
browser. Select your server under App Server
Instances
and expand to
Applications/Connector Modules
.
Select Deploy
and upload your
new kodo-jdo.rar
file. Enter an
application name, and click the
Select
button. Apply your
changes by selecting the link in the top right.
Note | |
---|---|
Unfortunately, SunONE / Sun JES sometimes may not
accept its own configuration file format. If this is the
case, you will see exceptions as if your configuration
values had not been set at all. To bypass this problem,
extract |
If you have installed Kodo correctly, you should see
kodo-jdo
listed in the
Connector Module
.
You have now installed Kodo JDO JCA.
Kodo persistence services can be deployed in servlet containers
such as Apache Tomcat. The servlet or JSP based web applications running
within the container can then use JPA or JDO services via
javax.jdo.PersistenceManagerFactory
or
javax.persistence.EntityManagerFactory
. The application can
obtain reference to the factories using respective bootstrap methods
javax.jdo.JDOHelper.getPersistenceManagerFactory()
and
javax.persistence.Persistence.createEntityManagerFactory()
.
The following example code demonstrates how to access the JDO
PersistenceManagerFactory
and subsequently a PersistenceManager
:
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory("kodo.properties"); PersistenceManager pm = pmf.getPersistenceManager ();
The JDO configuration file name you specify must be available in the calling code's
classpath. For example, package the file in WEB-INF/classes/kodo.properties
of the web application archive.
The following code example demonstrates how to access the JPA EntityManagerFactory
and EntityManager
, where the JPA persistence unit configuration
file is packaged in WEB-INF/classes/META-INF/persistence.xml
and defines a persistence unit named "test":
EntityManagerFactory emf = Persistence.createEntityManagerFactory("test"); EntityManager em = emf.createEntityManager();
Web applications using Kodo can package Kodo libraries in the WEB-INF/lib
directory of a WAR file or they can share the libraries with other web applications
from a common location. To share the libraries, make them available to the common
classloader of Tomcat by editing the $CATALINA_HOME/conf/catalina.properties
file:
common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,%KODO_ROOT%/lib/*.jar
Note | |
---|---|
|
This makes all of the published Kodo libraries available to Tomcat, even though not all of the libraries are required.
To make only the required libraries available, you can include the
following jar files in the WEB-INF/lib
directory:
commons-collections-3.2.jar
commons-lang-2.1.jar
commons-pool-1.3.jar
jca1.0.jar
jdbc-hsql-1_8_0.jar
(if using HSQL database)
jdbc-mysql-3_0_14.jar
(if using MySQL database)
jdo.jar
(if using JDO)
jpa.jar
(if using JPA)
jta-spec1_0_1.jar
kodo-runtime.jar
OR kodo.jar
openjpa.jar
serp.jar
You may also include the above jars in the WEB-INF/lib
directory of a deployable Web Application Archive. However, this restricts Kodo's
availability to only the particular web application.
The samples/jdo/jsp
directory contains an example of JSP based web
application using Kodo JDO services to run a petshop. Use the following steps to run the
samples in Tomcat. These steps require Apache Tomcat/6.0.10 installed and the homepage
accessible at http://localhost:8080/
:
Edit $CATALINA_HOME/conf/catalina.properties
as follows (%KODO_ROOT%
is the Kodo installation directory):
common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,%KODO_ROOT%/lib/*.jar
Change directory to the Kodo installation directory.
Edit samples/jdo/jsp/petshop.properties
to configure database specific details.
Run the provided Ant script (samples/jdo/jsp
) to compile and package the application:
$ ant -f samples/jdo/jsp/build.xml
The Ant script creates a packaged web application named petshop.war
in the
samples/jdo/jsp/
directory.
To deploy petshop.war
in Tomcat, copy petshop.war
to
$CATALINA_HOME/webapps
or deploy it using the browser-based Tomcat Manager
(http://localhost/manager/html/
).
Once petshop.war
is deployed, go to http://localhost/petshop/
to create and view animals.
JRun requires a JRun-specific deployment file in addition to
the generic ra.xml
. Edit the
jrun-ra.xml
file provided in the
jca/jdo
directory of your Kodo installation
by setting
jndi-name
attribute to the JNDI name of your
choice. Then add <property>
elements
that correspond to the <config-property-name>
in ra.xml
to configure
connection info and other configuration elements. Now update
kodo-jdo.rar
to include
jrun-ra.xml
in the
META-INF
virtual directory in the archive:
mkdir META-INF copy jrun-ra.xml META-INF jar -uvf kodo-jdo.rar META-INF/jrun-ra.xml
Browse to the web admin console of JRun in your browser.
Select your server in the servers tree
and expand to J2EE Components
.
Under Resource Adapters
,
select Add
and upload your new
kodo-jdo.rar
file. The Kodo resource
adapter
will now be deployed to the JNDI name that you specified in
the jrun-ra.xml
file.
Note | |
---|---|
JRun does not provide any means of configuring a built-in
|
Note | |
---|---|
Borland includes two different
|
Due to classloader issues, as well as configuration of the RAR itself, some basic expertise in jar and unjarring is required to install Kodo into BES. Otherwise, we recommend deploying Kodo, then switching to single classpath for the entire system through the Admin tool (which prevents hot deploy) to ease classpath conflict issues. First extract kodo-jdo.rar to a temporary directory:
mkdir tmp cd tmp jar -xvf ../kodo-jdo.rar
From there, remove/move some jars that will cause class conflict
issues with either your application or BES.
Next, add the JDO specification API jars
and your JDBC driver jars into the system classpath
(e.g.
var/servers/your_server/partitions/lib/system
).
You must configure the RAR by editing the
ra-borland.xml
file included in
the jca/jdo
directory of your Kodo
installation. Move this file into the
META-INF
directory
of the expanded RAR file. Refer to the DTD and Borland's
documentation on advanced features of the deployment descriptor,
including deployment and security options.
With this completed, you can re-jar the expanded contents
into a new kodo-bes.rar
file to be deployed
using iastool or the console interface. Before deploying,
first enable Visiconnect on the
partition using the console or the command-line utilities.
This will activate JCA support in the application server.
Then restart BES so that Visiconnect can activate and
so that jdo.jar is added to the runtime classpath
the runtime classpath. When deploying, stubs and verification
do not need to be processed on the file and may simplify
the deployment process.
tmp> jar -cvf kodo-bes.rar *
After a restart, Kodo should now be deployed to BES. You should be able to find Kodo at the JNDI location of serial://kodo-jdo in your application as well as be visible in the JNDI viewer in the console. You have now installed Kodo JDO JCA.
Kodo can be deployed as a Java Connector Architecture (JCA) module or as shared application libraries. The sample user applications provided in the Kodo distribution demonstrate access patterns for both kinds of deployment.
The Kodo JCA Connector module for JDO is available in
jca/jdo/kodo-jdo.rar
. The
JCA Connector module is configured in
META-INF/ra.xml
in kodo-jdo.rar
archive file. The configuration file ra.xml
must be edited for your environment before it can be deployed.
Go to the %KODO_HOME%/jca/jdo
directory:
$ cd %KODO_HOME%/jca/jdo
Extract ra.xml
:
$ jar xvf kodo-jdo.jar META-INF/ra.xml
With a text or XML editor, edit META-INF/ra.xml
as follows:
Specify appropriate values for database connection
properties namely <ConnectionDriver>
,
<ConnectionURL>
,
<ConnectionUserName>
; and
<ConnectionPassword>
properties.
Specify <value>buildSchema</value>
for the <SynchronizeMappings>
property.
This setting ensures that Kodo will define the database
schema for the persistent classes.
The JCA Connector module will be bound to the JNDI tree of GlassFish.
The JNDI name for the JCA connector is specified in the
sun-ra.xml
file. The Kodo distribution provides the
jca/jdo/sun-ra.xml
file, which specifies the JNDI name
for JDO JCA Connector as kodo-jdo
.
You can edit sun-ra.xml
to specify a different name.
After making edits appropriate for your environment, update the
kodo-jdo.rar
archive with the edited
version of ra.xml
and sun-ra.xml
, as follows:
$ cp sun-ra.xml META-INF/sun-ra.xml
$ jar uvf kodo-jdo.rar META-INF
Copy the following application libraries from
%KODO_HOME%/lib
to %GLASSFISH%/lib
:
commons-collections-3.2.jar
commons-lang-2.1.jar
commons-pool-1.3.jar
jdo.jar
openjpa.jar
serp.jar
Start the GlassFish application server:
$ cd %GLASSFISH_HOME%/bin $ asadmin -start-domain domain1
Deploy the JCA Connector module:
$ asadmin deploy %KODO_HOME%/jca/jdo/kodo-jdo.rarOr, if you prefer, open the GlassFish Administration Console in a browser. If you are running Glassfish on your local machine with the default configuration, the Administration Console is available at
http://localhost:4848/
.
Activate Connector Modules > Deploy
and select the file
%KODO_HOME%/jca/jdo/kodo-jdo.rar
.
Deploying Kodo as a shared library in GlassFish allows all
applications to directly obtain a javax.jdo.PersistenceManagerFactory
or javax.persistence.EntityManagerFactory
via the
bootstrap class javax.jdo.JDOHelper or javax.persistence.Persistence
.
commons-collections-3.2.jar
commons-lang-2.1.jar
kodo-runtime.jar
kodo-api.jar
openjpa.jar
serp.jar
jdo.jar
jpa.jar
The Kodo distribution provides a set of samples to demonstrate usage within a J2EE Application Server. Some of the samples access Kodo persistence services by looking up JNDI for JCA Connector modules while others use the direct bootstrap API.
For both the JSP and EJB samples described below, perform the following step first:
Edit META-INF/jdo.properties
and
specify the appropriate values for these
database connection properties:
ConnectionDriverName
, ConnectionURL
,
ConnectionUserName
, and
ConnectionPassword
.
Make sure these values are consistent with the setting in
META-INF/ra.xml
in
jca/jdo/kodo-jdo.rar
.
This sample is available in the %KODO_HOME%/samples/jdo/jsp
directory. This sample uses Kodo JDO by directly creating a
javax.jdo.PersistenceManagerFactory
via the
javax.jdo.JDOHelper.get PersistenceManagerFactory()
method. Hence, you can run this sample while you deploy Kodo in the shared application
libraries of GlassFish.
The steps to run the sample are presented in the build.xml
Ant script.
Follow these instructions to run this sample:
Change to the %KODO_HOME%/samples/jdo/jsp
directory:
$ cd %KODO_HOME%/samples/jdo/jsp
Edit petshop.properties
to add
database connection properties.
The sample is configured for HSQL database, and a JDBC driver is provided in
%KODO_HOME%/lib
. Copy the HSQL driver to %GLASSFISH%/lib
.
If you are using any other database,
add the appropriate JDBC driver to %GLASSFISH%/lib
and edit the
path to the driver JAR file in <path id=compile.class.path>
in the build.xml
file.
Run ant:
$ ant
This script compiles the classes, enhances the persistent classes, defines
a database schema, and then packages the classes, JSP files, and configuration
files into a Web Application Archive named petshop.war
.
Deploy the web application in GlassFish:
$ cd %GLASSFISH%/bin $ asadmin deploy %KODO_HOME%/samples/jdo/jsp/petshop.war
You can browse the running application at
http://<server>:<port>/petshop/
This sample is available in %KODO_HOME%/samples/jdo/j2ee
.
It uses Kodo JDO by looking for the JDO JCA Connection module in JNDI.
The sample also demonstrates the use of EJB 2.0 Beans using persistent classes.
The steps to run the sample are presented in the build.xml
Ant script.
Follow these instructions to run this sample:
Deploy the JDO JCA Connector module. The sample is configured for
the HSQL database, and a JDBC driver is provided in
%KODO_HOME%/lib
. Copy the HSQL driver to
%GLASSFISH%/lib
. If you are using any other database,
add the appropriate JDBC driver to %GLASSFISH%/lib
.
Change to the %KODO_HOME%/samples/jdo/j2ee directory
.
If you deployed the JDO JCA Connector module with a name
other than kodo-jdo
by editing the corresponding
sun-ra.xml
file, then you must specify that name in
the pmf.jndi
property in
samples.properties
.
Compile the source files in place both in this base directory
and in the nested ejb
directory:
javac *.java ejb/*.java
Enhance the Car class.
kodoc -p jdo.properties package.jdo
Run the mapping tool; make sure that your META-INF/jdo.properties
file includes the same connection information (e.g. Driver, URL, etc.)
as your installation:
mappingtool -p jdo.properties package.jdo
Configure options in samples.properties to match your JCA
installation, most notably the JNDI name to which you have bound
Kodo (it defaults to kodo
).
Warning | |
---|---|
This step (editing samples.properties) is very important as this value can be quite different for each appserver and each configuration. Be sure that the setting you put for Refer to your JNDI tree and the documentation for your application server for further details. |
Build an J2EE application archive by running Ant against the build.xml
file.
This will create samplej2ee.ear
. This ear can now
be deployed to your application server.
ant -f build.xml
Deploy the enterprise application in GlassFish:
$ cd %GLASSFISH%/bin $ asadmin deploy %KODO_HOME%/samples/jdo/j2ee/samplej2ee.ear
You can browse the running application at
http://<server>:<port>/samples/
.
For application servers that do not support JCA as a means
of deploying resource adapters, Kodo can be deployed manually
by writing some code to configure and bind an instance of the
PersistenceManagerFactory
into JNDI.
The mechanism by which you do this is up to you and will be dependent on functionality that is specific to your application server. The most common way is to create a startup class according to your application server's documentation that will create a factory and then bind it in JNDI. For example, in WebLogic you could write a startup class as follows:
Example 8.1. Binding a Factory into JNDI via a WebLogic Startup Class
JPA:
import java.util.*; import javax.naming.*; import weblogic.common.T3ServicesDef; import weblogic.common.T3StartupDef; import weblogic.jndi.WLContext; /** * This startup class creates and binds an instance of a * Kodo EntityManagerFactory into JNDI. */ public class StartKodo implements T3StartupDef { private static final String EMF_JNDI_NAME = "my.jndi.name"; private T3ServicesDef services; public void setServices (T3ServicesDef services) { this.services = services; } public String startup (String name, Hashtable args) throws Exception { String jndi = (String) args.get ("jndiname"); if (jndi == null || jndi.length () == 0) jndi = PMF_JNDI_NAME; EntityManagerFactory factory = Persistence.createEntityManagerFactory ("name of entity manager in META-INF/persistence.xml"); Hashtable icprops = new Hashtable (); icprops.put (WLContext.REPLICATE_BINDINGS, "false"); InitialContext ic = new InitialContext (icprops); ic.bind (jndi, factory); // return a message for logging return "Bound EntityManagerFactory to " + jndi; } }
JDO:
import java.util.*; import javax.naming.*; import weblogic.common.T3ServicesDef; import weblogic.common.T3StartupDef; import weblogic.jndi.WLContext; /** * This startup class creates and binds an instance of a * Kodo PersistenceManagerFactory into JNDI. */ public class StartKodo implements T3StartupDef { private static final String PMF_JNDI_NAME = "my.jndi.name"; private static final String PMF_PROPERTY = "javax.jdo.PersistenceManagerFactoryClass"; private static final String PMF_CLASS_NAME = "kodo.jdo.PersistenceManagerFactoryImpl"; private T3ServicesDef services; public void setServices (T3ServicesDef services) { this.services = services; } public String startup (String name, Hashtable args) throws Exception { String jndi = (String) args.get ("jndiname"); if (jndi == null || jndi.length () == 0) jndi = PMF_JNDI_NAME; Properties props = new Properties (); props.setProperty (PMF_PROPERTY, PMF_CLASS_NAME); // you could set additional properties here; otherwise, the defaults // from kodo.properties will be used (if the file exists) PersistenceManagerFactory factory = JDOHelper. getPersistenceManagerFactory (props); Hashtable icprops = new Hashtable (); icprops.put (WLContext.REPLICATE_BINDINGS, "false"); InitialContext ic = new InitialContext (icprops); ic.bind (jndi, factory); // return a message for logging return "Bound PersistenceManagerFactory to " + jndi; } }
Applications that utilize Kodo can then obtain a handle to the factory as follows:
Example 8.2. Looking up the Factory in JNDI
JPA:
EntityManagerFactory factory = (EntityManagerFactory) PortableRemoteObject.narrow (EntityManagerFactory.class, new InitialContext ().lookup ("java:/MyKodoJNDIName")); EntityManager em = factory.getEntityManager ();
JDO:
PersistenceManagerFactory factory = (PersistenceManagerFactory) PortableRemoteObject.narrow (PersistenceManagerFactory.class, new InitialContext ().lookup ("java:/MyKodoJNDIName")); PersistenceManager pm = factory.getPersistenceManager ();