13. Using the Handle Client Library

Communicating with the Handle System is done by sending requests to servers which then return a response. To resolve a handle, you send a ResolutionRequest to a server. To create a handle you send a CreateHandleRequest to a server. If you want to modify, remove, or add values to or from a handle you send a ModifyValueRequest, RemoveValueRequest, or AddValueRequest to a server, respectively.

There is an object for each of these requests in the net.handle.hdllib java package. In order to send these messages to a server you can use a HandleResolver object which is also located in the net.handle.hdllib package. For most messages, the HandleResolver object will locate the server that your messages should go to, send them, and return the response that was sent by the server. The following is an example that shows one way of programmatically resolving a handle:

import net.handle.hdllib.*; ... // Get the UTF-8 encoding of the desired handle. byte someHandle[] = Util.encodeString("10.1000/1"); // Create a resolution request. // (without specifying any types, indexes, or authentication info) ResolutionRequest request = new ResolutionRequest(someHandle, null, null, null); HandleResolver resolver = new HandleResolver(); // Create a resolver that will send the request and return the response. AbstractResponse response = resolver.processRequest(request); // Check the response to see if the operation was successful. if(response.responseCode == AbstractMessage.RC_SUCCESS) { // The resolution was successful, so we'll cast the response // and get the handle values. HandleValue values[] = ((ResolutionResponse)response).getHandleValues(); for(int i=0; i < values.length; i++) { System.out.println(String.valueOf(values[i])); } }

If all you want to do is resolve a handle, you can use the much simpler resolveHandle method of the HandleResolver as shown below.

import net.handle.hdllib.*; ... HandleValue values[] = new HandleResolver().resolveHandle("10.1000/1", null, null); for(int i=0; i < values.length; i++) { System.out.println(String.valueOf(values[i])); }

The Handle System Server and Client distributions include a "simple" package with command line tools to create, delete, and list handles. It also includes programs to home a naming authority and trace handle resolution. These programs provide a good starting point and simple guide to developing Java-based custom handle client software with the API. Each example program includes steps needed to form a handle request to send to a server . They are run from the command line and require certain arguments. The following commands should be run in the same directory as the `handle.jar' file.

• Create Handle:

  Simple tool for handle creation. It uses public key authentication.

  java -cp handle.jar net.handle.apps.simple.HDLCreate <auth handle> <auth index> <privkey> <handle>

• Delete Handle:

  Simple tool for handle deletion. It uses public key authentication.

  java -cp handle.jar net.handle.apps.simple.HDLDelete <auth handle> <privkey> <filename_of_file_with_handles_to_delete>

• List Handles:

  Simple tool for listing handles. It uses public key authentication.

  java -cp handle.jar net.handle.apps.simple.HDLList <auth handle> <auth index> <privkey> <naming authority>

• Trace handle:

  Simple tool for resolving a handle.

  java -cp handle.jar net.handle.apps.simple.HDLTrace <handle>

• Home Naming Authorities:

  Simple tool for homing Naming Authorities. It uses public key authentication.

  java -cp handle.jar net.handle.apps.simple.HomeNA <auth hdl> <privkey> <server ip> <NA handle>