2011/01/16 - Apache ObJectRelationalBridge has been retired.

Sample project

For our sample project, we should rename the directory to something more fitting, like productmanager.

Also, since we're using MySQL, we put the MySQL jar of the jdbc driver, which is called something like mysql-connector-java-[version]-stable-bin.jar, into the lib subdirectory.

The only other thing missing is the source code, but since that's what the other tutorials are dealing with, we will silently assume that it is already present in the src/java subdirectory.
If you don't want to write the code yourself, you can use the code from one of the tutorials which you can download here.

Configuration via build.properties

The next step is to adapt the build files, especially the build.properties file to your environment. It basically contains two sets of information, the database settings and the build configuration. While you shouldn't have to change the latter, the database settings probably need to be adapted to suit your needs:

If you know how the jdbc url for connecting to your database looks like, then you can derive the settings databaseName, databaseName, databaseName and databaseName easily:
Assume this url is given as:

jdbc:mysql://localhost:3306/myDatabase

then these properties are

Building via build.xml

After setting up the build you're probably eager to actually build the project. Here's the actions that you can perform using the Ant build file build.xml:

So, a typical build would be achieved with this Ant call:

ant build

If you want to create the database as well, and you have javadoc comments in your source code that describe the repository, then you would call Ant this way:

ant build setup-db

This will perform in that order the actions build, xdoclet (invoked automatically from the next action) and setup-db.
Of course, you do not need to use Torque to setup your database, but it is a convenient way to do so.

Sample project

First we change the database properties to these values (assuming that Torque will be used to setup the database):

Ok, now we have everything configured for building. The build.properties file now looks like this (the comments have been removed for brevity):

jcdAlias=default
databaseName=productmanager
databaseUser=steve
databasePassword=secret

dbmsName=MySQL
jdbcLevel=3.0
jdbcRuntimeDriver=com.mysql.jdbc.Driver
urlProtocol=jdbc
urlSubprotocol=mysql
urlDbalias=//localhost/${databaseName}

torque.database=mysql
torque.database.createUrl=${urlProtocol}:${urlSubprotocol}://localhost/

jar.name=projectmanager.jar

source.dir=src
source.java.dir=${source.dir}/java
source.resource.dir=${source.dir}/resources
source.test.dir=${source.dir}/test
source.schema.dir=${source.dir}/schema

build.dir=build
build.lib.dir=lib
build.classes.dir=${build.dir}/classes/
build.resource.dir=${build.dir}/resources/

target.dir=target

Looks like we're ready for building. Again, we're assuming that the source code is already present. So we're invoking Ant now in the top-level folder productmanager:

ant build setup-db

which should (assuming five java classes) produce an output like this

Buildfile: build.xml

compile:
    [mkdir] Created dir: /home/steve/projects/productmanager/build
    [mkdir] Created dir: /home/steve/projects/productmanager/build/classes
    [javac] Compiling 5 source files to /home/steve/projects/productmanager/build/classes

build:
     [copy] Copying 10 files to /home/steve/projects/productmanager/build/resources

xdoclet:
[ojbdoclet] (XDocletMain.start                   47  ) Running <ojbrepository/>
[ojbdoclet] Generating ojb repository descriptor (build/resources//repository_user.xml)
[ojbdoclet] Type test.Project
[ojbdoclet] Processed 5 types
[ojbdoclet] Processed 5 types
[ojbdoclet] (XDocletMain.start                   47  ) Running <torqueschema/>
[ojbdoclet] Generating torque schema (build/resources//project-schema.xml)
[ojbdoclet] Processed 5 types

setup-db:

check-use-classpath:

check-run-only-on-schema-change:

sql-check:

sql:
     [echo] +------------------------------------------+
     [echo] |                                          |
     [echo] | Generating SQL for YOUR Torque project!  |
     [echo] | Woo hoo!                                 |
     [echo] |                                          |
     [echo] +------------------------------------------+

sql-classpath:
[torque-sql] Using contextProperties file:
             /home/steve/projects/productmanager/build.properties
[torque-sql] Using classpath
[torque-sql] Generating to file
             /home/steve/projects/productmanager/build/resources/report.productmanager.sql.generation
[torque-sql] Parsing file: 'ojbcore-schema.xml'
[torque-sql] (transform.DTDResolver               128 ) Resolver: used database.dtd from
             org.apache.torque.engine.database.transform package
[torque-sql] Parsing file: 'project-schema.xml'
[torque-sql] (transform.DTDResolver               140 ) Resolver: used
             http://jakarta.apache.org/turbine/dtd/database.dtd

sql-template:

create-db-check:

create-db:
[torque-data-model] Using classpath
[torque-data-model] Generating to file
                    /home/steve/projects/productmanager/build/resources/create-db.sql
[torque-data-model] Parsing file: 'ojbcore-schema.xml'
[torque-data-model] (transform.DTDResolver               128 ) Resolver: used database.dtd from
                    org.apache.torque.engine.database.transform package
[torque-data-model] Parsing file: 'project-schema.xml'
[torque-data-model] (transform.DTDResolver               140 ) Resolver: used
                    http://jakarta.apache.org/turbine/dtd/database.dtd
     [echo]
     [echo]       Executing the create-db.sql script ...
     [echo]
      [sql] Executing file:
            /home/steve/projects/productmanager/build/resources/create-db.sql
      [sql] 2 of 2 SQL statements executed successfully

insert-sql:
[torque-sql-exec] Our new url -> jdbc:mysql://localhost/productmanager
[torque-sql-exec] Executing file:
                  /home/steve/projects/productmanager/build/resources/project-schema.sql
[torque-sql-exec] Executing file:
                  /home/steve/projects/productmanager/build/resources/ojbcore-schema.sql
[torque-sql-exec] 50 of 50 SQL statements executed successfully

BUILD SUCCESSFUL

That was it. You now have your database setup properly. Go on, have a look:

mysql -u steve productmanager

mysql> show tables;

There, all tables for your project, as well as the tables required for some OJB functionality which we also used in the above process (you can recognize them by their names which start with ojb_).

Configuring the OJB runtime

With the OJB.properties file and OJB-logging.properties (both located in src/resources), you configure and finetune the runtime aspects of OJB. For a simple application you'll probably won't have to change anything in them, though.

Configuring the database connection

For projects that use OJB, you configure the connections to the database via jdbc connection descriptors. These are usually defined in a file called repository_database.xml (located in src/resources). In the ojb-blank project, the build file will setup this file for you and place it in the build/resources directory.

Configuring the repository

Finally you need to configure the repository. It consists of descriptors that define which java classes are mapped in what way to which database tables, and it is typically contained in the repository_user.xml file. This is the most complicated configuration part which will be explained in much more detail in the rest of the tutorials.
An convenient way of creating the repository metadata is to use the XDoclet OJB module. Basically, you put specific Javadoc comments into your source code, which are then processed by the build file (xdoclet and setup-db targets) and the repository metadata and the database schema are generated.

Sample project

Actually, there is not much to do here. For our simple sample application the default properties of OJB work just fine, so we leave OJB.properties and OJB-logging.properties untouched.

Also, the build file generated the connection descriptor for us, and we were using the XDoclet OJB module and Torque to generate the repository metadata and database for us. For instance, the processed connection descriptor (file build/resources/repository_database.xml) looks like this:

<jdbc-connection-descriptor
    jcd-alias="default"
    default-connection="true"
    platform="MySQL"
    jdbc-level="3.0"
    driver="com.mysql.jdbc.Driver"
    protocol="jdbc"
    subprotocol="mysql"
    dbalias="//localhost/productmanager"
    username="steve"
    password="secret"
    eager-release="false"
    batch-mode="false"
    useAutoCommit="1"
    ignoreAutoCommitExceptions="false"
>
    <object-cache class="org.apache.ojb.broker.cache.ObjectCacheDefaultImpl">
        <attribute attribute-name="timeout" attribute-value="900"/>
        <attribute attribute-name="autoSync" attribute-value="true"/>
    </object-cache>
    <connection-pool
        maxActive="21"
        validationQuery="" />
    <sequence-manager className="org.apache.ojb.broker.util.sequence.SequenceManagerHighLowImpl">
        <attribute attribute-name="grabSize" attribute-value="20"/>
        <attribute attribute-name="autoNaming" attribute-value="true"/>
        <attribute attribute-name="globalSequenceId" attribute-value="false"/>
        <attribute attribute-name="globalSequenceStart" attribute-value="10000"/>
    </sequence-manager>
</jdbc-connection-descriptor>

If you're curious as to what this stuff means, check this reference guide.

The repository metadata (file build/resources/repository_user.xml) starts like:

<class-descriptor
    class="productmanager.Product"
    table="Product"
>
    <field-descriptor
        name="name"
        column="name"
        jdbc-type="VARCHAR"
        length="32"
    >
    </field-descriptor>
    <field-descriptor
        name="price"
        column="price"
        jdbc-type="FLOAT"
    >
    </field-descriptor>
    <field-descriptor
        name="stock"
        column="stock"
        jdbc-type="INTEGER"
    >
    </field-descriptor>
    <field-descriptor
        name="id"
        column="id"
        jdbc-type="INTEGER"
        primarykey="true"
    >
    </field-descriptor>
</class-descriptor>
...

Now you should be able to run your application:

cd build/resources

java productmanager.Main

Of course, you'll need to setup the CLASSPATH before running your application. You'll should add all jars from the lib folder except the ones for Torque (torque-[version].jar, velocity-[version].jar and commons-collections-[version].jar) and for the XDoclet OJB module (xdoclet-[version].jar, xjavadoc-[version].jar and xdoclet-ojb-module-[version].jar).

It is important to note that OJB per default assumes the OJB.properties and OJB-logging.properties files in the directory where you're starting the application. Hence, we changed to the build/resources directory before running the application. This of course requires the compiled classes to be on the classpath, as well (directory build/classes).

Per default, the same applies to the other configuration files (repository*.xml) but you can change this in the OJB.properties file.