org.biomoby.client
Class BaseClient

java.lang.Object
  org.biomoby.client.BaseClient

Direct Known Subclasses:

BaseCmdLineClient, ExtendedProtocolClient

public abstract class BaseClient
extends Object

This is a base class for Biomoby clients. It takes care about converting user input into Biomoby XML, sending it in a SOAP message to a Biomoby service, waiting for the response and parsing it from Biomoby XML. It also divides requests and responses into so-called jobs - each of them corresponds to a Biomoby query (a Biomoby single network request may contain more queries/jobs).

Any client can override various methods - but the ones she/he must override in a subclass are those telling what service to call (getServiceLocator()), what data to put in a request (fillRequest), and what to do with a response (useResponse.

Version:

$Id: BaseClient.java,v 1.14 2008/12/03 15:21:13 groscurt Exp $

Author:

Martin Senger

Constructor Summary

BaseClient()

Method Summary

String	callRemoteService(String xmlInput) Call a SOAP-based BioMoby service.
String	errorsInResponse(String xmlResponse) Extracts errors from a raw service response.
String	fillRequest() Create raw XML input.
abstract boolean	fillRequest(MobyJob request, MobyPackage inputContext) Crate data (fill them into 'request') for one Moby job (query).
boolean	fillRequest(MobyPackage mobyInput, int jobCount) Fill the whole 'mobyInput' - put there any number of jobs (queries) as you wish (you do not need to follow the 'jobCount' hint suggesting how many jobs should be put there).
abstract MobyServiceLocator	getServiceLocator() Return characteristics of a BioMoby service that will be called, and that reveal where to find such service.
String	interceptRequest(String xmlInput)
void	process() The main method that packs input data, invokes a BioMoby service and uses its response.
void	process(int jobCount) The main method that packs input data, invokes a BioMoby service and uses its response.
abstract boolean	useResponse(MobyJob response, MobyPackage responseContext) Process a single job returned from a BioMoby service.
void	useResponse(MobyPackage mobyResponse) A high-level processing.
boolean	useResponse(String xmlResponse) A raw-level processing.

Methods inherited from class java.lang.Object

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

Constructor Detail

BaseClient

public BaseClient()

Method Detail

process

public void process()
             throws MobyException

The main method that packs input data, invokes a BioMoby service and uses its response. Use this method if the input data should have just one job (which is a usual case) - otherwise use method process(int).

Throws:

MobyException - if (a) a sub-class throws it during the filling data or using response, or (b) a Biomoby service invocation fails

process

public void process(int jobCount)
             throws MobyException

The main method that packs input data, invokes a BioMoby service and uses its response. The input data may consist from more than one job (query) - the 'jobCount' is a suggestion how many jobs will be included, but this can be changed by the implementing sub-class.

Usually a client developer does not need to overwrite this method. She or he makes the real input data filling in the fillRequest() method, and uses the response in the useResponse(java.lang.String) method.

Throws:

MobyException - if (a) a sub-class throws it during the filling data or using response, or (b) a Biomoby service invocation fails

interceptRequest

public String interceptRequest(String xmlInput)
                        throws MobyException

Throws:

MobyException

fillRequest

public String fillRequest()
                   throws MobyException

Create raw XML input. Override this method if you have already an input XML, or you want to create it yourself.

Returns:

a full XML input for a Biomoby service (in this case no other fillRequest methods will called); return null if no XML was created and a usual process to gather it will be used

Throws:

MobyException - if an XML cannot be created

callRemoteService

public String callRemoteService(String xmlInput)
                         throws MobyException

Call a SOAP-based BioMoby service. In order to find what service to call and what are its characteristics (such as its endpoint) it will call method getServiceLocator() that should be implemented by a sub-class.

Once it has the service locator, this class does one of the following, in this order:

• The locator must contain at least a service name. If it does not, an exception is raised.
• If the locator contains a service endpoint, a call is made to this endpoint, using also the service name as a method name.
• If the locator has a registry endpoint, an enquiry to the registry is made to find an endpoint of a service corresponding with the given service name. Once found, the service is called.
• The same as the previous one but using a default registry.

  Parameters:

  xmlInput - data will be sent to the called Biomoby service

  Returns:

  service response (still in XML)

  Throws:

  MobyException - (a) if service call (or a call to registry; for example because the registry does not know given service) fails, or (b) if the used MobyServiceLocator does not contain a service name.

fillRequest

public boolean fillRequest(MobyPackage mobyInput,
                           int jobCount)
                    throws MobyException

Fill the whole 'mobyInput' - put there any number of jobs (queries) as you wish (you do not need to follow the 'jobCount' hint suggesting how many jobs should be put there).

Usually there is not need to overwrite this method. It serves as an inter-mediator between the main process() method and the individual request fillings (done by a sub-class in method fillRequest(MobyJob,MobyPackage)).

Parameters:

mobyInput - is an empty shell that you are supposed to fill with the input data for a Biomoby service execution

jobCount - is only a suggestion how many requests/job should be created (it comes from the process() method) - but it does not need to be obeyed

Returns:

false if you wish to cancel whole request (nothing will be sent to a Biomoby service); otherwise return true.

Throws:

MobyException

useResponse

public boolean useResponse(String xmlResponse)
                    throws MobyException

A raw-level processing. Use it if you need access to raw XML coming from a service.

Parameters:

xmlResponse - is a raw XML response returned from a BioMoby service

Returns:

false if the response should be considered fully processed (in this case no other 'useResponse' will be called); true indicates that normal processing of the response will follow; by default, this class (BaseClient) returns true

Throws:

MobyException - if you are not satisfied with a response data, or from whatever reasons; it also throws this exception if the 'mobyResponse' is broken

useResponse

public void useResponse(MobyPackage mobyResponse)
                 throws MobyException

A high-level processing. Use it if you need access to all jobs (queries) - that returned from a service - in the same time. Otherwise use the processing on the job level (method useResponse(MobyJob,MobyPackage).

Parameters:

mobyResponse - is a full response returned from a BioMoby service

Throws:

MobyException - if you are not satisfied with a response data, or from whatever reasons; it also throws this exception if the 'mobyResponse' is broken

errorsInResponse

public String errorsInResponse(String xmlResponse)

Extracts errors from a raw service response. It is iseful when one does not want to create a whole MobyPackage from a response, but just find whether a response is good or bad.

Parameters:

xmlResponse - is a full response returned from a BioMoby service

Returns:

a slightly formatted list of exceptions (of severity error) extracted from the response; or null if there are no errors there

getServiceLocator

public abstract MobyServiceLocator getServiceLocator()
                                              throws MobyException

Return characteristics of a BioMoby service that will be called, and that reveal where to find such service.

Returns:

an object defining a location of a BioMoby service

Throws:

MobyException - if service locator cannot be returned/created (e.g. because there is not enough information about what service to call)

See Also:

callRemoteService(java.lang.String)

fillRequest

public abstract boolean fillRequest(MobyJob request,
                                    MobyPackage inputContext)
                             throws MobyException

Crate data (fill them into 'request') for one Moby job (query). The request will be sent within given 'inputContext' - but it is not yet there (because you may wish not to put it there - see the return value), and it is not the task of this method to put it there (just fill the 'request').

This is a method that should be implemented by a client developer, and it is the place where the client's business logic sits.

Parameters:

request - is an object that you are supposed to fill with input data for one service invocation; it already has a name (so called 'query id' in the BioMoby speak) but you are free to change it

inputContext - is an envelope where all requests will be stored and sent to a Biomoby service; you do not need to do anything with it here unless you wish; note that all already created requests are there, but not the one you are just creating in this method

Returns:

true if this request should be included into the input data (package) that will be sent to a biomoby service; or return false if you do not wish to create any more requests for this particular package (also this 'request' will not be used)

Throws:

MobyException - if you need so (from whatever reason in your business logic); if thrown then nothing will be sent to a Biomoby service

useResponse

public abstract boolean useResponse(MobyJob response,
                                    MobyPackage responseContext)
                             throws MobyException

Process a single job returned from a BioMoby service.

This is a method that should be implemented by a client developer, and it is the place where the client's business logic using the response sits.

Parameters:

response - is an object that you are supposed to use

responseContext - is an envelope where the full response (all its jobs) is located; you do not need to do anything with it here unless you wish (e.g. it gives you knowledge about how many jobs are in the full response, or it gives you access to the so-called 'service notes')

Returns:

false if you do not wish to get any more responses/jobs; otherwise return true

Throws:

MobyException - if you are not satisfied with a response data, or from whatever reasons; it also throws this exception if the 'response' is broken