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:
- Install OJB
- Set up a database to test against
- Set up a basic project using OJB
- 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!
|
|
|