org.biomoby.client
Class MobyRequest

java.lang.Object
  org.biomoby.client.MobyRequest

public class MobyRequest
extends Object

This class handles the WSDL transaction to request a response from a remote SOAP Web service that handles the MOBY format. It depends on having already retrieved the definition of the Web service via the MOBY central registry using the jMOBY API, and for now it uses the Apache Axis Web services framework, as well as Apache Xalan. There are code comments for the few lines that rely on Axis classes rather than the JAX-RPC interfaces.

Author:

Paul Gordon gordonp@ucalgary.ca

Constructor Summary

MobyRequest(Central central)
Default constructor.

Method Summary

void	addEventHandler(MobyRequestEventHandler h)
String	convertMOBYDataToMOBYRequest(MobyContentInstance data) Creates an XML representation of the data, renamed to fit the needs of the service if necessary, and adding any secondary parameter default values if not already specified in the incoming data.
String	convertMOBYDataToMOBYRequest(MobyDataInstance data)
Element	decodeSOAPMessage(Element n, StringBuffer contentsXMLOutput, String inputXML)
Element	decodeSOAPMessage(Element n, StringBuffer contentsXMLOutput, String inputXML, boolean async) Isolates the MOBY Data from the SOAP message returned by the remote service host.
Central	getCentralImpl()
MobyContentInstance	getInput()
MobyContentInstance	getOutput()
String	getResponseXML()
MobyService	getService()
MobyContentInstance	invokeService() The main method of the class.
int	invokeService(MobyRequestEventHandler handler) Asynchronous call to invokeService.
void	removeEventHandler(MobyRequestEventHandler h)
void	sendResponse(MobyRequestEvent mre)
void	setAuthentication(String user, String password)
void	setDebugMode(boolean mode)
void	setDebugPrintStream(PrintStream ps) Standard error is used unless this method is called.
void	setInput(MobyContentInstance data) Sets the input data for the MOBY service request.
void	setInput(MobyDataInstance datum) Convenience method to run services that take one argument.
void	setInput(MobyDataInstance[] data) Takes the data in the array, with their current articleNames, as input for the service
void	setInput(MobyDataInstance datum, String paramName) Convenience method to run services that take one named argument.
void	setSecondaryInput(Collection<MobyDataSecondaryInstance> secondaryData) Same functionality as setSecondaryInput(MobyDataSecondaryInstance[])
void	setSecondaryInput(MobyDataSecondaryInstance[] secondaryData) This method will assign the provided secondary parameters to all primary input data currently in this object.
void	setService(MobyService mobyservice)

Methods inherited from class java.lang.Object

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

Constructor Detail

MobyRequest

public MobyRequest(Central central)
            throws ParserConfigurationException

Default constructor. You should have a Central instance around since you're going to be retrieving MobyServices to pass into here. Lets reuse it.

Parameters:

central - An instance of a Moby central object so we can make requests about object types, etc.

Throws:

ParserConfigurationException - if JAXP doesn't have any valid DOM-building XML parsers set up for use

Method Detail

setAuthentication

public void setAuthentication(String user,
                              String password)

setDebugMode

public void setDebugMode(boolean mode)

Parameters:

mode - if true, debugging information is printed to the stream returned by getDebugOutputStream

setDebugPrintStream

public void setDebugPrintStream(PrintStream ps)
                         throws IllegalArgumentException

Standard error is used unless this method is called.

Parameters:

ps - the OutputStream to which debugging information is sent.

Throws:

IllegalArgumentException - if the stream is null

getCentralImpl

public Central getCentralImpl()

Returns:

the instance of the class implementing Central that we are using

setService

public void setService(MobyService mobyservice)

Parameters:

mobyservice - the MobyService that should be executed when invokeService is called

getService

public MobyService getService()

Returns:

the MobyService that will be executed when invokeService is called

getResponseXML

public String getResponseXML()

Returns:

the Raw MOBY XML response as a string

setInput

public void setInput(MobyContentInstance data)
              throws MobyException

Sets the input data for the MOBY service request. The length of the input array, and the number of input parameters required by the service must be equal when invokeService() is called. This method strictly enforces that the input be of the appropriate type for the service. Note that there is no requirement to use MobyDataInstance.setXmlMode() before passing in data, this class will temporarily set the XML mode of the data when it is required.

Throws:

IllegalArgumentException - if the input does not fit the criteria of the service (e.g. wrong data type)

MobyException

setInput

public void setInput(MobyDataInstance[] data)
              throws MobyException

Takes the data in the array, with their current articleNames, as input for the service

Throws:

MobyException

setInput

public void setInput(MobyDataInstance datum)
              throws MobyException

Convenience method to run services that take one argument. If the service requires the input to have a name, it will be automatically assigned.

Throws:

MobyException

setInput

public void setInput(MobyDataInstance datum,
                     String paramName)
              throws MobyException

Convenience method to run services that take one named argument.

Throws:

MobyException

getInput

public MobyContentInstance getInput()

Returns:

the MobyService that will be executed when invokeService is called

setSecondaryInput

public void setSecondaryInput(Collection<MobyDataSecondaryInstance> secondaryData)
                       throws MobyException

Same functionality as setSecondaryInput(MobyDataSecondaryInstance[])

Throws:

MobyException

setSecondaryInput

public void setSecondaryInput(MobyDataSecondaryInstance[] secondaryData)
                       throws MobyException

This method will assign the provided secondary parameters to all primary input data currently in this object. This is convenient if you are running 100 seqs through BLAST and only want to set the parameters once. If you instead want to set secondary input differently for all primary inputs, you'll need to create a custom MobyContentInstance as input to setInput().

Throws:

MobyException - if a parameter name is blank, or overrides a primary parameter

getOutput

public MobyContentInstance getOutput()
                              throws MobyException

Returns:

a vector of MobyDataInstance[], each element of the vector is the collection of response objects for the correspondingly indexed input request.

Throws:

MobyException - if you try to get the results before calling InvokeService

invokeService

public MobyContentInstance invokeService()
                                  throws Exception,
                                         MobyException,
                                         SOAPException,
                                         NoSuccessException

The main method of the class. If all of the MOBY input objects are properly defined according to the Web service definition, a SOAP request will be sent to the remote server, and the method will return one or more MOBY objects (synchronous). Call this method after calling setService, and setInput. If you do not call setSecondaryInput, the default secondary parameter values will be used.

Returns:

the results of the remote Web service in response to the give input

Throws:

MobyException - i.e. there was something wrong with the input, output or remote service's logic

SOAPException - i.e. there was a problem with the underlying transaction/transport layer

Exception

NoSuccessException

invokeService

public int invokeService(MobyRequestEventHandler handler)

Asynchronous call to invokeService. A callback to the passed-in handler will be made when the response is ready, or there is an exception.

Returns:

the id that the callback event will return from getID(), allowing a client to distinguish between multiple concurrent invocation callbacks

addEventHandler

public void addEventHandler(MobyRequestEventHandler h)

removeEventHandler

public void removeEventHandler(MobyRequestEventHandler h)

sendResponse

public void sendResponse(MobyRequestEvent mre)

decodeSOAPMessage

public Element decodeSOAPMessage(Element n,
                                 StringBuffer contentsXMLOutput,
                                 String inputXML)
                          throws SOAPException,
                                 MobyException

Throws:

SOAPException

MobyException

decodeSOAPMessage

public Element decodeSOAPMessage(Element n,
                                 StringBuffer contentsXMLOutput,
                                 String inputXML,
                                 boolean async)
                          throws SOAPException,
                                 MobyException

Isolates the MOBY Data from the SOAP message returned by the remote service host.

Returns:

The root element of the MOBY response DOM

Throws:

SOAPException - if the MOBY payload cannot be found in the SOAP message

MobyException - if the MOBY message is not well-formed XML

convertMOBYDataToMOBYRequest

public String convertMOBYDataToMOBYRequest(MobyDataInstance data)
                                    throws MobyException

Throws:

MobyException

convertMOBYDataToMOBYRequest

public String convertMOBYDataToMOBYRequest(MobyContentInstance data)
                                    throws MobyException

Creates an XML representation of the data, renamed to fit the needs of the service if necessary, and adding any secondary parameter default values if not already specified in the incoming data.

Parameters:

data - the array of input parameters to put in a MOBY XML request

Returns:

the XML representation of the input data

Throws:

MobyException