org.biomoby.shared.parser
Class MobyJob

java.lang.Object
  org.biomoby.shared.parser.MobyJob

public class MobyJob
extends Object

This class represents one 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.

Each job is identified (within a service request or response) by its id (methods getId() and setId(java.lang.String), or a constructor MobyJob(java.lang.String)).

The main contents of each job are data elements. They can represent either a Simple element, a Collection, or a Parameter. The class has many methods to find and get these data elements. The best is to find them by name but unfortunately not all of them have always a name. Therefore, some methods of this class try to apply some heuristics to locate the most probable data lement.

Version:

$Id: MobyJob.java,v 1.7 2006/05/09 13:32:09 senger Exp $

Author:

Martin Senger

Constructor Summary

MobyJob()
Default constructor.

MobyJob(String id)
Another constructor, naming this job by an id.

Method Summary

void	addData(MobyObject data) Create an un-named Simple object and add it as the last one in the current data elements.
void	addData(MobyObject data, String name) Create a named Simple object and add it as the last one in the current data elements.
void	addDataElement(MobyDataElement dataElement) Add 'dataElement' to this job.
void	addDataSet(MobyObject[] data) Create an un-named Collection object and add it as the last one in the current data elements.
void	addDataSet(MobyObject[] data, String name) Create a named Collection object and add it as the last one in the current data elements.
String	format(int indent) Return the same contents as toString() method but indented by level expressed in the parameter 'indent'.
MobyObject	getData() Find and return the first data element of type Simple (which may not be the first data element in this job).
MobyObject	getData(String name) Find and return a data element of a Simple type that is named by 'name'.
MobyObject	getData(String name, String dataTypeName) Find and return a data element of a Simple type that is named by 'name' and has data type 'dataTypeName'.
MobyDataElement[]	getDataElements() Return all data elements stored in this job.
MobyObject[]	getDataSet() Find and return the first data element of type Collection (which may not be the first data element in this job).
MobyObject[]	getDataSet(int index) Find and return the 'index'-th data element, assuming that it is a Collection data element.
MobyObject[]	getDataSet(String name) Find and return a data element of a Collection type that is named by 'name'.
MobyObject[]	getDataSet(String name, String dataTypeName) Find and return a data element coming from a Collection type that is named by 'name' and has data type 'dataTypeName'.
String	getId()
String	getParameter(String name) Find a Parameter object named by 'name', and return its value.
void	setData(MobyObject data) Create an un-named Simple object as the first data element.
void	setData(MobyObject data, String name) Create a named Simple object as the first data element.
void	setData(MobyObject data, String name, int index) Create a named Simple object and put it as the 'index'-th data element.
void	setDataElements(MobyDataElement[] dataElements) Replace all current data elements (if any) by the new ones.
void	setDataSet(MobyObject[] data) Create an un-named Collection object as the first data element.
void	setDataSet(MobyObject[] data, String name) Create a named Collection object as the first data element.
void	setDataSet(MobyObject[] data, String name, int index) Create a named Collection object and put it as the 'index'-th data element.
void	setId(String id) Set a "query id" that identifies this job uniquely within a client request or a service response.
void	setParameter(String name, String value) Set secondary parameter 'name' to 'value'.
int	size() Return a number of data elements contained in this job.
String	toString() Format all non-empty public members in a human-readable way.
org.jdom.Element	toXML() Create an XML element representing this object.
static org.jdom.Element	toXML(String jobId, org.jdom.Element[] data) Create an XML element representing this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

MobyJob

public MobyJob()

Default constructor.

MobyJob

public MobyJob(String id)

Another constructor, naming this job by an id.

Method Detail

getDataSet

public MobyObject[] getDataSet(int index)
                        throws MobyException

Find and return the 'index'-th data element, assuming that it is a Collection data element. The index starts from zero, and both Simples and Collections elements are counted together.

Note that the BioMoby API does not dictate any order on the data elements. Therefore, this method is not public, and it is used from all other getData methods only.

Parameters:

index - of the data element to be returned (a negative index is changed to zero)

Throws:

MobyException - if the index-th data element is not a Collection, or if the index is too large

toString

public String toString()

Format all non-empty public members in a human-readable way.

Overrides:

toString in class Object

Returns:

a formatted string

See Also:

for making the returned string better indented

format

public String format(int indent)

Return the same contents as toString() method but indented by level expressed in the parameter 'indent'. It is useful when a hierarchy of objects call toString methods on their children/members. For example, in order to list all data elements in a MobyJob object, the method toString in MobyJob includes code like this:

  StringBuffer buf = new StringBuffer();
  for (Enumeration en = dataElements.elements(); en.hasMoreElements(); )
    buf.append (((MobyDataElement)en.nextElement()).format (1));

Parameters:

indent - means a level of wanted indentation: number 1 means three spaces, number two six spaces, etc.

Returns:

a formatted, and indented, string

toXML

public org.jdom.Element toXML()

Create an XML element representing this object.

Returns:

a jDom element that can be easily incorporated into bigger a XML document

toXML

public static org.jdom.Element toXML(String jobId,
                                     org.jdom.Element[] data)

Create an XML element representing this object.

Returns:

a jDom element that can be easily incorporated into bigger a XML document

setId

public void setId(String id)

Set a "query id" that identifies this job uniquely within a client request or a service response.

Parameters:

id - to be stored. If it is null, an empty string is stored instead.

getId

public String getId()

See Also:

setId(java.lang.String)

size

public int size()

Return a number of data elements contained in this job.

setDataElements

public void setDataElements(MobyDataElement[] dataElements)

Replace all current data elements (if any) by the new ones.

addDataElement

public void addDataElement(MobyDataElement dataElement)

Add 'dataElement' to this job.

getDataElements

public MobyDataElement[] getDataElements()

Return all data elements stored in this job. There are also convenient methods to return just some data elements (by name, by index, etc.).

getData

public MobyObject getData()
                   throws MobyException

Find and return the first data element of type Simple (which may not be the first data element in this job).

Returns:

null if no such data element was found

Throws:

MobyException - if there was an internal error

getData

public MobyObject getData(String name)
                   throws MobyException

Find and return a data element of a Simple type that is named by 'name'. This is how it tries to find the element:

1. Try to find a Simple with an article name equals to 'name'.
2. If it fails, count how many unnamed Simple data elements are present. If only one, return it.

Parameters:

name - is an article name we are looking for

Returns:

found data element or null

Throws:

MobyException - if there was an internal error

getData

public MobyObject getData(String name,
                          String dataTypeName)
                   throws MobyException

Find and return a data element of a Simple type that is named by 'name' and has data type 'dataTypeName'. This is how it tries to find the element:

1. Try to find a Simple element matching both the article name ('name') and a data type ('dataTypeName').

2. If it fails, try to find an unnamed Simple data element matching just the data type.

3. Return null.

For example: If a service expects two inputs, one String and one Integer, but any of them, or both actually, can be missing, use

getData ("", "String")

and

getData ("", "Integer")

and test results for null values. We use en ampty article names here because there cannot be any confusion (there are no more String or Integer types inputs). However, if the same service was registered with article names, it is better to use them (and if a client does not use them the data will be found anyway).

Parameters:

name - is an article name we are looking for

dataTypeName - is a simple (unqualified) class name. For example, for a data type represented by a Java class org.biomoby.shared.datatypes.GenericSequence put here just GenericSequence. For the BioMoby primitive types, put them either their simple, unqualified class name (such as MobyString), or their native BioMoby name (such as String.

Returns:

found data element or null

Throws:

MobyException - if there was an internal error

setData

public void setData(MobyObject data)
             throws MobyException

Create an un-named Simple object as the first data element.

Throws:

MobyException

setData

public void setData(MobyObject data,
                    String name)
             throws MobyException

Create a named Simple object as the first data element.

Throws:

MobyException

setData

public void setData(MobyObject data,
                    String name,
                    int index)
             throws MobyException

Create a named Simple object and put it as the 'index'-th data element. Expand data elements by empty Simple objects if the index is out of bounds.

Throws:

MobyException

addData

public void addData(MobyObject data)
             throws MobyException

Create an un-named Simple object and add it as the last one in the current data elements.

Throws:

MobyException

addData

public void addData(MobyObject data,
                    String name)
             throws MobyException

Create a named Simple object and add it as the last one in the current data elements.

Throws:

MobyException

getDataSet

public MobyObject[] getDataSet()
                        throws MobyException

Find and return the first data element of type Collection (which may not be the first data element in this job).

Returns:

null if no such data element was found

Throws:

MobyException - if there was an internal error

getDataSet

public MobyObject[] getDataSet(String name)
                        throws MobyException

Find and return a data element of a Collection type that is named by 'name'. This is how it tries to find the element:

1. Try to find a Collection with an article name equals to 'name'.
2. If it fails, count how many unnamed Collection data elements are present. If only one, return it.

Parameters:

name - is an article name we are looking for

Returns:

found data element or null

Throws:

MobyException - if there was an internal error

getDataSet

public MobyObject[] getDataSet(String name,
                               String dataTypeName)
                        throws MobyException

Find and return a data element coming from a Collection type that is named by 'name' and has data type 'dataTypeName'. This is how it tries to find the element:

1. Try to find a collection element matching both the article name ('name') and a data type ('dataTypeName'). Matching means that the first element of this collection matches.

2. If it fails, try to find an unnamed Collection data element matching just the data type. Again, matching is done for an element of this collection.

3. If it fails, and if here given 'name' is empty, try to find any Collection data element matching the data type. (I am not sure that this rule is what we want...)

4. Return null.

Parameters:

name - is an article name we are looking for

dataTypeName - is a simple (unqualified) class name. For example, for a data type represented by a Java class org.biomoby.shared.datatypes.GenericSequence put here just GenericSequence. For the BioMoby primitive types, put them either their simple, unqualified class name (such as MobyString), or their native BioMoby name (such as String.

Returns:

found data element or null

Throws:

MobyException - if there was an internal error

setDataSet

public void setDataSet(MobyObject[] data)
                throws MobyException

Create an un-named Collection object as the first data element.

Throws:

MobyException

setDataSet

public void setDataSet(MobyObject[] data,
                       String name)
                throws MobyException

Create a named Collection object as the first data element.

Throws:

MobyException

setDataSet

public void setDataSet(MobyObject[] data,
                       String name,
                       int index)
                throws MobyException

Create a named Collection object and put it as the 'index'-th data element. Expand data elements by empty Simple objects if the index is out of bounds. The individual elements of the collection get (article) names from the individual 'data' objects.

Throws:

MobyException

addDataSet

public void addDataSet(MobyObject[] data)
                throws MobyException

Create an un-named Collection object and add it as the last one in the current data elements.

Throws:

MobyException

addDataSet

public void addDataSet(MobyObject[] data,
                       String name)
                throws MobyException

Create a named Collection object and add it as the last one in the current data elements.

Throws:

MobyException

getParameter

public String getParameter(String name)
                    throws MobyException

Find a Parameter object named by 'name', and return its value. Note that all Parameters should have name.

Parameters:

name - is an article name we are looking for

Returns:

found parameter, or null

Throws:

MobyException - if 'name' represents a different type of data element (not a parameter)

setParameter

public void setParameter(String name,
                         String value)

Set secondary parameter 'name' to 'value'.

Parameters:

name - of a secondary paraneter to be set

value - to be set