Handle Server Technology

Overview
The handle server is a TCP service that assists in resolving Handles. It is not needed for basic DSpace functionality, but it is used whenever an end-user dereferences a handle-format URL. These URLs are printed in older articles that have associated Dryad data (articles published before the introduction of DOIs). They are also available from various parts of Dryad, where the interface has not been completely updated to use DOIs.

Functionality
When a user resolves a handle, by putting a handle-format URL in their browser, they are redirected to the appropriate item page in Dryad. Everything else should be invisible to an end-user.

When the central CNRI server receives a request for handle resolution, it first queries the Dryad handle server. The Dryad handle server checks to see whether an appropriate entry exists in the Dryad database. If so, it returns the appropriate redirect URL, and the CNRI server passes this URL on to the user's browser.

Workflow
Startup:
 * 1) Administrator runs /opt/dryad/bin/start-handle-server
 * 2) Handle server reads some configuration from config.dct (port numbers and other handle setttings) and other configuration from dspace.cfg (database connection information and logging information)
 * 3) Handle server uses some services from dspace.jar to initiate the database connection.
 * 4) Handle server runs as a deamon connected to a particular TCP port, and waits for requests.

For each request:
 * 1) User sends GET request to the CNRI servers (e.g., http://hdl.handle.net/10255/dryad.20)
 * 2) CNRI looks in their local configuration (from the uploaded sitebndl.zip) to determine the appropriate IP address of the local handle server.
 * 3) CNRI sends a TCP request to the local handle server.
 * 4) The local deamon receives the request, and performs a search in the DSpace database for the appropriate handle.
 * 5) If the handle exists in the database, the deamon returns the appropriate redirection URL (e.g., http://datadryad.org/handle/10255/dryad.20)
 * 6) This URL is built using the server base URL set in dspace.cfg (???does the handle prefix come from dspace.cfg or config.dct???)
 * 7) CNRI simply forwards the URL to the user's browser for redirection.
 * 8) The user's browser loads the resultant page.
 * 9) If the handle does not exist in the database, the deamon returns a "not found" indicator, and CNRI generates a "handle not found" page.

Configuration
Installing the handle server for the first time (or rebuilding it on a new machine):
 * 1) Run /opt/dryad/bin/dspace make-handle-config /opt/dryad/handle-server
 * 2) Answer the questions
 * 3) * It is best to provide generic contact information, such as help@datadryad.org
 * 4) * Take the defaults whenever possible.
 * 5) * Note that the http port is the port for the handle server -- it shouldn't be the same as a port you are already using for DSpace.
 * 6) Take the sitebndl.zip file out of /opt/dryad/handle-server and email it to hdladmin@cnri.reston.va.us with a request to update the IP address. NOTE: The DSpace manual specifies uploading this file to a particular webpage. This should only be done when a new handle prefix is being requested. We do not expect that Dryad will ever use a new handle prefix.
 * 7) Edit handle-server/config.dct:
 * 8) * Replace YOUR_NAMING_AUTHORITY with the actual handle prefix (10255)
 * 9) * Verify that these lines exist within the server_config section (or add them):
 * 10) ** "case_sensitive" = "yes"
 * 11) ** "storage_type" = "CUSTOM"
 * 12) ** "storage_class" = "org.dspace.handle.HandlePlugin"
 * 13) Run sudo /opt/dryad/bin/start-handle-server
 * 14) Check for any errors in the log files in the handle-server directory
 * 15) Ensure the handle server can get through the firewall on the ports you selected earlier.
 * 16) Ensure that the handle server will start when the machine is rebooted.

This email thread has some useful info: http://dspace.2283337.n4.nabble.com/handle-server-location-td3293457.html

Troubleshooting

 * See if there are error messages in any of the log files. Logs can be found in both /opt/dryad/logs and /opt/dryad/handle-server
 * Ensure that requests are resulting in log entries. If not, the handle server may not be running, CNRI may be using the wrong IP address to contact the handle server, or the handle server's ports may be closed.
 * Ensure that the ports specified in config.dct are open to the world.
 * Ensure that the settings listed above for config.dct are in place, particularly the case-sensitivity.

Relation to DSpace
The handle server code used by Dryad is exactly the same as used by any standard DSpace installation. Only some of the configuration is different. In particular:
 * Dryad uses the handle prefix 10255.
 * Dryad identifiers include alphabetic characters, so the handle server must be configured to be case-sensitive.
 * Pathnames in the commands above are specific to the standard way that Dryad is installed.