org.opentox.toxotis.client
Interface IClient

All Superinterfaces:
Closeable
All Known Subinterfaces:
IGetClient, IPostClient
All Known Implementing Classes:
AbstractClient, AbstractHttpClient, AbstractHttpsClient, DeleteHttpsClient, GetHttpClient, GetHttpsClient, PostHttpClient, PostHttpsClient

public interface IClient
extends Closeable

Generic interface for a client in ToxOtis.

Author:
Pantelis Sopasakis, Charalampos Chomenides

Field Summary
static String httpProtocol
           
static String httpSecureProtocol
           
static String URL_ENCODING
          Standard UTF-8 Encoding
 
Method Summary
 IClient addHeaderParameter(String paramName, String paramValue)
          Note: if the parameter name (paramName) is either 'Accept' or 'Content-type', this method will override setMediaType and setContentType respectively.
 IClient authorize(AuthenticationToken token)
          Provide an authentication token to the client.
 void close()
          Closes this stream and releases any system resources associated with it.
 ReentrantReadWriteLock.WriteLock getConnectionLock()
          Returns the connection lock.
 String getMediaType()
          Retrieve the specified media type which is the value for the Accept HTTP Header.
 ReentrantReadWriteLock.ReadLock getReadLock()
          Returns the read-lock of the client.
 InputStream getRemoteStream()
          Get the body of the HTTP response as InputStream.
 int getResponseCode()
          Get the HTTP status of the response
 String getResponseContentType()
          Returns the content-type of the response.
 String getResponseHeader(String header)
          The header of the response.
 com.hp.hpl.jena.ontology.OntModel getResponseOntModel()
          If possible, get the ontological model provided in the response.
 com.hp.hpl.jena.ontology.OntModel getResponseOntModel(String specification)
          If possible, get the ontological model provided in the response.
 String getResponseText()
          Get the response body as a String in the format specified in the Accept header of the request.
 Set<VRI> getResponseUriList()
          Get the response of the remote service as a Set of URIs.
 VRI getUri()
          Get the targetted URI
 IClient setMediaType(Media mediaType)
          Specify the media-type to be used in the Accept header providing an instance of Media.
 IClient setMediaType(String mediaType)
          Specify the mediatype to be used in the Accept header.
 IClient setUri(String uri)
          Provide the target URI as a String
 IClient setUri(VRI vri)
          Set the URI on which the GET method is applied.
 

Field Detail

httpProtocol

static final String httpProtocol
See Also:
Constant Field Values

httpSecureProtocol

static final String httpSecureProtocol
See Also:
Constant Field Values

URL_ENCODING

static final String URL_ENCODING
Standard UTF-8 Encoding

See Also:
Constant Field Values
Method Detail

addHeaderParameter

IClient addHeaderParameter(String paramName,
                           String paramValue)
Note: if the parameter name (paramName) is either 'Accept' or 'Content-type', this method will override setMediaType and setContentType respectively. In general it is not advisable that you choose this method for setting values to these headers. Once the parameter name and its value are submitted to the client, they are encoded using the standard UTF-8 encoding.

Parameters:
paramName - Name of the parameter which will be posted in the header
paramValue - Parameter value
Returns:
The current instance of client with updated headers.
Throws:
NullPointerException - If any of the arguments is null.

authorize

IClient authorize(AuthenticationToken token)
Provide an authentication token to the client. This token is given to the remote server to verify the client's identity. The remote service in turn asks the openSSO service whether the underlying request is allowed for the client with the given token. Services have also access to the client's data such as username, name and email which might be stored on the server side to provide accounting facilities.

Parameters:
token - Authentication token which will be provided in the request's header. Authentication/Authorization follow RFC's guidelines according to which the token is provided using the Header Authorization.
Returns:
This object with an updated header.

close

void close()
           throws IOException
Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

Specified by:
close in interface Closeable
Throws:
IOException - if an I/O error occurs

getMediaType

String getMediaType()
Retrieve the specified media type which is the value for the Accept HTTP Header.

Returns:
The accepted media type.

getRemoteStream

InputStream getRemoteStream()
                            throws ServiceInvocationException
Get the body of the HTTP response as InputStream.

Returns:
InputStream for the remote HTTP response
Throws:
ToxOtisException - In case an error status code is received from the remote location.
ServiceInvocationException

getResponseCode

int getResponseCode()
                    throws ServiceInvocationException
Get the HTTP status of the response

Returns:
Response status code.
Throws:
ToxOtisException - In case the connection cannot be established because a ToxOtisException is thrown while a connection is attempted to the remote service.
ServiceInvocationException

getResponseOntModel

com.hp.hpl.jena.ontology.OntModel getResponseOntModel()
                                                      throws ServiceInvocationException
If possible, get the ontological model provided in the response. This assumes that the Accept Header of the request has value application/rdf+xml or at least some other rdf-related MIME (like for example application/x-turtle.

Returns:
The ontological model from the response body.
Throws:
ToxOtisException - A ToxOtisException is thrown in case the server did not provide a valid (syntactically correct) ontological model, or in case some communication error will arise.
ServiceInvocationException

getResponseOntModel

com.hp.hpl.jena.ontology.OntModel getResponseOntModel(String specification)
                                                      throws ServiceInvocationException
If possible, get the ontological model provided in the response. This assumes that the Accept Header of the request has value application/rdf+xml or at least some other rdf-related MIME (like for example application/x-turtle.

Parameters:
specification - the langauge of the serialization; null selects the default, that is "RDF/XML". Also available: "TTL", "N-TRIPLE" and "N3".
Returns:
The ontological model from the response body.
Throws:
ToxOtisException - A ToxOtisException is thrown in case the server did not provide a valid (syntactically correct) ontological model, or in case some communication error will arise.
ServiceInvocationException

getResponseText

String getResponseText()
                       throws ServiceInvocationException
Get the response body as a String in the format specified in the Accept header of the request.

Returns:
String consisting of the response body (in a MediaType which results from content negotiation, taking into account the Accept header of the request)
Throws:
ToxOtisException - In case some communication, server or request error occurs.
ServiceInvocationException

getUri

VRI getUri()
Get the targetted URI

Returns:
The target URI

setMediaType

IClient setMediaType(String mediaType)
Specify the mediatype to be used in the Accept header.

Parameters:
mediaType - Accepted mediatype
See Also:
RequestHeaders.ACCEPT

setMediaType

IClient setMediaType(Media mediaType)
Specify the media-type to be used in the Accept header providing an instance of Media.

Parameters:
mediaType - Accepted media-type
See Also:
RequestHeaders.ACCEPT

setUri

IClient setUri(VRI vri)
               throws ToxOtisException
Set the URI on which the GET method is applied.

Parameters:
vri - The URI that will be used by the client to perform the remote connection.
Throws:
ToxOtisException

setUri

IClient setUri(String uri)
               throws URISyntaxException,
                      ToxOtisException
Provide the target URI as a String

Parameters:
uri - The target URI as a String.
Throws:
URISyntaxException - In case the provided URI is syntactically incorrect.
ToxOtisException

getResponseUriList

Set<VRI> getResponseUriList()
                            throws ServiceInvocationException
Get the response of the remote service as a Set of URIs. The media type of the request, as specified by the Accept header is set to text/uri-list.

Returns:
Set of URIs returned by the remote service.
Throws:
ToxOtisException - In case some I/O communication error inhibits the transmittance of data between the client and the server or a some stream cannot close.
ServiceInvocationException

getConnectionLock

ReentrantReadWriteLock.WriteLock getConnectionLock()
Returns the connection lock. While a connection is being established this lock is held by the client. You can monitor it to know exactly when the connection has been established.

Returns:
The connection Write Lock.

getReadLock

ReentrantReadWriteLock.ReadLock getReadLock()
Returns the read-lock of the client. As long as the client reads the response that is returned from the remote location, this lock is being held by the client. Use this lock to know exactly when the client starts and stops reading from the response stream.

Returns:
The read-lock.

getResponseHeader

String getResponseHeader(String header)
                         throws ServiceInvocationException
The header of the response.

Parameters:
header - Name of the header.
Returns:
The value of the header as it is specified in the response.
Throws:
ServiceInvocationException - A ServiceInvocationException is thrown is the response headers are not accessible for any reason including, but not limited to, connectivity issues.

getResponseContentType

String getResponseContentType()
                              throws ServiceInvocationException
Returns the content-type of the response. This is a short-cut for #getResponseHeader("Content-type").

Returns:
The content-type of the response.
Throws:
ServiceInvocationException - A ServiceInvocationException is thrown in case this header value is not accessible as for example if the remote server is not reachable.


Copyright © 2011-2012 OpenTox. All Rights Reserved.