org.biomoby.shared.parser
Class MobyPackage

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

public class MobyPackage
extends Object

This is the main container for Biomoby data once they are extracted from an XML format. It represents the package either sent from a client to a Biomoby service, or vice-versa. It also includes methods for parsing data from XML and for creating data back into XML.

Version:

$Id: MobyPackage.java,v 1.8 2008/02/28 05:21:48 senger Exp $

Author:

Martin Senger

Constructor Summary

MobyPackage()
Default constructor.

MobyPackage(MobyObject mObj, String articleName)
Constructing a simplest MobyPackage - with one MobyObject.

Method Summary

void	addException(ServiceException error) Add a new exception reported by this service execution.
void	addException(ServiceException error, MobyJob job) Add a new exception reported by this service execution.
void	addJob(MobyJob job) Add one job to the already stored here.
static MobyPackage	createFromXML(Object xmlData) Constructing a MobyPackage object from XML.
static MobyPackage	createFromXML(Object xmlData, Map<String,String> lowestKnownDataTypes) Constructing a MobyPackage object from XML.
static MobyPackage	createFromXML(Object xmlData, String lowestKnownDataType) Constructing a MobyPackage object from XML.
String	evaluateExceptions(org.apache.commons.logging.Log log, boolean throwException) Evaluate current exceptions.
String	format(int indent) Return the same contents as toString() method but indented by level expressed in the parameter 'indent'.
String	getAuthority() Get back the authority serving this package.
ServiceException[]	getExceptions() Return all so far set exceptions.
MobyJob	getJob(int index) Get back a job indicated by its order number.
MobyJob[]	getJobs() Get back all jobs stored here.
String	getServiceNotes() Get back service notes.
static org.jdom.Element	getXMLElement(String name) Return a jDOM XML element equipped with the BioMoby namespace.
boolean	hasAnError() Return true if this package contains at least one exception of the severity ServiceException.ERROR).
void	setAuthority(String authority) Fill in an authority of this whole package.
void	setExceptions(ServiceException[] errors) Set one or more exceptions reported by this service invocation.
void	setJobs(MobyJob[] jobs) Store here all jobs.
void	setServiceNotes(String notes) Fill in any string representing service notes.
void	setServiceNotesXML(String notes) Fill in any string representing service notes.
static void	setXMLAttribute(org.jdom.Element element, String name, String value) Set attribute 'name' to 'value' in a jDOM XML element, equipped with the BioMoby namespace.
static void	setXMLAttributeForced(org.jdom.Element element, String name, String value) Set attribute 'name' to 'value' in a jDOM XML element, equipped with the BioMoby namespace.
int	size() Return the number of jobs (queries) contained in this package.
String	toString() Format all non-empty public members in a human-readable way.
String	toXML() Convert the whole contents and all its children to a Biomoby compliant XML string.
org.jdom.Document	toXMLDocument() Convert the whole contents and all its children to a Biomoby compliant XML document.
static org.jdom.Document	toXMLDocument(org.jdom.Element[] jobs) A static alternative returning much simpler XML document - without authority, without service notes, just with the given jobs.

Methods inherited from class java.lang.Object

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

Constructor Detail

MobyPackage

public MobyPackage()

Default constructor.

MobyPackage

public MobyPackage(MobyObject mObj,
                   String articleName)

Constructing a simplest MobyPackage - with one MobyObject.

Parameters:

mObj - to be inserted in this package as a simple object in a single job

articleName - is the name given to the only Simple

Method Detail

createFromXML

public static MobyPackage createFromXML(Object xmlData)
                                 throws MobyException

Constructing a MobyPackage object from XML. The input XML can be given as a String, byte[], or a File.

Throws:

MobyException

createFromXML

public static MobyPackage createFromXML(Object xmlData,
                                        String lowestKnownDataType)
                                 throws MobyException

Constructing a MobyPackage object from XML. The input XML can be given as a String, byte[], or a File.

Additionally, it passes to the XML parser the 'lowestKnownDataType' as a falback object (the role of a fallback object is explained in MobyParser.

Throws:

MobyException

createFromXML

public static MobyPackage createFromXML(Object xmlData,
                                        Map<String,String> lowestKnownDataTypes)
                                 throws MobyException

Constructing a MobyPackage object from XML. The input XML can be given as a String, byte[], or a File.

Additionally, it passes to the XML parser the 'lowestKnownDataType' as a falback object (the role of a fallback object is explained in MobyParser.

Throws:

MobyException

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.

Parameters:

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

Returns:

a formatted, and indented, string

getXMLElement

public static org.jdom.Element getXMLElement(String name)

Return a jDOM XML element equipped with the BioMoby namespace. This is just a convenient utility method.

Parameters:

name - of the returned element

Returns:

a jDOM element

setXMLAttribute

public static void setXMLAttribute(org.jdom.Element element,
                                   String name,
                                   String value)

Set attribute 'name' to 'value' in a jDOM XML element, equipped with the BioMoby namespace. This is just a convenient utility method.

Do it only if 'value' is not empty. If you need to create an attribute even if the value is empty use instead method setXMLAttributeForced(org.jdom.Element, java.lang.String, java.lang.String).

Parameters:

element - where a new attribute is created

name - of the created attribute

value - of the created attribute

setXMLAttributeForced

public static void setXMLAttributeForced(org.jdom.Element element,
                                         String name,
                                         String value)

Set attribute 'name' to 'value' in a jDOM XML element, equipped with the BioMoby namespace. This is just a convenient utility method.

Do it even for an empty 'value'.

Parameters:

element - where a new attribute is created

name - of the created attribute

value - of the created attribute

toXML

public String toXML()

Convert the whole contents and all its children to a Biomoby compliant XML string.

toXMLDocument

public org.jdom.Document toXMLDocument()

Convert the whole contents and all its children to a Biomoby compliant XML document.

toXMLDocument

public static org.jdom.Document toXMLDocument(org.jdom.Element[] jobs)

A static alternative returning much simpler XML document - without authority, without service notes, just with the given jobs. And the jobs are given already as DOM Elements.

size

public int size()

Return the number of jobs (queries) contained in this package.

setJobs

public void setJobs(MobyJob[] jobs)

Store here all jobs. It removes all previously (if any) stored jobs.

addJob

public void addJob(MobyJob job)

Add one job to the already stored here.

getJobs

public MobyJob[] getJobs()

Get back all jobs stored here.

getJob

public MobyJob getJob(int index)
               throws MobyException

Get back a job indicated by its order number. The 'index' starts at zero.

Throws:

MobyException

setAuthority

public void setAuthority(String authority)

Fill in an authority of this whole package.

getAuthority

public String getAuthority()

Get back the authority serving this package.

setServiceNotes

public void setServiceNotes(String notes)

Fill in any string representing service notes. According the BioMoby API, the service notes are meant to contain human-readable free text describing further a service returning this package.

Parameters:

notes - human-readable description

See Also:

for adding CDATA section, for adding service exceptions

setServiceNotesXML

public void setServiceNotesXML(String notes)

Fill in any string representing service notes. The string will be added as a CDATA (so it can contain any XML).

Parameters:

notes - human-readable description

See Also:

for adding string that will be properly escaped, for adding service exceptions

getServiceNotes

public String getServiceNotes()

Get back service notes.

addException

public void addException(ServiceException error)

Add a new exception reported by this service execution. If the exception reports only about a particular job it is its responsibility to have ID of this job filled in.

Parameters:

error - to be added

addException

public void addException(ServiceException error,
                         MobyJob job)

Add a new exception reported by this service execution. Add to the exception the job ID of the given job. It is a convenient method.

Parameters:

error - to be added

job - whose ID is aded to the 'error'

setExceptions

public void setExceptions(ServiceException[] errors)

Set one or more exceptions reported by this service invocation. It first removes all previously set exceptions.

Parameters:

errors - to be assigned

getExceptions

public ServiceException[] getExceptions()

Return all so far set exceptions.

evaluateExceptions

public String evaluateExceptions(org.apache.commons.logging.Log log,
                                 boolean throwException)
                          throws MobyException

Evaluate current exceptions.

This is a utility (convenient) method that extracts all exceptions from this package and formats them into one string, and either returns it, or throws an exception (depending on the policy in 'throwException').

Parameters:

log - if not null then the formatted exceptions are written into this log (the severity of the exceptions dedicates the log level used)

throwException - specify what to do when an error condition was found: if 'throwException' is true then an exception is thrown, otherwise the formatted exception is returned

Returns:

formatted exceptions (of any kind, not only severe errors), or an empty String if there were no exceptions

Throws:

MobyException - if there were at least one severe exceptions and if the 'throwException' policy is true

hasAnError

public boolean hasAnError()

Return true if this package contains at least one exception of the severity ServiceException.ERROR). Otherwise return false.