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:

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).