ACE Ims API

The Java IMS api provides a mechanism to both create tokens and validate existing tokens against the IMS. There are four jars required for the API. The API has been designed to work for Java 1.6.0 or greater.

Getting Started

• Javadoc

Required Components

• ims-api.jar - API classes
• ace-common.jar - shared ACE components, error message constants, etc
• adapt-util.jar - Utility classes, string parsing, etc
• Log4j-1.2.15.jar - Logging for the API

Sample Code

• BatchSample.java

Connect to IMS

All communication with the IMS is handled through the IMSService class.

IMSService ims = IMSService.connect("ims.umiacs.umd.edu", 8080);

Token Creation

The IMS provides the TokenRequestBatch service that can be used to bulk register tokens. The service is available from your ims connection. It requires a name of your token service, a RequestBatchCallback to notify you when tokens have been registered, max mumber of tokens to send on one call, and how many milliseconds to wait at most before a call.

// create service
TokenRequestBatch batch = ims.createImmediateTokenRequestBatch("SHA-256-0", new BatchCallback(), 1000, 5000);
// register file
TokenRequest request = new TokenRequest();
request.setHashValue("5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef");
request.setName("c:/some/file");
batch.add(request);
// shutdown registration thread and block until all outstanding requests have been serviced
batch.close();

The TokenRequestBatch will spawn off a thread that handles all communication with the IMS. This means the batch.add call is nonblocking and can be used in a loop to add many files. The batch will add files to a queue and when any of the thresholds used to create the batch are met, a request will be sent to the IMS.

File[] fileList = getListOfFiles(...);
for (File file : fileList)
{
    String fileDigest = createSha256Digest(file...);
    TokenRequest request = new TokenRequest();
    request.setHashValue(fileDigest);
    request.setName(file.getName());
    batch.add(request);
}
batch.close();

RequestBatchCallback

The RequestBatchCallback handles responses from the IMS. It provides three methods that will be called when an IMS request returns. Please note, this will be called from an internally created thread and not the thread that called batch.add(). Implementers should take care to make sure there are no threading issues between adding requests and receiving responses.

   class BatchCallback implements RequestBatchCallback
    {

        public void tokensReceived(List<TokenRequest> requests,
                List<TokenResponse> responses)
        {
            int numResponses = 0;
            int numErrors = 0;

            for ( TokenResponse response : responses )
            {
                if ( response.getStatusCode() != StatusCode.SUCCESS )
                {
                    System.out.println("Unsuccessful request: " +
                            "name: " + response.getName() + ", status code: " +
                            response.getStatusCode());
                    numErrors++;
                }
                else
                {
                    System.out.println("Suffessful request: " +
                            "name: " + response.getName() + ", status code: " +
                            response.getStatusCode());
                    numResponses++;
                }
            }
            System.out.println("" + requests.size() + " request(s), " +
                    numResponses + " response(s), " +
                    numErrors + " error(s)");
        }

        public void exceptionThrown(List<TokenRequest> requests, Throwable t)
        {
            System.out.println("" + requests.size() +
                    " error(s) on exception: " + t.getMessage());
        }

        public void unexpectedException(Throwable t)
        {
            System.out.println("*** ERROR: " + t.getMessage());
            t.printStackTrace();
        }
    }

Complete Registration Sample

A complete sample is available BatchSample.java