Appendix A. Installing The Hibernate Back-End

Table of Contents

Installing The Database Schema
Alternate Installation Procedure (Using Ant)
Testing the Hibernate Backend
Limitations Of The Hibernate Backend

This appendix details the procedure for setting up a relational database store for the Hibernate back-end.

Installing The Database Schema

The Hibernate TopicMapProvider connects to a single database and expects that database to have already been initialised with tables defined by a schema generated by the Hibernate O-R tool. Within a single database, the Hibernate TopicMapProvider can support multiple topic maps, so in most cases, it should only ever be necessary to create one such database. It is strongly recommended that these tables be created in their own database and that you do not add new tables to the database subsequently. In addition, it should go without saying that if you modify the schema of one or more tables installed by the Hibernate back-end, you can expect that things will probably go wrong!

The installation of the database schema is currently supported by a simple command-line application. The application is invoked as follows:

java org.tm4j.topicmap.hibernate.InstallDB {-d hibernate dialect} {-c JDBC driver class name} {-u JDBC database URL} [username password]

Where:

hibernate dialect
The Hibernate Dialect class for the specific database implementation you are connecting to. This should be the full class name of the dialect. The dialect class names are listed in Table 3.6, “Databases supported by the Hibernate Back-end”.
JDBC driver class name
The full Java class name of the JDBC driver to be used to connect to the database. The class must be present on the CLASSPATH (either in a JAR listed in the CLASSPATH or as a .class file in a directory listed in the CLASSPATH) at the time you invoke this application.

Note

Some JDBC drivers (e.g. older Oracle JDBC drivers) are packaged as a .zip file rather than a JAR. In this case you have three options:

  • Unzip the driver files to a directory and add that directory to the CLASSPATH environment variable.
  • Unzip the driver files to a directory and then create a JAR file of the unzipped classes and add that JAR file to the CLASSPATH.
  • Unzip the driver files to a directory, create a JAR file of the unzipped classes and add that JAR file to the lib subdirectory of your TM4J installation.
JDBC database URL
The JDBC connection URL for the database. The format of this URL will depend upon the JDBC driver you are using for the database connection.
username and password
The database user name and password for the connection. If ommitted, the application will attempt to connect to the database without supplying a user name and password.

If successful, you will see the message:

Database schema was installed successfully!

Otherwise, check the error messages for details of what went wrong. The most likely causes of error are as follows:

  1. Incorrect dialect class name specified - check the spelling and that you have specified the full Java class name
  2. Incorrect JDBC driver class name specified - check the spelling and that you have specified the full Java class name.
  3. JDBC driver class is not found on the CLASSPATH - check the the JAR containint the driver is specified in the -cp parameter used to invoke the application or in the CLASSPATH environment variable.
  4. Connection refused by the database - either the username/password combination you supplied was not correct; or the database has not been configured to allow you access; or you failed to specify a username/password combination when one was required for connection.

Note

When the installation application is run, it first attempts to drop any previously existing tables which have the same name as the tables to be created. If you see output like Unsuccessful: General error: Unknown table 'locators' and you are installing into a fresh database, there is nothing to worry about.

Alternate Installation Procedure (Using Ant)

The build.xml file that ships with the source distribution of TM4J provides a target which will invoke the database schema installation program automatically. To make use of this target, you must first create a file called build.properties in the root directory of the TM4J distribution (i.e. in the same directory as build.xml). This file must contain the following property definitions:

hibernate.dialect={class name of the Hibernate database dialect to use}
hibernate.connection.driver_class={class name of the JDBC driver to use}
hibernate.connection.url={JDBC connection URL of the database to access}
hibernate.connection.username={username for connection}
hibernate.connection.password={password for connection}
	  

The JDBC driver you are using must be contained in a JAR file contained in the lib directory of the TM4J distribution you are using.

Once you have created the build.properties file, and installed the JDBC driver in the lib directory, you can then initialise the database by invoking the hibernate-initdb target with the following command:bin/ant hibernate-initdb