Overview (Lookup/Ibis web service client API)

Packages
Package	Description
uk.ac.cam.ucs.ibis.client	Provides the support classes necessary to connect to the Lookup/Ibis web service and invoke API methods.
uk.ac.cam.ucs.ibis.dto	Provides DTO classes for transferring data from the server to client in the web service API.
uk.ac.cam.ucs.ibis.methods	Contains auto-generated classes which contain all the available methods in the Lookup/Ibis web service API.

This document describes the Lookup/Ibis web service client API, which is intended to simplify the task of using the web service from Java client applications.

This client library provides code to automatically handle the following tasks:

Securely connect to the server over HTTPS, checking its certificates to ensure that it is really is the Lookup/Ibis server.
Authenticate with the server using HTTP Basic Authentication.
Construct correct URLs to methods on the server, encoding any method parameters that may form part of the path, or appear in the query string.
Encode any form parameters that may be needed in the request body.
Parse the XML returned by the server, producing one or more linked Java objects containing all the requested information in an easily accessible form.

All of the API methods are contained in XxxMethods classes in the uk.ac.cam.ucs.ibis.methods package, for example PersonMethods which contains methods relating to or returning people, and InstitutionMethods which contains methods relating to or returning institutions. All the XxxMethods classes are auto-generated, to keep them in sync with the matching server methods.

Some typical code using this API might look something like this:

    import uk.ac.cam.ucs.ibis.client.*;
    import uk.ac.cam.ucs.ibis.dto.*;
    import uk.ac.cam.ucs.ibis.methods.*;

    ClientConnection conn = IbisClientConnection.createTestConnection();
    InstitutionMethods im = new InstitutionMethods(conn);

    List<IbisPerson> people = im.getMembers("UIS", null);

    for (IbisPerson person : people)
        System.out.println(person.visibleName);

Note that it is typically only necessary to create a single instance of the ClientConnection and XxxMethods objects, and then re-use them throughout your Java application.

Thread safety

Once created and initialised, the ClientConnection and XxxMethods classes are safe to use from multiple simultaneous threads (for example in a web server).

Note, however, that ClientConnection.setUsername() and ClientConnection.setPassword() are not thread safe. These methods are regarded as part of the initialisation of the connection, and should typically only be used once on startup. If you need to regularly switch between users, then use a separate ClientConnection per user or per thread (and separate corresponding XxxMethods objects).