OJB
Downloads
Documentation
Development
Translated (Web)
|
how to use OJB with a specific relational database |
OJB has been designed to smoothly integrate with any relational
database that provides JDBC support. OJB can be configured to use only JDBC 1.0 API calls
to avoid problems with restrictions of several JDBC drivers. It
uses a limited SQL subset to avoid problems with restrictions of
certain RDBMS. This design allows to keep the OJB code generic and
free from database specifics.
This document explains basic concepts and shows how OJB can be
configured to run against a specific RDBMS.
|
basic concepts |
OJB internal tables |
For certain features OJB relies on several internal tables that must be present in the
target rdbms to allow a proper functioning.
If those features are not needed OJB can be safely run without any internal tables.
The following table
lists all tables and their specific purpose.
Tablename |
Purpose |
OJB_HL_SEQ
|
Table for the high/low sequence manager.
If the built-in OJB sequence manager is not used, this table is not needed.
|
OJB_LOCKENTRY
|
This table is used to store Object locks if the LockManager is
run in distributed mode. Not needed in singlevm mode.
|
OJB_NRM
|
The "Named Roots Map". ODMG allows to bind
persistent objects to an user defined name. The Named roots
map is used to store these bindings. It has NAME (String of
arbitrary length) as primary key and keeps the serialized OID of
the persistent object in the field OID (String of arbitrary
length).
If bind() and lookup() are not used in client apps, this table is not needed
|
OJB_DLIST
|
The table used for the ODMG persistent DList collections.
If ODMG DLists are not used, this table is not needed.
|
OJB_DLIST_ENTRIES
|
stores the entries of DLists (a wrapper to objects stored in
the DList)
If ODMG DLists are not used, this table is not needed.
|
OJB_DSET
|
The table used to store ODMG persistent DSET collections
If ODMG DSets are not used, this table is not needed.
|
OJB_DSET_ENTRIES
|
This table stores the entries of DSets.
If ODMG DSets are not used, this table is not needed.
|
OJB_DMAP
|
The table use to store the ODMG persistent DMap tables
If ODMG DMaps are not used, this table is not needed.
|
OJB_DMAP_ENTRIES
|
The table containing the DMap entries. The Keys and Values of
the map can be arbitrary persistent objects.
If ODMG DMaps are not used, this table is not needed.
|
OJB uses Torque
to create all required tables and data.
Thus there is no SQL DDL file, but an XML file describing the
tables in format readable by Torque.
The Torque DDL information for the internal tables resides in the
file src/schema/ojbcore-schema.xml .
The o/r mappings for these tables are contained in the file
repository_internal.xml .
|
tables for the regression testbed |
It is recommended to run the OJB JUnit regression tests
against your target database.
Thus you will have to provide several more tables, filled with the proper
testdata.
The DDL information for these tables resides in the
file src/schema/ojbtest-schema.xml .
The testdata is defined in the
file src/schema/ojbtest-data.xml .
The o/r mappings for these tables are contained in the file
repository_junit.xml .
|
tables for the tutorial applications |
If you intend to run the OJB tutorial applications
against your target database
you will have to provide one extra table.
The DDL information for this table also resides in the
file src/schema/ojbtest-schema.xml .
The testdata is also defined in the
file src/schema/ojbtest-data.xml .
The o/r mappings for this table is contained in the file
repository_user.xml .
|
|
the setup process |
OJB provides a setup routine to generate the target database and to fill it
with the required testdata.
This routine is based on Torque scripts and is driven from the build.xml file.
This section describes how to use it.
executing the build script |
Now everything should be prepared to launch the setup routine.
This routine can be invoked by calling
build[.sh] prepare-testdb .
If you are prompted with a BUILD SUCCESSFUL message after
some time, everything is OK.
If you are prompted with a BUILD FAILED message after
some time, something went wrong.
This may have several reasons:
-
You entered some incorrect settings. Please check the
log messages to see what went wrong.
-
Torque does not work properly against your target database.
Torque is very flexible and should be able to work against
a wide range of databases. But the code templates for each
database may not be accurate.
Please check the ojb-user mailinglist archive if there are
any failure reports for your specific database.
Please also check if some contributed a fix already.
If you don't find anything please post your problem to the ojb user-list.
As a last resort you can try the following:
Switch back to the default hsqldb profile and execute build[.sh] prepare-testdb
This will setup the default hsqldb database.
And it will also generate SQL scripts that you may use to generate your
database manually.
The SQL scripts are generated to jakarta-ojb-xxx/target/src/sql .
You can touch these scripts to match your database specifics and
execute them manually against your platform.
|
verifying the installation |
Now everything is setup to run the junit regression tests against
your target database.
Execute build[.sh] junit to see if everything works as expected.
If you did not manage to set up the target database with the
build[.sh] prepare-testdb you can use
build[.sh] junit-no-compile-no-prepare to
run the testsuite without generation of the test database.
After running the regression tests
you should see a console output as follows:
 |  |  |
 |
...
junit-no-compile-no-prepare:
[junit] Running org.apache.ojb.broker.AllTests
[junit] Tests run: 99, Failures: 0, Errors: 0,
Time elapsed: 8,337 sec
[junit] Running org.apache.ojb.odmg.AllTests
[junit] [BOOT] INFO: OJB.properties: file:
/home/tom/workspace/jakarta-ojb/target/test/ojb/OJB.properties
[junit] Tests run: 118, Failures: 0, Errors: 0,
Time elapsed: 12,506 sec
[junit] Running org.apache.ojb.soda.AllTests
[junit] [BOOT] INFO: OJB.properties: file:
/home/tom/workspace/jakarta-ojb/target/test/ojb/OJB.properties
[junit] Tests run: 3, Failures: 0, Errors: 0,
Time elapsed: 6,391 sec
...
BUILD SUCESSFUL
|  |
 |  |  |
If the Junit tests report errors or failures something does not
work properly! There may be several reasons:
-
There may be bugs in OJB! we aim at shipping releases that
have no failures and errors in the regression tests!
But in certain circumstances it may be neccessary to ship
intermediary releases that have failing junit tests.
This will be mentioned in the todo.html file.
If you get exactly the same number of junit failures as mentioned
in this file there are no special problems with your platform.
-
If the release has no junit failures listed in todo.html or if
you get more errors than mentioned in todo.html there seem to
be problems with your platform.
In such a case please check again if you followed all the above
steps. If you still have problems you might post a request to
the OJB user mailinglist.
|
|
|