#---------------------------#
# Hedgehog 1.0              #
#---------------------------#

Hedgehog is an RDBMS storage implementation for the Handle server distributed 
by CNRI (http://www.handle.net/).  Hedgehog uses the Hibernate persistent object
storage toolkit, and can be used with any Hibernate-supported JDBC-compliant 
backend database.

Prerequisites
--------------

   * Handle server.  Tested with handle server version 6.2.5.
   * Java 1.5
   * Any Hibernate-supported JDBC-compliant database. Hedgehog ships with 
     Derby, a Java-based embedded RDBMS, which can be enabled through the configuration 
     process as described below.
   
Installation (Unix)
-------------------

1.  Download and tar-unzip the file hedgehog-1.0-bin.tgz in a temporary location,
    referred to below as DISTDIR.

2.  Make a lib/ directory under your handle server root (HDLROOT):

    mkdir <HDLROOT>/lib
    
3.  Copy handle.jar (distributed with the handle server), all the jar files in
    the Hedgehog package lib/ subdirectory to the newly-created lib/ directory:
    
    cp handle.jar <HDLROOT>/lib
    cp <DISTDIR>/lib/*.jar <HDLROOT>/lib
    
4.  Copy your database JDBC driver jar file to the lib/ directory

    cp <DB_DRIVER>.jar <HDLROOT>/lib
    
5.  Copy the provided Hedgehog config.dct file to your handle root, then edit 
    it (make a backup of your current config.dct first, if you have one):
    
    cp <DISTDIR>/config.dct <HDLROOT>/
    vi <HDLROOT>/config.dct
    
    Edit the usual handle parameters (bind_address, bind_port, etc.) according
    to the instructions provided with the handle server.
    
    To enable Hedgehog, change the following parameters in the storage_config 
    block:
    
    To use the embedded Derby database:
       "hedgehog_embedded_derby" = "true"
       and delete the "hedgehog_hibernate_url" line.
       
    To use your own RDBMS:
       "hedgehog_hibernate_dialect" = "org.hibernate.dialect.<YOUR DB DIALECT>"
          (see http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-optional-dialects)
       "hedgehog_hibernate_driver" = "<YOUR DRIVER CLASS>"
       "hedgehog_hibernate_url" = "jdbc:<DB URL>"
       
6.  Copy the hedgehog configuration files to your handle root:

    cp <DISTDIR>/hibernate.cfg.xml <DISTDIR>/log4j.properties <HDLROOT>/

    Edit log4j.properties to suit your logging preference.
    
    Edit hibernate.cfg.xml for your database environment.  The parameters that 
    need to be changed are indicated in the file.

7.  Set your Java CLASSPATH to include all the jars in <HDLROOT>/lib.  Here's one 
    method, which uses the "paste" command:
    
    CLASSPATH=`ls <HDLROOT>/lib/*.jar | /usr/local/bin/paste -s -d":"`
    CLASSPATH=".:$CLASSPATH"
    export CLASSPATH
   
8.  Initialize the Handles database:
 
    java -cp `echo $CLASSPATH` \ 
                edu.wisc.doit.lira.library.hedgehog.HedgehogHandleStorageSetup \ 
                <HDLROOT>

9.  Start your handle server:

    java -cp `echo $CLASSPATH` net.handle.server.Main <HDLROOT> >> handleserver.log 2>&1 &
    
Notes and Caveats
-----------------

* Any changes made directly in the database will not be replicated to mirrors.  
  To replicate changes made directly to the database (i.e., using sqlplus, psql, 
  triggers. PL/SQL, etc.), shut down your mirror, delete the mirror's 
  txnstat.dct file, and restart it.  The mirror server will then  delete its 
  locally-mirrored handles and re-sync with the primary.

* Be careful when modifying records in the database directly.  If your server 
  is set up to canonicalize handle IDs to uppercase, you'll need to make sure 
  all your handle IDs are uppercase in the database.

* If you're going to run the handle server as a mirror:

    -- Set the "hedgehog_is_mirror" and "hedgehog_allow_delete_all" parameters 
       in config.dct to "true".
    
    -- If you shut down the mirror, and you have a large (100,000+) number of 
       handles, go into the database directly and truncate the tables prior 
       to restarting the handle mirror server.  Hedgehog performs cascading 
       DELETES when resetting the mirror database before resyncing with the 
       primary server.  This can be very time consuming with large databases.
       
    -- Be aware that Hedgehog checks for data integrity prior to 
       inserting/modifying handles and handle values in its database.  This 
       means that every handle value being mirrored must have a type, every 
       handle must be well-formed, be unique within its naming authority, etc.  
       If the primary sends a bad handle or handle value, Hedgehog will throw 
       an error, the mirroring process will abort and restart.  In this case, 
       shut down the mirror server, fix the bad data in the primary server, 
       and restart the mirror.  Consult the log files and the handle server
       STDOUT for more information.
        
* In initial load testing, Hedgehog has performed well during both
  short peaks and sustained periods of very high load, responding to queries
  in less than a tenth of a second on test machines.  However, due to the 
  overhead of running an RDBMS backend, it is unlikely that it will ever be
  as fast as the native JDB implementation.  If extremely high performance 
  is a concern, consult your DBA to optimize your database, or stick with 
  the native JDB files.
  
* Log files are your friends.  Configure the log4j.properties file to redirect
  Hedgehog logs as you wish, and to the desired level of verbosity.  The DEBUG
  log level is very verbose, especially for the Hibernate logging, and
  should only be used when troubleshooting.
  
* The file "hedgehog-erd.pdf" contains an ERD diagram for the Hedgehog handles 
  database.  It's pretty simple.