What is in this kit:
--------------------

mit-hierarchy.jar -- this is the implementation of Hierarchy OSID. This jar needs to be on the classpath of your application.

build.xml -- the ant script to build your database schema

lib/ -- third party libraries used by this OSID. An additional readme.txt in that directory describes each one. These libraries must be on your classpath.

etc/ -- configuration files for hibernate and logging. This directory must be on your classpath.

antlib/ -- the libraries needed to run the ant task for building your database schema

doc/ -- javadoc for the Hierarchy and Shared OSIDs, plus other relevant OKI docs.

example/ -- sample applications using the Hierarchy OSID. Each has a readme.txt that explains it.

osidimpl/ -- the source for the Hierarchy OSID

Everything in this kit is built using ant.


To use this kit:
----------------

1.) define your database properties in etc/hibernate.properties
2.) define your logging options in etc/log4j.properies
3.) put your database driver into lib/ and antlib/. There is already a MySQL driver there.
4.) create your database schema
5.) go to example/* and use ant to build the various sample applications and run them
6.) write your own application!


Using Hibernate:
----------------

This implementation of the Hierarchy OSID uses Hibernate 2.1 for its persistance. You can therefore customize the backend used by editing the etc/hibernate.properties file to connect to your chosen database and to configure connection pooling. You must make sure that the necessary database driver is on your classpath -- placing it in lib/ is a good idea. The lib/ directory contains libraries needed by this implementation. It contains the minimum number of Hibernate libraries required in order to run a simple test case on MySql. If you require other options for your connection pooling or runtime environment, they are available in the Hibernate distribution. For more information about how to configure Hibernate, go to http://www.hibernate.org


Using Commons Logging:
---------------------

The implementation also uses Jakarta Commons Logging and includes a Log4J implementation. You can configure your logging options by editing the etc/log4j.properties file. You can also substitute another Commons Logging implementation. 
For more information, see http://jakarta.apache.org/commons/logging/


Creating your database schema:
------------------------------

To create your database schema, configure hibernate.properties to specify your chosen SQL dialect. Put hibernate.properties into the /antlib directory so it will be found by the ant task.

Then use ant as follows to create a database script:

	ant -lib antlib schemaexport

This will create the file schemaexport.sql, which contains the SQL commands to create your database schema. Use your favorite DB query tool to run the script and buid the schema in the database.

You can also use this task to directly configure your schema in the database so you don't have to run a script. To do this, make sure that your database driver is in the /antlib directory and use the following command:

	ant -lib antlib -Dtextonly=no schemaexport



If you have any problems, contact the Enterprise Architecture Services group at ac-eas@mit.edu