ObJectBridge
BRIDGING JAVA OBJECTS AND RELATIONAL DATABASES

ObJectRelationalBridge Deployment

How to deploy OJB in your applications

Author: Thomas Mahler, march 2002

Introduction

This document describes how to deploy OJB in different application environments.

things needed for deploying OJB

This section enumerates all things needed to deploy OJB.

the ojb binary jar archive

Currently there is no binary distribution for OJB. The binaries have to be build from the source distribution. By calling build[.sh] jar you can assemble the binary jar archive.
The archive is named ojb-<version>.jar and placed in the dist directory.
This jar files contains all OJB code neccessary in production level environments. It does not contain any test code. It also does not contain any configuration data.

configuration data

OJB needs two kinds of configuration data:

  1. configuration of the OJB runtime environment. This data is stored in a file named OJB.properties. Learn more about this file here.

  2. Configuration of the MetaData layer. This data is stored in file named repository.xml (and several included files). Learn more about this file here.

These configuration files are read in through ClassLoader resource lookup and must therefore be placed on the classpath.

additional jar archives

OJB needs several jar archives during runtime. These jar files are shipped in the lib directory. The following table lists these archives.

Archive name

What does it contain ?

Required at runtime ?

ant.jar

The ANT build environment

No

antlr.debug.jar

The ANTLR Parser runtime (with debug infos)

required for debugging in some Java IDEs

antlr.jar

The ANTLR Parser runtime

Yes

antlr_compiletime.jar

The ANTLR Parser generator. Used to build Parser source code during build process.

No

crimson.jar

The Crimson XML parser

Yes (if no other parser is used)

ejb.jar

The javax.ejb Standard extension for EJB

No

gnu-regexp-1.1.4.jar

The GNU regular expression tools. Needed only in the mapping tools.

No

hsqldb.jar

The Hypersonic SQL Database

Only if the Application is running against Hypersonic

jdbc2_0-stdext.jar

The javax.sql standard extension for SQL

Yes

jta-spec1_0_1.jar

The javax.transaction standard extension for Transaction integration

Yes

junit.jar

The JUnit Unit testing framework

No

log4j.jar

The LOG4J logging framework

Only if OJB is configured to use LOG4J logging

proxy.jar

The Developmentor JDK1.2 emulation of JDK1.3 dynamic proxies

Only if running in a JRE1.2 environment

servlet.jar

The javax.servlet standard extension for Servlets.

No



Important note: The repository.xml defines JDBC Connections to your runtime databases. To use the declared JDBC drivers the respective jar archives must also be present in the classpath. Refer to the documentation of your databases.


deployment in standalone applications

Deploying OJB for standalone applications is most simple. If you follow these four steps your application will be up in a few minutes.

  1. Add ojb-<version>.jar to the classpath

  2. place OJB.properties and repository.xml files on the classpath

  3. Add additional runtime jar archives to the classpath. Typically you will need antlr.jar, crimson.jar, jdbc2_0-stdext.jar, jta-spec1_0_1.jar and log4j.jar.

  4. Add your JDBC drivers jar archive to the classpath.

deployment in servlet based applications

Generally speaking the four steps described in the previous section have to be followed also in Servlet / JSP based environments.
In this section I describe the procedure for the popular servlet engine TOMCAT (http://jakarta.apache.org/tomcat). The exact details may differ for your specific Servlet container, but the general concepts should be quite similar.

Tomcat 3.3.x

Tomcat 3.3 has a directory lib/apps for application specific jar archives.

  1. Add ojb-<version>.jar to lib/apps

  2. Add additional runtime jar archives to lib/apps. Typically you will need antlr.jar, crimson.jar, jdbc2_0-stdext.jar, jta-spec1_0_1.jar and log4j.jar.

  3. Add your JDBC drivers jar archive to lib/apps.

  4. Deploy OJB.properties and repository.xml with your servlet applications WAR file.
    The WAR format specifies that Servlet classes are to be placed in a directory WEB-INF/classes. The OJB configuration files have to be in this directory as tomcat adds it to the classpath.
    By executing build[.sh] war you can generate a sample servlet application assembled to a valid WAR file. The resulting ojb-servlet.war file is written to the dist directory. You deploy this WAR file to your tomcat servlet engine or unzip it to have a look at its directory structure.

Tomcat 4.0.x (aka Catalina)

Tomcat 4.0 wants you to place application specific jar archives in the lib directory directly. The deployment thus works like follows:

  1. Add ojb-<version>.jar to lib.

  2. Add additional runtime jar archives to lib. Typically you will only need antlr.jar, and log4j.jar.

  3. Add your JDBC drivers jar archive to lib.

  4. Deploy OJB.properties and repository.xml with your servlet applications WAR file.
    The WAR format specifies that Servlet classes are to be placed in a directory WEB-INF/classes. The OJB configuration files have to be in this directory as tomcat adds it to the classpath.
    By executing build[.sh] war you can generate a sample servlet application assembled to a valid WAR file. The resulting ojb-servlet.war file is written to the dist directory. You deploy this WAR file to your tomcat servlet engine or unzip it to have a look at its directory structure.

deployment in EJB based applications

I'm planning to provide a description for the JBOSS J2EE server here.

For the time beeing you should apply the general ideas of the four steps mentioned above to setup your environment.



$FOOTER$