org.biomoby.shared.parser
Class MobyParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.tulsoft.tools.xml.XMLErrorHandler
          org.biomoby.shared.parser.MobyParser

All Implemented Interfaces:

MobyTags, ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class MobyParser
extends org.tulsoft.tools.xml.XMLErrorHandler
implements MobyTags

The MobyParser is able to read a Biomoby service/client XML data, parse them and create from them an instance of MobyPackage. The parser can be invoked by using a static method MobyPackage.createFromXML.

The parser depends on generated Java classes that define all Biomoby data types. There is a generator DataTypesGenerator that produces such classes into a package org.biomoby.shared.datatypes.

There is a situation when the parser tries to substitute an unknown data type by a known one. If the parsing encoutered an XML tag depicting a top-level data object, or a member object, and if there is no class available for such object, the parser can be instructed (in its non-default constructor to create a substituted object whose name was given in the parser constructor (there is also a constructor where you can get more than one such substitution object, depicted by its article name). This is to prevent situation when a long-time running and deployed service suddenly gets a request from a client that uses more up-to-date list of data types. It would be bad to let such service die (or minimally respond unproperly) just because its classes were generated too long ago.

Because also skeletons for services can be generated, it is easy to ensure that a service knows its "the most specialized" data type it can still serve, and that it passes it to the parser constructor.

If the parser finds an unknown object/tag but no substitute was passed in the parser constructor, it prints a warning and ignores the whole object, with all its descendants. The parser also produces a warning if it makes the substitution described above. Both these warnings should signal that new data types should be generated, and services restarted. Fortunately, it does not happen often at all.

If the parser finds another problem, usually related to the invalid XML, it raises a MobyException with error message containing line and column close to place where the error happened.

One possible problem would be when article names of the member data types in the parsed XML do not correspond to what was registered in the Biomoby registry (or to its more specialized childern).

You can test parser by using a simple TestingMobyParser client. This is how to invoke it and how to get its help:

 build/run/run-moby-parser -h
 

A test input file is available in data directory. To use it type:

 build/run/run-moby-parser -r data/parser-test-input.xml
 

The -r option causes that the parser not only parses the input file into an instance of MobyPackage but also converts this instance back (reverse) into an XML. The resulting XML is not formally identical to the original - it may have different formatting, it probably has more XML namespace prefixes (they are everywhere), but more importantly, it may not reflect all data that was in the original input. This is because the parser ignores all values that are not carried by and only by the Biomoby primitives types (as it was allowed before big change in the summer 2005).

If you wish to use the parser in your own code, here is how to do it:

 import org.biomoby.shared.parser.MobyPackage;
 import org.biomoby.shared.MobyException;

 try {
    MobyPackage moby = MobyPackage.createFromXML (new File ("input.xml"));

    // do something with 'moby'
    ...
    } catch (MobyException e) {
    ...
    }
 

If you want to add the "fallback" data type (as explained above), add its name as a second parameter:

 MobyPackage moby = MobyPackage.createFromXML (new File ("input.xml"),
                                               "GenericSequence");
 

For a constructor with more fallbacks, check generated skeletons (for example the sample skeleton net.jmoby.samples.ConcatSequencesSkel).

All XML tags and all attribute names that are recognized and processed by this parser are stored as constants in class MobyTags.

The parser is not thread-safe. Make a new instance for each parsed input.

Version:

$Id: MobyParser.java,v 1.9 2008/03/02 12:45:26 senger Exp $

Author:

Martin Senger

Field Summary

Fields inherited from class org.tulsoft.tools.xml.XMLErrorHandler

VERSION

Fields inherited from interface org.biomoby.shared.parser.MobyTags

ARTICLENAME, AUTHORITY, AUTHURI, COLLECTION, COMMENT, CROSSREFERENCE, DATABASECOMMENT, DATABASENAME, DATABASEVERSION, EVIDENCECODE, EXCEPTIONCODE, EXCEPTIONMESSAGE, MOBY, MOBY_XML_NS, MOBY_XML_NS_PREFIX, MOBYBOOLEAN, MOBYCONTENT, MOBYDATA, MOBYDATETIME, MOBYEXCEPTION, MOBYFLOAT, MOBYINTEGER, MOBYOBJECT, MOBYSTRING, NOTES, OBJ_ID, OBJ_NAMESPACE, PARAMETER, PLAINVERSION, PROVISIONINFORMATION, QUERYID, REFELEMENT, REFQUERYID, SERVICECOMMENT, SERVICEDATABASE, SERVICENAME, SERVICENOTES, SERVICESOFTWARE, SEVERITY, SIMPLE, SOFTWARECOMMENT, SOFTWARENAME, SOFTWAREVERSION, VALUE, XREF, XREFTYPE

Constructor Summary

MobyParser()
Default constructor.

MobyParser(Map<String,String> lowestKnownDataTypes)
Another constructor, taking more "fallback" data type names (indexed by their article names).

MobyParser(String lowestKnownDataType)
Another constructor, taking the "fallback" data type name.

Method Summary

void	characters(char[] ch, int start, int length) Called for #PCDATA.
void	endDocument() Called at the end of the parsed document.
void	endElement(String namespaceURI, String name, String qName) Called at the end of an element.
static MapDataTypesIfc	loadB2JMapping() Load mapping class between Biomoby data types names and their Java representations.
MobyPackage	parse(InputStream xml) Parse the contents coming from the given input stream.
MobyPackage	parse(Reader xmlReader) Parse the contents coming from the given reader.
MobyPackage	parse(String xmlFilename) Parse the contents of the given file.
void	setDocumentLocator(Locator l) Set document locator.
void	startDocument() Called at the beginning of the parsed document.
void	startElement(String namespaceURI, String name, String qName, Attributes attrs) Called when an element starts.

Methods inherited from class org.tulsoft.tools.xml.XMLErrorHandler

error, fatalError, warning

Methods inherited from class org.xml.sax.helpers.DefaultHandler

endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, skippedEntity, startPrefixMapping, unparsedEntityDecl

Methods inherited from class java.lang.Object

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

Constructor Detail

MobyParser

public MobyParser()

Default constructor.

MobyParser

public MobyParser(String lowestKnownDataType)

Another constructor, taking the "fallback" data type name. See the full documentation at the top of this class what is "fallback" data type and when it is used.

MobyParser

public MobyParser(Map<String,String> lowestKnownDataTypes)

Another constructor, taking more "fallback" data type names (indexed by their article names). See the full documentation at the top of this class what is "fallback" data type and when it is used.

Method Detail

parse

public MobyPackage parse(String xmlFilename)
                  throws MobyException

Parse the contents of the given file.

Throws:

MobyException

parse

public MobyPackage parse(InputStream xml)
                  throws MobyException

Parse the contents coming from the given input stream.

Throws:

MobyException

parse

public MobyPackage parse(Reader xmlReader)
                  throws MobyException

Parse the contents coming from the given reader.

Throws:

MobyException

setDocumentLocator

public void setDocumentLocator(Locator l)

Set document locator. There is usually no need to use it from outside the parser.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

loadB2JMapping

public static MapDataTypesIfc loadB2JMapping()
                                      throws MobyException

Load mapping class between Biomoby data types names and their Java representations.

Throws:

MobyException - if the mapping class was not found (which can happen because the mapping class is usually generated together with generating all data types - so if you forgot to do it first, the class does not exist and an exception is thrown)

startDocument

public void startDocument()
                   throws SAXException

Called at the beginning of the parsed document.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class DefaultHandler

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

Called at the end of the parsed document.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class DefaultHandler

Throws:

SAXException

startElement

public void startElement(String namespaceURI,
                         String name,
                         String qName,
                         Attributes attrs)
                  throws SAXException

Called when an element starts.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Throws:

SAXException

endElement

public void endElement(String namespaceURI,
                       String name,
                       String qName)
                throws SAXException

Called at the end of an element.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Throws:

SAXException

characters

public void characters(char[] ch,
                       int start,
                       int length)

Called for #PCDATA.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler