Page History

...

• You don't have to use CNRI's Handle system. At the moment, you need to change the code a little to use something else (e.g PURLs) but that should change soon.
• You'll notice that while you've been playing around with a test server, DSpace has apparently been creating handles for you looking like hdl:123456789/24 and so forth. These aren't really Handles, since the global Handle system doesn't actually know about them, and lots of other DSpace test installs will have created the same IDs. They're only really Handles once you've registered a prefix with CNRI (see below) and have correctly set up the Handle server included in the DSpace distribution. This Handle server communicates with the rest of the global Handle infrastructure so that anyone that understands Handles can find the Handles your DSpace has created.
• If you want to use the Handle system, you'll need to set up a Handle server. This One is included with DSpace. Note that this is not required in order to evaluate DSpace; you only need one if you are running a production service. You'll need to obtain a Handle prefix from the central CNRI Handle site.

A Handle server runs as a separate process that receives TCP requests from other Handle servers, and issues resolution requests to a global server or servers if a Handle entered locally does not correspond to some local content. The Handle protocol is based on TCP, so it will need to be installed on a server that can send and receive TCP on port 2641.

You can either use a Handle server running on the same machine as DSpace, or you can install it on a separate machine. Installing it on the same machine is a little bit easier.  If you install it on a separate machine, you can use one Handle server for more than one DSpace installation.

To install your Handle resolver on the host where DSpace runs:

1. To configure your DSpace installation to run the handle server, run the following command:

   Code Block
   [dspace]/bin/dspace make-handle-config [dspace]/handle-server

   Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property.

   1. If you are using Windows, the proper command is:

      Code Block
      [dspace]/bin/dspace dsrun net.handle.server.SimpleSetup [dspace]/handle-server

      Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property.

2. Edit the resulting [dspace]/handle-server/config.dct file to include the following lines in the "server_config"clause:

   Code Block
   "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin"

   This tells the Handle server to get information about individual Handles from the DSpace code.

3. Once the configuration file has been generated, you will need to go to http://hdl.handle.net/4263537/5014 to upload the generated sitebndl.zip file. The upload page will ask you for your contact information. An administrator will then create the naming authority/prefix on the root service (known as the Global Handle Registry), and notify you when this has been completed. You will not be able to continue the handle server installation until you receive further information concerning your naming authority.
4. When CNRI has sent you your naming authority prefix, you will need to edit the config.dct file. The file will be found in /[dspace]/handle-server. Look for "300:0.NA/YOUR_NAMING_AUTHORITY". Replace YOUR_NAMING_AUTHORITY with the assigned naming authority prefix sent to you.

5. Now start your handle server (as the dspace user):

   Code Block
   [dspace]/bin/start-handle-server

   1. If you are using Windows, the proper command is (please replace "[dspace]\handle-server" with the full path of the handle-server directory):

      Code Block
      [dspace]/bin/dspace dsrun net.handle.server.Main [dspace]/handle-server

      Ensure that [dspace]/handle-server matches whatever you have in dspace.cfg for the handle.dir property.

Note that since the DSpace code manages individual Handles, administrative operations such as Handle creation and modification aren't supported by DSpace's Handle server.

To install a Handle resolver on a separate machine:

The Handle server you use must be dedicated to resolve Handles from DSpace. You cannot use a Handle server that is in use with other software already. You can use CNRI's Handle Software -- all you have to do is to add to it a plugin that is provided by DSpace. The following instructions were tested with CNRI's Handle software version 7.3.1. You can do the following steps on another machine than the machine DSpace runs on, but you have to copy some files from the machine on which DSpace is installed.

1. Download the CNRI Handle Software: http://www.handle.net/download.html. In the tarball you'll find an INSTALL.txt with installation instructions -- follow it.
2. Download the plugin from https://github.com/DSpace/Remote-Handle-Resolver.  TBS:  how to build it or use a compiled JAR and copy it to the resolver.
3. After installing the CNRI Handle Software you should have two directories: once that contains the CNRI software and one that contains the configuration of you local Handle Server. For the rest of this instruction we assume that the directory containing the CNRI Software is /hs/hsj-7.3.1 and the directory containing the configuration of your local server is /hs/srv_1.  (We use the same paths here as CNRIs INSTALL.txt.)  In your DSpace installation directory you'll find the following two files: [dspace-install]/lib/log4j-1.2.14.jar, [dspace-install]/lib/DSpace-handle-plugin.jar. Copy them into /hs/hsj-7.3.1/lib.
4. Create the directory /hs/srv_1/logs.

5. Create the following two files in /hs/srv_1.

   log4j-handle-plugin.properties

    

   log4j.rootCategory=INFO, A1 log4j.appender.A1=org.apache.log4j.DailyRollingFileAppender log4j.appender.A1.File=/hs/srv_1/logs/handle-plugin.log log4j.appender.A1.DatePattern='.'yyyy-MM-dd log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%d %-5p %c @ %m%n log4j.logger.org.apache.axis.handlers.http.HTTPAuthHandler=INFO

    

   Change the path in the third line, if necessary.

   handle-dspace-plugin.cfg

    

   dspace.handle.endpoint1 = http://example.org/dspace/handleresolver

    

   If you are using XMLUI take a look in [dspace-install]/config/dspace.cfg, change the URL above to the value of your dspace.url and add /handleresolver to the end of it. If you are using JSPUI take a look in [dspace-install]/config/dspace.cfg, change the URL above to the value of your dspace.url and add /json/hdlresolver to the end of it. If you run more than one DSpace Installation, you may add more DSpace Endpoints.  Just increase the number at the end of the key for each:  endpoint2, endpoint3....

6. Edit /hs/srv_1/config.dct file to include the following lines in the "server_config" clause:

    

   "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.MultiRemoteDSpaceRepositoryHandlePlugin"

7. Copy /hs/hsj-7.3.1/bin/hdl-server to /hs/srv_1/start-hdl-server
8. Edit /hs/srv_1/start-hdl-server:
   
   1. Find the last line that begins with HDLHOME=
   2. Below that line add the following one: HDLHOME="/hs/hsj-7.3.1/"
   3. Find a line that contains exec java ... net.handle.server.Main ...
   4. Add "-Dlog4j.configuration=file:///hs/srv_1/log4j-handle-plugin.properties -Ddspace.handle.plugin.configuration=/hs/srv_1/handle-dspace-plugin.cfg" right in front of net.handle.server.Main.
9. If your handle server is running, stop it.
10. From now on you should start this handle server using /hs/srv_1/start-hdl-server

Please note: The Handle Server will only start if it is able to connect to at least one running DSpace Installation. It only resolves the handles of the DSpace Installations that were running when it was started.

Updating Existing Handle Prefixes

...