de.mpg.mpiz_koeln.featureClient
Class FeatureClient

java.lang.Object
  de.mpg.mpiz_koeln.featureClient.FeatureClient

public class FeatureClient
extends Object

It features several things:

• Calling services with the concrete objects (like AminoAcidSequence)
• Service discovery based on service name or input/output definition (like return all services which consume an AGI locus code and return PMIDs)
• Parallelization for multiple service calls
• Using a timeout if the service does not return in that time
• Calling a service once with possible different inputs

How to use the this client can be learned by looking a the examples found in the de.mpg.mpiz_koeln.featureClient.test.

Author:

Andreas Groscurth

Nested Class Summary

static class

FeatureClient.JobIdentifier

Constructor Summary

FeatureClient()
Creates a new FeatureClient instance default the central in Canada.

FeatureClient(Central central)
Creates a new FeatureClient instance with the given moby central and the default timeout of 20s.

FeatureClient(Central central, long timeout)
Creates a new FeatureClient instance with the given moby central and a given timeout.

Method Summary

void	add2Filter(Collection<String> services) Adds the services to the filter list.
void	add2Filter(String... services) Adds a list of service names to the filter.
void	addMultipleCallInput(FeatureClient.JobIdentifier jobIdentifier, MobyObject... inputs) Adds one or more input(s) to the client which are used to call services once or more.
void	addMultipleCallInput(FeatureClient.JobIdentifier identifier, String id)
void	addMultipleCallInput(FeatureClient.JobIdentifier identifier, String namespace, String id)
void	addMultipleCallInput(FeatureClient.JobIdentifier identifier, String namespace, String id, String name)
void	addMultipleCallInput(String id)
void	addMultipleCallInput(String jobidentifier, MobyObject... inputs)
void	addMultipleCallInput(String namespace, String id) Adds a new simple input to the client.
void	addMultipleCallInput(String namespace, String id, String name) Adds a new simple input to the client.
void	addOutput(String datatype) Adds an output definition.
void	addOutput(String datatype, String... namespaces) Adds an output definition.
void	addSecondary(String name, String value) Adds a secondary (parameter) to the request.
void	addService(String name) Adds a service name to the list of service which will be called.
void	addService(String auth, String name) Adds a service to the request.
Collection<FeatureClientResult>	call() Calls one or several services (which are found by the find-service-procedure) and returns their results.
Collection<FeatureClientResult>	call(Collection<MobyService> services) Calls all given services and returns their result.
Collection<FeatureClientResult>	call(MobyService mobyService) Calls the moby service and returns its result.
<T> Map<String,Collection<T>>	callServiceMultipleTimes() Calls a service multiple times and returns it results.
<T> Collection<T>	callWithMultipleResult() Calls a service and returns the results of the service.
<T> T	callWithSingleResult() Calls a service and returns the one result the service returns.
void	setAuthentication(String user, String password) Sets the user and the password for a possible authentification of a service.
void	setCentral(String url, String uri) Sets the central to be used.
void	setSingleCallInput(MobyObject... inputs) Sets the inputs for a single service call.
void	setSingleCallInput(String namespace, String id) Sets the input for a single service call.
void	setSingleCallInput(String namespace, String id, String name) Sets the input for a single service call.
void	setTimeout(long timeout) Sets the timeout in seconds how long the call shall be kept alive.
void	setValidateServices(boolean validateServices) Sets whether the services which will be called, shall be validated if they are working.

Methods inherited from class java.lang.Object

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

Constructor Detail

FeatureClient

public FeatureClient(Central central)

Creates a new FeatureClient instance with the given moby central and the default timeout of 20s.

Parameters:

central - the central to be used

FeatureClient

public FeatureClient()
              throws MobyException

Creates a new FeatureClient instance default the central in Canada. It uses the default timeout of 20s.

Throws:

MobyException

FeatureClient

public FeatureClient(Central central,
                     long timeout)

Creates a new FeatureClient instance with the given moby central and a given timeout.

Parameters:

central - the central to use

timeout - the timeout how long a service call is valid

Method Detail

setValidateServices

public void setValidateServices(boolean validateServices)

Sets whether the services which will be called, shall be validated if they are working. This is done via a script at the official moby central repository.

Parameters:

validateServices - validate ?

setCentral

public void setCentral(String url,
                       String uri)
                throws MobyException

Sets the central to be used. The central is identified by its URL and its URI

Parameters:

url - the endpoint of the central

uri - the namespace of the central

Throws:

MobyException

call

public Collection<FeatureClientResult> call(Collection<MobyService> services)

Calls all given services and returns their result.

Parameters:

services - list of services to be called

Returns:

list of FeatureClientResult

callWithSingleResult

public <T> T callWithSingleResult()
                       throws FeatureClientException

Calls a service and returns the one result the service returns. This is used if one wants to call one service which returns exactly one result.

Type Parameters:

T - the datatype which the service returns

Returns:

the one service result

Throws:

FeatureClientException - something happened

callWithMultipleResult

public <T> Collection<T> callWithMultipleResult()
                                     throws FeatureClientException

Calls a service and returns the results of the service. This is used if one wants to call one service which returns a collection of results.

Type Parameters:

T - the datatype which the service returns

Returns:

the collection of results

Throws:

FeatureClientException

callServiceMultipleTimes

public <T> Map<String,Collection<T>> callServiceMultipleTimes()
                                                   throws FeatureClientException

Calls a service multiple times and returns it results. This is used if one wants to call one service more than once.

Type Parameters:

T - the datatype which the service returns

Returns:

the results of the multiple calls.

Throws:

FeatureClientException

call

public Collection<FeatureClientResult> call()
                                     throws FeatureClientException

Calls one or several services (which are found by the find-service-procedure) and returns their results.

Returns:

list of service call results

Throws:

FeatureClientException

call

public Collection<FeatureClientResult> call(MobyService mobyService)

Calls the moby service and returns its result.

Parameters:

mobyService - the service to be called

Returns:

the result list of the service call

setSingleCallInput

public void setSingleCallInput(String namespace,
                               String id)
                        throws FeatureClientException

Sets the input for a single service call. The input is a simple input and can not be used to set complex data types. The simple object input is identified via its namespace and its id.

Parameters:

namespace - the namespace of the object

id - the identifier of the object

Throws:

FeatureClientException

setSingleCallInput

public void setSingleCallInput(String namespace,
                               String id,
                               String name)
                        throws FeatureClientException

Sets the input for a single service call. The input is a simple input and can not be used to set complex data types. It also sets the name of the object if the service requires explicit naming of the input parameter.

Parameters:

namespace - the namespace of the object

id - the identifier of the object

name - the article name of the object

Throws:

FeatureClientException

setSingleCallInput

public void setSingleCallInput(MobyObject... inputs)
                        throws FeatureClientException

Sets the inputs for a single service call. The inputs can either be a simple object type or a complex type. This method is only to be used if a service requires more than one input. If one wishes to call a service multiple times see addMultipleCallInput(String, MobyObject...)

Parameters:

inputs - the inputs for the service call

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(String id)
                          throws FeatureClientException

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(FeatureClient.JobIdentifier identifier,
                                 String id)
                          throws FeatureClientException

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(FeatureClient.JobIdentifier identifier,
                                 String namespace,
                                 String id)
                          throws FeatureClientException

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(FeatureClient.JobIdentifier identifier,
                                 String namespace,
                                 String id,
                                 String name)
                          throws FeatureClientException

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(String namespace,
                                 String id)
                          throws FeatureClientException

Adds a new simple input to the client. This is used if services shall be called multiple times with different inputs.

Parameters:

namespace - the namespace of the input

id - the identifier of the input

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(String namespace,
                                 String id,
                                 String name)
                          throws FeatureClientException

Adds a new simple input to the client. This is used if services shall be called multiple times with different inputs. It also sets the article name of the object in case the service require this !

Parameters:

namespace - the namespace of the object

id - the identifier of the object

name - the article name of the object

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(String jobidentifier,
                                 MobyObject... inputs)
                          throws FeatureClientException

Throws:

FeatureClientException

addMultipleCallInput

public void addMultipleCallInput(FeatureClient.JobIdentifier jobIdentifier,
                                 MobyObject... inputs)
                          throws FeatureClientException

Adds one or more input(s) to the client which are used to call services once or more. If a service requires a complex data type, this method has to be used. The inputs are not used to call the service more than once, but only for setting the inputs of one service call. To add more inputs for multiple class this method has to be called multiple times with different inputs.

Parameters:

jobIdentifier - an identifier to know later which service result was which input

inputs - the service inputs of a service

Throws:

FeatureClientException

addOutput

public void addOutput(String datatype,
                      String... namespaces)

Adds an output definition. The output definition consists of the data type and a list of namespaces (like 'Object' with namespaces 'PMID', 'PMCID' to get Publications)

Parameters:

datatype - the data type

namespaces - a list of namespaces

addOutput

public void addOutput(String datatype)

Adds an output definition. This method is identical to addOutput(String, String...) with data type and null as parameters for namespaces. This is used when the data type does not require specific namespaces.

Parameters:

datatype - the datatype

setTimeout

public void setTimeout(long timeout)

Sets the timeout in seconds how long the call shall be kept alive. If a service does not respond in the given timeout frame the call is terminated.

Parameters:

timeout - the timeout in seconds

addSecondary

public void addSecondary(String name,
                         String value)

Adds a secondary (parameter) to the request.

Parameters:

name - the name of the secondary

value - the value of the secondary

add2Filter

public void add2Filter(String... services)

Adds a list of service names to the filter. This filter is kind of a blacklist to remove services, one might not want to call. The services can either be determined by their name or one can provide an authority to remove all services of that authority.

Parameters:

services - service names to be removed

add2Filter

public void add2Filter(Collection<String> services)

Adds the services to the filter list. These services will later be filtered out during service finding and not be called afterwards. The services can either be determined by their name or one can provide an authority to remove all services of that authority.

Parameters:

services - the services

addService

public void addService(String auth,
                       String name)

Adds a service to the request. This service will be called during the calling process. The service is determined by the authority and the service name, which guarantees to exactly find one service during the service find process.

Parameters:

auth - the authority of the service

name - the name of the service

addService

public void addService(String name)

Adds a service name to the list of service which will be called.
WARNING: It is highly adviced to use addService(String, String) and to give also the authority with the service name, as this method is not guaranteed to find and cache the correct service you might look for !

Parameters:

name - the service name

setAuthentication

public void setAuthentication(String user,
                              String password)

Sets the user and the password for a possible authentification of a service.

Parameters:

user - the user

password - his/her password