* * This base class does not contain any service-specific entities. It * serves all Biomoby services. The service-specific features (notably * the method that is called when a service is invoked) are in the * generated service skeletons (a separate skeleton for every * service). A service provider extends a service skeleton by her/his * own class that implements service business logic but does not need * to deal with the Biomoby protocol/envelope at all.
* * Here is the basic inheritance picture of involved classes for a * Biomoby service registerd (in a Biomoby registry) under the name * "A_Service":
* * A typical generated skeleton (for service "A_Service") would look * like this:
* *
abstract public class A_ServiceSkel
extends BaseService {
public String A_Service (Object data) {
try {
// reading the whole input
MobyPackage mobyInput = MobyPackage.createFromXML (data);
// prepare an output object
MobyPackage mobyOutput = prepareOutput (mobyInput);
// do the main job
processIt (mobyInput, mobyOutput);
// and return an XML back
return mobyOutput.toXML();
} catch (MobyException e) {
return error (e.getMessage());
}
}
}
* |
* * While a service provider class (implemented manually) could look * like this (its name is arbitrary):
* *
public class AServiceImpl
extends A_ServiceSkel {
public void processIt (MobyJob request,
MobyJob response,
MobyPackage outputContext)
throws MobyException {
// this is how to get input data
GenericSequence input = get_GenericSequence (request);
String seq = input.get_SequenceString();
// this is an example of a trivial "business logic"
response.setData (new MobyInteger (seq.length()));
}
}
* |
* * Note that this particular service uses an input object of type * GenericSequence and an output object of type * Integer - but if a more specific object, such as a * NucleotideSequence comes from a client, it will handle it * properly.
* * @author Martin Senger * @version $Id: BaseService.java,v 1.9 2008/03/02 12:45:26 senger Exp $ */ abstract public class BaseService { // communication with the surrounding SOAP toolkit (shared by all // instances); if not used in a servlet context, this toolkit // finds parameters in system properties protected static SOAPToolkit toolkit; /************************************************************************** * Default constructor. **************************************************************************/ public BaseService() { try { // toolkit may be already initialized by a previous instance // (we need only one instance - but someone may have deployed // this with a different scope, such as "request" or // "session") which would lead to more instances of this // (which I hope does not do any harm) if (toolkit == null) toolkit = SoapUtils.loadSOAPToolkit(); } catch (GException e) { // TBD: substitute with a message to a log System.err.println ("Cannot load SOAP toolkit: " + e.getMessage()); } } /************************************************************************** * Return a list containing the parameter names available within * the context of the invoked web service together with the global * context.
* * Any web service (deployed within a reasonable environment, such * as Apache Axis) can be deployed with some initialization * parameters that are static (they do not change during the Web * Service) and they are, of course, not changeable not even * visible to the service clients. Typical example would be * parameters needed for a JDBC connection (JDBC URL, user name, * password etc.).
*
* @return a list of available parameter names. If this class is
* not used within a servlet container (which may be during its
* testing) it return names of system properties.
*
* @see #getParam
**************************************************************************/
public String[] getParamNames() {
// toolkit can be null if the constructor failed to load it -
// but I want to keep the constructor of this class without
// any throwing exception, so I simulate here what toolkit can do
if (toolkit == null) {
List
*
* @param name of a parameter
* @return a value of the named parameter, or null if the
* parameter does not exist; note that when run not in a servlet
* container the returned value is looked for in the system
* properties instead
**************************************************************************/
public String getParam (String name) {
// toolkit can be null if the constructor failed to load it -
// but I want to keep the constructor of this class without
// any throwing exception, so I simulate here what toolkit can do
if (toolkit == null) {
return System.getProperty (name);
}
return toolkit.getAttribute (name);
}
/**************************************************************************
* Return a toolkit that gives you broader access to the
* environment where this service is deployed in. Especially it is
* useful for session management.
*
* See details what a toolkit can provide in
* org.tulsoft.tools.soap.SOAPToolkit.
*************************************************************************/
public SOAPToolkit getToolkit() {
return toolkit;
}
/**************************************************************************
* Returns a servlet request instance - the one that delivered a
* request to this service.
*
* @return a servlet request, or null if the request is not
* available
*************************************************************************/
public HttpServletRequest getServletRequest() {
MessageContext ctx = MessageContext.getCurrentContext();
if (ctx == null)
return null;
HttpServletRequest req =
(HttpServletRequest)ctx.getProperty (HTTPConstants.MC_HTTP_SERVLETREQUEST);
return req;
}
/**************************************************************************
* Returns the Internet Protocol (IP) address of the client or
* last proxy that sent the request.
*
* @return the caller address or null if the address is unknown
*************************************************************************/
public String getCallerAddr() {
MessageContext ctx = MessageContext.getCurrentContext();
if (ctx == null)
return null;
HttpServletRequest req =
(HttpServletRequest)ctx.getProperty (HTTPConstants.MC_HTTP_SERVLETREQUEST);
return req.getRemoteAddr();
}
/**************************************************************************
* Returns HTTP headers that were used when delivering a request
* to this services.
*
* @return a set of name-value pairs representinh HTTP headers; if
* the headers are not accessible, an empty set is returned (never
* null)
*************************************************************************/
public Properties getHTTPHeaders() {
Properties headers = new Properties();
MessageContext ctx = MessageContext.getCurrentContext();
if (ctx == null)
return headers;
HttpServletRequest req =
(HttpServletRequest)ctx.getProperty (HTTPConstants.MC_HTTP_SERVLETREQUEST);
if (req == null)
return headers;
for (Enumeration en = req.getHeaderNames(); en.hasMoreElements(); ) {
String headerName = (String)en.nextElement();
String headerValue = req.getHeader (headerName);
if (headerValue != null)
headers.put (headerName, headerValue);
}
return headers;
}
/**************************************************************************
* Returns length (in bytes) of the request coming to this service.
*
* The length is taken from the HTTP headers. This is only a
* convenient method extracting one header from those available by
* the {@link #getHTTPHeaders getHTTPHeaders}. >p>
*
* @return a length of the request, or zero if the request length
* is not available
*************************************************************************/
public int getRequestLength() {
MessageContext ctx = MessageContext.getCurrentContext();
if (ctx == null)
return 0;
HttpServletRequest req =
(HttpServletRequest)ctx.getProperty (HTTPConstants.MC_HTTP_SERVLETREQUEST);
if (req == null)
return 0;
try {
return new Integer (req.getHeader ("content-length")).intValue();
} catch (Exception e) {
return 0;
}
}
/**************************************************************************
* A utility method returning true if 'value' is neither null nor
* a string consisting only from whitespaces.
*************************************************************************/
public static boolean notEmpty (String value) {
return ( value != null && ! "".equals (value.trim()) );
}
/**************************************************************************
* A utility method returning true if 'value' is either null or a
* string consisting only from whitespaces.
*************************************************************************/
public static boolean isEmpty (String value) {
return ! notEmpty (value);
}
/**************************************************************************
* Error handling.
*
* This method produces an empty (no data) response with the
* 'message' in its service notes tag. Whatever is returned by
* this method is send back to the client. So if you override it,
* you must return back an XML (if you wish the Biomoby client to
* understand/parse it).
*
* @param message is a reason why this method was called in the
* first place; it is a good practise to incorporate it (somehow)
* in the return value
*
* @param outputSoFar is a so-far-filled response (it may be
* null); you may consider to use it and to fill its service notes
* tag with the 'message', or you can ignore it and create your
* own error response
*
* @return an XML (hopefully Biomoby compliant) response
*************************************************************************/
public String error (String message, MobyPackage outputSoFar) {
if (outputSoFar == null)
outputSoFar = new MobyPackage();
outputSoFar.addException
(ServiceException.error ("AN ERROR OCCURED DURING THE SERVICE EXECUTION: "
+ message));
return outputSoFar.toXML();
}
/**************************************************************************
* Return a package that has the same number of jobs
* (and named the same) as the given input. But otherwise it is empty.
*
* Usually, there is no need to override this method. It is called
* by a service skeleton, once an input XML is parsed and before a
* service implementation class is called to process it.
*
* @param mobyInput contains all data coming from a client
* @return an empty package that will later go back to the client
* @throws MobyException if input data package is corrupted
*************************************************************************/
public MobyPackage prepareOutput (MobyPackage mobyInput)
throws MobyException {
MobyPackage mobyOutput = new MobyPackage();
// iterate over all input jobs
for (int i = 0; i < mobyInput.size(); i++) {
mobyOutput.addJob
(new MobyJob (mobyInput.getJob (i).getId()));
}
return mobyOutput;
}
/**************************************************************************
* A high-level processing. Override this method if you need
* access to all jobs in the same time. Otherwise use the {@link
* #processIt(MobyJob,MobyJob,MobyPackage) processessig on the job
* level}.
*
* @param mobyInput contain all data coming from a client
* @param mobyOutput is an empty package that will go later to the
* client; this method should fill it with a response
*
* @throws MobyException if processing failed; in which case the
* caller of this method (which is usually a generated skeleton)
* will probably call the {@link #error} method
*************************************************************************/
public void processIt (MobyPackage mobyInput, MobyPackage mobyOutput)
throws MobyException {
// iterate over all input jobs
for (int i = 0; i < mobyInput.size(); i++) {
processIt (mobyInput.getJob (i),
mobyOutput.getJob (i),
mobyOutput);
}
}
/**************************************************************************
* A job-level processing: This is the main method to be
* overriden by a service provider!. Here all the business
* logic belongs.
*
* This method is called once for each job in a client
* request. A {@link org.biomoby.shared.parser.MobyJob job} is a
* BioMoby query (in a client request), or a result of one query
* (in a service response). There can be more queries (jobs) in
* one network request to a BioMoby service. If a network request
* contains more jobs, also the corresponding service response
* must contain the same number of jobs.
*
* @param request contain data coming from one client's job
*
* @param response is an empty object (except its name that is
* already filled in - because it must correspond with the same
* name in the 'request'); this method should fill it with a
* response
*
* @param outputContext is a package that will be, at the end,
* delivered to the client; it is here not to be filled - that is
* taken care of by some other methods - but you may use it to see
* how other (previous) jobs have been made, and also to add
* things to the package envelope (e.g. service notes)
*
* @throws MobyException if a complete processing failed; after
* this exception the client will not get any data back (only an
* error message). If you wish just to indicate that only this
* particular job failed you have to add an exception to the
* outputContext - see {@link
* MobyPackage#addException(ServiceException,MobyJob)}.
*************************************************************************/
abstract public void processIt (MobyJob request,
MobyJob response,
MobyPackage outputContext)
throws MobyException;
}