Dear diary,

I have spent far too much time trying to install the hibernate backend for tm4j (or tmnav, to be precise), so let me tell you how it is done. :)

Remember, I do this for Win2k. After facing some performance problems with the ozone backend, I decided to go with MySQL.

I went to http://dev.mysql.com/downloads/mysql/4.0.html to get the Windows binaries, and downloaded the plain Windows installer binaries. I got a zip-file, unpacked it and hit setup, following the default settings (even though that means installing in C:\mysql). If I remember correctly, I did not go for the service, I prefer to start and stop the server myself.

After the installer exits, take a look at the very detailed documentation, and you might want to take care of the passwords first. There are two accounts, an anonymous and the "root"-account, both have no passwords - change that.

To do so, start the server as described in file:///C:/mysql/Docs/manual.html#Windows_server_first_start

Then, open another command window and start the client as described in file:///C:/mysql/Docs/manual_toc.html#Windows_running

The concepts of user accounts, default accounts and passwords are described in file:///C:/mysql/Docs/manual_toc.html#Default_privileges

In short, the following boils it down:

shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');

where 'newpwd' should be replaced with what your new password is, like in PASSWORD('foo').

Then, for the anonymous account, do like this:

shell> mysql -u root
mysql> DELETE FROM mysql.user WHERE Host='localhost' AND User='';
mysql> FLUSH PRIVILEGES;

After going through the post installation procedures explained in file:///C:/mysql/Docs/manual.html#Windows_post-installation (if you feel like it), we should add a new user, let us call it "tm4j". How this is done is explained here: file:///C:/mysql/Docs/manual_toc.html#Adding_users where it says:

----------------
shell> mysql --user=root mysql

If you have assigned a password to the root account, you'll also need to supply a --password or -p option for this mysql command and also for those later in this section.
----------------

so, we would do as follows:
----------------
mysql> GRANT ALL PRIVILEGES ON *.* TO 'tm4j'@'localhost'
    ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'tm4j'@'%'
    ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
----------------

This not only creates the user, but also takes care of the access rights.

Finally, we have to set up a new database, into which the provider can put the topicmaps - let's call it "tm4j" as well... :)

Creating databases is described in detail here: file:///C:/mysql/Docs/manual.html#Database_use

We will do the following:

mysql> CREATE DATABASE tm4j;

That's about it for now with MySQL. Now, let's take care of ant, which eases things a lot... :) Go to http://ant.apache.org/bindownload.cgi and choose an appropriate mirror, I then downloaded apache-ant-1.6.2-bin.zip. This zip can be extracted to your favourite directory (c:\ant ?) - that's about it. The following is also described here: http://ant.apache.org/manual/index.html - http://ant.apache.org/manual/install.html#installing

    * Add the bin directory to your path.
    * Set the ANT_HOME environment variable to the directory where you installed Ant. On some operating systems the ant wrapper scripts can guess ANT_HOME (Unix dialects and Windows NT/2000) - but it is better to not rely on this behavior.
    * Optionally, set the JAVA_HOME environment variable (see the Advanced section below). This should be set to the directory where your JDK is installed.

On windows, this boils down to the following:

set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin

(At the time of writing this doc, the java version should look more like j2sdk1.4.2_03 or newer. If it is not newer than 1.4.2, go to http://java.sun.com/ and look for a link which will take you to the current J2SE SDK [Software Development Kit] and install that - you will need it...).

To verify if your JAVA_HOME is set correctly, you can do the following:

- either go to somewhere where you are sure that you don't have a java.exe hanging around, and type "java" without the "", and then get something like the following:

C:\>java
Usage: java [-options] class [args...]
           (to execute a class)
   or  java [-options] -jar jarfile [args...]
           (to execute a jar file)

where options include:
    -client       to select the "client" VM
    -server       to select the "server" VM
    -hotspot      is a synonym for the "client" VM  [deprecated]
                  The default VM is client.
[...]

This shows that at least one java is working on your machine - if you have more than one, you should know what you are doing... :)

- or go to somewhere where you don't have java in your directory, and type

C:\>%JAVA_HOME%\bin\java    (for windows) or
$JAVA_HOME/bin/java         (for linux)

and get the same output.

That's it. Easy, no? :)

Now, let's go for tm4j - even if you like binaries, you will now also need the source-distribution, as some of the necessary files are only in there (that is, as of time of this writing...).

You will find both packages at http://sourceforge.net/project/showfiles.php?group_id=27895&package_id=19735 from where you will be led to the page where you can pick your closest download mirror.

Extract the source files, and change into the top directory of the source distribution - currently, that is tm4j-0.9.6, under which you find bin, build, and other dirs, but also the files build.xml (important for ant, and currently only available in the source distribution), and build.properties - which for me looks like this (comments inside):
---------------------
# JDK1.2+ ("modern") Sun compiler
build.compiler=modern

# Jikes compiler
#build.compiler=jikes

######################
##### TM4J VERSION ###
######################
# The version number included in all JAR files
# If not specified, the version number defaults
# to the current date
version=0.9.6

######################
##### HIBERNATE ######
######################
# The JDBC URL you use to connect to your relational database.
# Check your JDBC driver's documentation on JDBC URL syntax.
# The example provided here is for MySQL.
# localhost is easy, as we want to do it on the local machine,
# and tm4j is the name of the database we created, remember? :)
hibernate.connection.url=jdbc:mysql://localhost/tm4j

# The database username and password
hibernate.connection.username=tm4j
hibernate.connection.password=*whatever_you_set_here*

# Below are a few helpful settings for various
# database implementations
# (you should enable only one pair of these).
# TM4J does NOT come bundled with any JDBC driver, so
# make sure you copy the appropriate JAR to
# lib/hibernate.

# MySQL
hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class=com.mysql.jdbc.Driver
---------------------

All other entries, I skipped.

Now, before we do any ant-stuff, remember what it said up there?

# TM4J does NOT come bundled with any JDBC driver.

TRUE!

So point your browser to http://dev.mysql.com/downloads/connector/j/3.0.html and get yourself something like mysql-connector-java-3.0.14-production.zip - once you unzip it, you get, amongst other files, mysql-connector-java-3.0.14-production-bin.jar - copy that into the \lib-directory in your tm4j-source-tree.

Now, go back to the tm4j-directory, and do the following:

ant hibernate-install-mappings
and then
ant hibernate-initdb

the result should, eventually, look something like this:

[...couple of screesn full of stuff...]
     [java] alter table tm_options add index (id), add constraint FK1480B2D8D1B
foreign key (id) references topicmaps (id)
     [java] alter table topicmaps add index (baseLocator), add constraint FK1731
A4469D595085 foreign key (baseLocator) references locators (id)
     [java] alter table mergemaps add index (tm_id), add constraint FK6105CECF69
5A4A1 foreign key (tm_id) references topicmaps (id)
     [java] alter table mergemaps add index (locator), add constraint FK6105CECF
142BDC96 foreign key (locator) references locators (id)
     [java] create index sip_idx on topic_sips (sip_id)
     [java] alter table topic_sips add index (sip_id), add constraint FKCE45AFE9
CA394EA0 foreign key (sip_id) references SubjectIdentityPoint (id)
     [java] alter table topic_sips add index (topic_id), add constraint FKCE45AF
E9C6F0E22B foreign key (topic_id) references tmobjects (id)
     [java] Database schema installed successfully.

BUILD SUCCESSFUL
Total time: 10 seconds

Mind you - if you don,t have stuff like this:

      [java] alter table topic_sips add index (topic_id), add constraint
FKCE45AF
E9C6F0E22B foreign key (topic_id) references tmobjects (id)
      [java] Database schema installed successfully.

before the "BUILD SUCCESSFUL", you probably face a new challenge right now... :) Because for me, it did not have all that [java]-stuff there, but still claimed "BUILD SUCCESSFUL" - argh.

That is all on the backend side - concerning the frontend, I have not yet dealt with tm4j, but with tmnav - for some reason, I felt the urge to have my topic maps in a database instead of xtm-files on my harddisk.

So go to http://sourceforge.net/projects/tm4j and look for tmnav 0.2.8_1 or newer, download it, and unzip it to an appropriate location.

Then, you have to do two things:
- copy the mysql-connector (mysql-connector-java-3.0.14-production-bin.jar or newer) into the lib-directory, and
- adapt the file tmnav.xml, which you will have in your home-directory, after you have started tmnav for the first time.

In mine, the relevant part looks like this:

      <provider id="hibernate-provider">

<factoryclassname>org.tm4j.topicmap.hibernate.TopicMapProviderFactoryImpl</factoryclassname>
        <displayname>Hibernate-Provider</displayname>
        <description>This provider stores TopicMaps in a relational Database which is accessed via JDBC. Be sure to have the following jars on your classpath: hibernate.jar, commons-lang.jar, commons-logging.jar, commons-collections.jar, odmg.jar</description>
        <property key="hibernate.dialect">net.sf.hibernate.dialect.MySQLDialect</property>
        <property key="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
        <property key="hibernate.connection.url">jdbc:mysql://localhost/tm4j</property>
        <property key="hibernate.connection.username">tm4j</property>
        <property key="hibernate.connection.password">tm4j</property>
<!--            <property key="hibernate.connection.pool_size"></property>
            <property key="hibernate.statement_cache.size"></property>
-->
      </provider>

For the last two keys, I still have to look up the appropriate values up in kal's doc (or somewhere else), but it works without as well, for now.

Now, if you want to start tmnav, make sure that the mysql-server is running, otherwise tmnav will fail to start.

Well, that's it, right now. Still a couple of glitches to fight with, but had I had all information in this document at the beginning (and read it!), it would have saved some time.

Dear diary, I am tired now. nite... :)