Table of Contents
This appendix details the procedure for setting up a relational database store for the Hibernate back-end.
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:
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:
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:
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.
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