The Apache DB Project
ObJectRelationalBridge

OJB

Downloads

Documentation

Development

Translated (Web)

Getting Started with OJB
Introduction

This document is designed to help you get started with OJB for the first time. It is a cookbook type set of instructions designed to get you get OJB installed, and able to work on the other various tutorials.

This tutorial will:

  1. Install OJB
  2. Set up a database to test against
  3. Set up a basic project using OJB
  4. Configure a PostgreSQL database for use with OJB

This tutorial presumes you are comfortable configuring your relational database of choice, including adding databases and users, and configuring access controls at the database level (ie, you can create a database and user and give the user permission to access and change the database over a JDBC connection).

Setting Up the Database

We will look at setting up the database first as being able to run the unit tests is the best way to see if everything has built correctly.

This tutorial will speak to using PostgreSQL, however the steps are the same for configuring pretty much any database. OJB defaults to HSQLDB support -- so if you use HSQLDB your life is made a little bit easier. The tutorial will speak to PostgreSQL when a specific is required, however it will try to avoid going terribly database specific. OJB isn't supposed to work that way.

It is convenient to use the standard names that OJB likes to use for testing. So, create a database named OJB and a user with read/write access to that database named oleg. In PostgreSQL I prefer to name the database lower-case ojb as it makes the command line psql tools easier to use. Your mileage may vary. Make sure that your database is listening on a TCP/IP port (many PostgreSQL installs do not by default) as JDBC cannot use UNIX sockets, or whatever the Windows equivalent of that is.

Installing and Building OJB

Using the source installation provides a great deal of flexibility when working with OJB, and is the better path to take while learning the tool.

Download the most recent source distribution, or retrieve it from CVS and unpack it to a chosen directory. Building OJB will require retrieving several additional libraries which are not redistributable by Jakarta directly. These are specified in the deployment instructions. Retrieve the needed libraries and install them in lib/ directory. As mentioned, make sure to include the JDBC driver for the database you are using.

Now, run ant jar in your installation directory to build OJB. If you experience build errors that a class is not found, you have missed a required library. Check again to make sure you have downloaded and added the needed jars to the lib/ directory. The package name of the missing class should give you a good clue as to what library you need.

Accessing Your Database

Now that you know you can build the actual OJB library, lets make sure it works with your database.

Edit the build.properties file and uncomment the line for the database you are using. For this example we will use PostgreSQL, so we will uncomment the linefor PostgreSQL: profile=postgresql and comment the line for HSQL: #profile=hsqldb. You will uncomment the profile you need for your specific database.

Look for your database's entry in the profiles/ directory, postgresql.profile for our PostgreSQL example, and open it in your text editor. Make any needed changes (such as specifying a password if you have your database set to require one) to the configuration and save the profile.

Now that the raw information needed to access your database is entered, go back to the installation directory for OJB and run ant junit and sit back. This will construct all of the needed tables for OJB, as well as tables for unit testing OJB. It will then happily run all of the various unit tests for you.

Assuming the build succeeded, take a look at your database and look at the various tables. Pay particular note to the system tables described in the platforms documentation. You will need these tables in the database for your application as well.

Your Project
Preparing the Database

Once again we will begin by preparing the database. One option is to change the database profile to point directly at your project database and run the ant task to build the database. While this will generated the needed OJB tables, it will also clutter your database with a score or so ugly unit test tables.

Assuming you tested against the same type of database you intend to run against, the DDL for the required tables already exists, though. You can use this DDL to generate the OJB tables in your database. The core tables required by OJB will have their DDL in the target/src/sql/ojbcore-schema.sql sql script. You can use it directly to generate the required tables in your project's database.

OJB uses Torque to generate the JUnit tables. An excellent way to generate the OJB tables, instead of using the DDL generated for the tests, is to generate your schema via Torque as well, and include the schema definitions from the JUnit tests in your schema definition. This is, however, beyond the scope of this tutorial. Torque does have an excellent set of tutorials that can make this task very simple though. The schema definition for OJB is in the src/schema/ojbcore-schema.xml file. Just drop this file into your own Torque schema directory and you are good to go, the OJB schema will be built right alongside your own.

OJB Deployment

Detailed deployment information is available in the deployment documentation, including examples of deployment to various J2EE containers. This tutorial merely steps through the minimum to get a project up and running in a freestanding applications.

OJB requires a number of configuration files to function correctly. All of these configuration files can be loaded directly off of the classpath, however so you just need ot get the onto your runtime classpath.

The required files are:

  • OJB.properties
  • repository*.xml
It is easiest to just copy the files from the test run to your project and edit them to your needs. The test files can be found in the target/test/ojb/ directory. Copy these to a place directly on your classpath - or better, to a place where your build process can copy them to your runtime classpath.

Open up the repository.xml file. It is basically a skeleton that includes the other repository-*.xml files. The default layout works fairly well - use repository-user.xml for your mappings, repository-database.xml for the database connection information, etc. You can safely comment out or remove the junit, jdo, and ejb sections however for this. If you intend to use that functionality yourself, go ahead and add it back in after you have a stronger understanding of what it does. For now, we just need the core functionality. make sure to leave the internal reference in - it contains the mappings for OJB's internally used tables.

In addition to the configuration information, you will need the ojb jar library, and its required libraries. An up to date list of these is kept on the Deployment page. Copy these jar files to your runtime classpath as well as the db-ojb-*.jar.

You are now ready to begin using OJB!


Copyright © 1999-2003, Apache Software Foundation