2.4 Deploying and Running

2.4.1 Editing the Deployment Descriptor

repository.xml is the OJB deployment descriptor. Its purpose is
very much like that of the ejb-jar.xml descriptor. OJB comes with a sample
repository.xml file that you can modify for your application. You
should copy the following files to your project directory:
repository.xml, repository_internal.xml,
repository.dtd, and OJB.properties.

The sample repository.xml file includes two XML fragments (external
entities), repository_internal.xml and
repository_user.xml. You have already copied
repository_internal.xml to your project directory. What about
repository_user.xml? It is the OJB descriptor fragment we have
covered in the previous sections. You need to create a file called
repository_user.xml and put the mapping details inside. All three
XML files and fragments must be in your application's classpath.

2.4.2 Setup OJB Internal Tables

Before we can run our applications, we must set up the OJB internal tables.
This step is done once and is relatively painless. The steps below should be
helpful. (Assume OJB_HOME points to where you've unzipped the OJB
distribution.)

Modify OJB_HOME/build.properties. At the beginning of
the file, uncomment the appropriate database you are planning to use. If you plan
to use Hypersonic database, that part of the properties file should look like this:

In the OJB_HOME/profile directory, modify the
corresponding database profile file. For the Hypersonic database, the file is
called hsqldb.profile. In general, you only need to make sure that
all of the database URLs are correct. In the case of Hypersonic, the file should be:

(Note: The createDatabaseUrl, buildDatabaseUrl, and databaseUrlvariables are all incorrect in the OJB 0.9.7 distribution. Make sure the URLs are right after string substitutions are done.)

If you have Ant installed, you can simply invoke ant
prepare-testdb. Otherwise, OJB_HOME/bin contains both
build.sh and build.bat scripts that invoke Ant,
distributed with the OJB package. (If you are not using Hypersonic, make sure
your JDBC driver is in the classpath or that the .jar file is copied over to
the OJB_HOME/lib directory.)

You should see "BUILD SUCCESSFUL" at the end. Otherwise,
check your database profile and the on-screen log messages.

2.4.3 The Test Application

JUnit is a good way to test your application and verify settings. This test
application shows the OJB classes we use to persist and query objects. They are
PersistenceBroker, Criteria, and Query. To run the application, you should have
the OJB distribution .jar files in your CLASSPATH. In addition, the
OJB.properties file and OJB XML descriptor files should also be in
the CLASSPATH.

That's it. With only a few lines of extra code, your business objects can be
made persistent without having to be remodeled to entity beans.

3. Conclusion

Free and robust persistence frameworks are available today. They have good
object-relational mapping capabilities, so that developers can work on the
object models that are most natural for the business requirements. Given the complexities
of today's business applications, the capabilities provided by these frameworks
should not be overlooked.

4. Appendix

It is often desirable to decouple your application from the specifics of a
persistence framework, so that you can easily switch frameworks in the future. I
recommend creating custom PersistenceManager and Transaction
classes for this purpose. For example: