uk.ac.cam.ucs.ibis.client

Class IbisClientConnection

java.lang.Object

uk.ac.cam.ucs.ibis.client.IbisClientConnection

All Implemented Interfaces:

ClientConnection

public class IbisClientConnection
extends Object
implements ClientConnection

Default implementation of the ClientConnection interface, to allow methods in the Lookup/Ibis web service API to be invoked.

Nested Class Summary

Nested classes/interfaces inherited from interface uk.ac.cam.ucs.ibis.client.ClientConnection

ClientConnection.Method

Constructor Summary

Constructors

Constructor and Description
IbisClientConnection(String urlBase, boolean checkCertificates) Create a new ClientConnection using the specified URL base, which should be something like "https://www.lookup.cam.ac.uk/".

Method Summary

Modifier and Type	Method and Description
static IbisClientConnection	createConnection() Create a ClientConnection to the Lookup/Ibis web service API at https://www.lookup.cam.ac.uk/.
static IbisClientConnection	createLocalConnection() Create a ClientConnection to a Lookup/Ibis web service API running locally on https://localhost:8443/ibis/.
static IbisClientConnection	createTestConnection() Create a ClientConnection to the Lookup/Ibis test web service API at https://lookup-test.srv.uis.cam.ac.uk/.
IbisResult	invokeMethod(ClientConnection.Method method, String path, String[] pathParams, Object[] queryParams, Object[] formParams) Invoke a web service GET, POST, PUT or DELETE method.
IbisResult	invokeMethod(String path, String[] pathParams, Object[] queryParams) Invoke a web service GET method.
void	setPassword(String password) Set the password to use when connecting to the Lookup/Ibis web service.
void	setUsername(String username) Set the username to use when connecting to the Lookup/Ibis web service.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IbisClientConnection

public IbisClientConnection(String  urlBase,
                            boolean checkCertificates)
    throws GeneralSecurityException,
           IOException,
           JAXBException

Create a new ClientConnection using the specified URL base, which should be something like "https://www.lookup.cam.ac.uk/". It is strongly recommended that certificate checking be enabled.

The connection is initially anonymous, but this may be changed using setUsername(String) and setPassword(String).

Parameters:

urlBase - The base URL to the Lookup/Ibis web service API.

checkCertificates - If this is true the server's certificates will be checked. Otherwise, the they will not, and the connection may be insecure.

Throws:

GeneralSecurityException

IOException

JAXBException

See Also:

createConnection(), createTestConnection()

Method Detail

createConnection

public static IbisClientConnection createConnection()
    throws GeneralSecurityException,
           IOException,
           JAXBException

Create a ClientConnection to the Lookup/Ibis web service API at https://www.lookup.cam.ac.uk/.

The connection is initially anonymous, but this may be changed using setUsername(String) and setPassword(String).

Returns:

the connection to the Lookup/Ibis server.

Throws:

GeneralSecurityException

IOException

JAXBException

createTestConnection

public static IbisClientConnection createTestConnection()
    throws GeneralSecurityException,
           IOException,
           JAXBException

Create a ClientConnection to the Lookup/Ibis test web service API at https://lookup-test.srv.uis.cam.ac.uk/.

The connection is initially anonymous, but this may be changed using setUsername(String) and setPassword(String).

NOTE: This test server is not guaranteed to always be available, and the data in it may be out of sync with the data on the live system.

Returns:

the connection to the Lookup/Ibis test server.

Throws:

GeneralSecurityException

IOException

JAXBException

createLocalConnection

public static IbisClientConnection createLocalConnection()
    throws GeneralSecurityException,
           IOException,
           JAXBException

Create a ClientConnection to a Lookup/Ibis web service API running locally on https://localhost:8443/ibis/.

The connection is initially anonymous, but this may be changed using setUsername(String) and setPassword(String).

This is intended for testing during development. The local server is assumed to be using self-signed certificates, which will not be checked.

Returns:

the connection to a local Lookup/Ibis server.

Throws:

GeneralSecurityException

IOException

JAXBException

setUsername

public void setUsername(String username)

Description copied from interface: ClientConnection

Set the username to use when connecting to the Lookup/Ibis web service. By default connections are anonymous, which gives read-only access. This method enables authentication as a group, using the group's password, which gives read/write access and also access to certain non-public data, based on the group's privileges.

This method may be called at any time, and affects all subsequent access using this connection, but should not affect any other ClientConnection objects.

Specified by:

setUsername in interface ClientConnection

Parameters:

username - The username to connect as. This should either be "anonymous" (the default) or the name of a group.

setPassword

public void setPassword(String password)

Description copied from interface: ClientConnection

Set the password to use when connecting to the Lookup/Ibis web service. This is only necessary when connecting as a group, in which case it should be that group's password.

Specified by:

setPassword in interface ClientConnection

Parameters:

password - The group password.

invokeMethod

public IbisResult invokeMethod(String   path,
                               String[] pathParams,
                               Object[] queryParams)
    throws IOException,
           JAXBException

Description copied from interface: ClientConnection

Invoke a web service GET method.

The path should be the relative path to the method with standard Java format specifiers for any path parameters, for example "api/v1/person/%1$s/%2$s". Any path parameters specified are then substituted into the path according to the standard Java formatting rules.

Specified by:

invokeMethod in interface ClientConnection

Parameters:

path - The path to the method to invoke.

pathParams - Any path parameters that should be inserted into the path in place of any format specifiers.

queryParams - Any query parameters to add as part of the URL's query string. These are expected to come in pairs {name1, value1, name2, value2, ...}.

Returns:

The result of invoking the method.

Throws:

IOException

JAXBException

invokeMethod

public IbisResult invokeMethod(ClientConnection.Method method,
                               String                  path,
                               String[]                pathParams,
                               Object[]                queryParams,
                               Object[]                formParams)
    throws IOException,
           JAXBException

Description copied from interface: ClientConnection

Invoke a web service GET, POST, PUT or DELETE method.

The path should be the relative path to the method with standard Java format specifiers for any path parameters, for example "api/v1/person/%1$s/%2$s". Any path parameters specified are then substituted into the path according to the standard Java formatting rules.

Specified by:

invokeMethod in interface ClientConnection

Parameters:

method - The method type (GET, POST, PUT or DELETE).

path - The path to the method to invoke.

pathParams - Any path parameters that should be inserted into the path in place of any format specifiers.

queryParams - Any query parameters to add as part of the URL's query string. These are expected to come in pairs {name1, value1, name2, value2, ...}.

formParams - Any form parameters to submit. These are expected to come in pairs {name1, value1, name2, value2, ...}.

Returns:

The result of invoking the method.

Throws:

IOException

JAXBException