org.cybertory.MSS
Class XMLHandler

java.lang.Object
  extended byorg.cybertory.MSS.XMLHandler
All Implemented Interfaces:
java.lang.Comparable
Direct Known Subclasses:
XMLHandlerArray, XMLHandlerAtomic, XMLHandlerStd, XMLHandlerSuper

public abstract class XMLHandler
extends java.lang.Object
implements java.lang.Comparable

The base class for code associated with handled data types, including functionality for generating XML Schema and parsing the corresponding XML data. There's also a lot of static code behind the methods schemaDocument() and parseXMLDocument(org.jdom.Document, org.cybertory.MSS.ExternalDataFactory[]).


Field Summary
protected  java.lang.Class handledClass
          map of handlers keyed by short name for class
 
Constructor Summary
protected XMLHandler(java.lang.Class handledClass)
          Constructor (never accessed by user code since abstract).
 
Method Summary
protected abstract  boolean allowBackwardRef()
          Allow multiple elements for this data type ?
protected abstract  boolean allowMultiple()
           
protected static org.jdom.Element alternateElement(java.lang.String parseLabel, boolean forExternal)
          Create the element for either "ext_*" or "ref_*" with given parse label.
 int compareTo(java.lang.Object o)
          To implement Comparable
protected  java.util.List extractChildren(org.jdom.Element parentElem, org.jdom.filter.Filter childFilter, boolean required)
           
protected static XMLHandler[] getAllHandlers()
           
static java.lang.Class[] getHandledClasses(java.lang.Class superClass)
          Given a class (or interface), return its handled subclasses.
protected static XMLHandler getHandler(java.lang.Class cls)
          Return the handler instance associated with a handled data type.
protected static XMLHandler[] getHandlersDefs()
           
 XMLChildFilter getXMLChildFilter(boolean allowExternalData)
           
 XMLChildFilter getXMLChildFilter(java.lang.String parseLabel, boolean allowExternalData)
           
 java.lang.Class handledClass()
          Return the Class object for the data type handled by this wrapper.
static void handlersReport(java.io.PrintStream output)
          The Class whose data is parsed by this handler
protected abstract  boolean needsTypedef()
          Allow data in the "defs" section, with later backward references ?
protected  java.lang.Object parseChildren(org.jdom.Element parentElem, org.jdom.filter.Filter childFilter, XMLAltData altData, boolean required)
          Parse zero or more children of the same data type.
protected abstract  java.lang.Object parseElement(org.jdom.Element elem, XMLAltData altData)
          Given that the element already extracted from it's context, parse the data (whose type should match that of the handler).
static Scan[] parseRequest(org.jdom.Element parentElem, XMLAltData altData)
           
static Scan[] parseXMLDocument(org.jdom.Document doc, ExternalDataFactory[] extDataFactories)
          Parse the entire XML document requesting microarray image scans.
static org.jdom.Document schemaDocument()
          Return a JDOM Document for the entire schema of the XML for generating images.
protected  org.jdom.Element schemaInContext(boolean required, boolean allowExternalData)
           
protected  org.jdom.Element schemaInContext(boolean required, boolean allowExternalData, java.lang.String description)
          Return an element for a particular context
protected  org.jdom.Element schemaInContext(java.lang.String parseLabel, boolean required, boolean allowExternalData)
           
protected  org.jdom.Element schemaInContext(java.lang.String parseLabel, boolean required, boolean allowExternalData, java.lang.String description)
          Return an element for a particular context
protected  org.jdom.Element schemaTypedef()
          Generate Schema type definition for the class (using JDOM).
 java.lang.String typeDescription()
           
abstract  java.lang.String xmlTypeName()
          Return the label to be used in the name of schema type defs.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

handledClass

protected final java.lang.Class handledClass
map of handlers keyed by short name for class

Constructor Detail

XMLHandler

protected XMLHandler(java.lang.Class handledClass)
Constructor (never accessed by user code since abstract).

Method Detail

handlersReport

public static void handlersReport(java.io.PrintStream output)
The Class whose data is parsed by this handler


getHandledClasses

public static java.lang.Class[] getHandledClasses(java.lang.Class superClass)
Given a class (or interface), return its handled subclasses.

Parameters:
superClass - the class for whom the subclasses are desired
Returns:
an array of subclasses of the given class

getAllHandlers

protected static XMLHandler[] getAllHandlers()

getHandlersDefs

protected static XMLHandler[] getHandlersDefs()

schemaDocument

public static org.jdom.Document schemaDocument()
                                        throws XMLUnhandledTypeException
Return a JDOM Document for the entire schema of the XML for generating images. All of the XMLHandler instances must be created before this will work.

Returns:
a Document for the image generation schema
Throws:
XMLUnhandledTypeException

parseXMLDocument

public static Scan[] parseXMLDocument(org.jdom.Document doc,
                                      ExternalDataFactory[] extDataFactories)
                               throws XMLParseException,
                                      XMLUnhandledTypeException
Parse the entire XML document requesting microarray image scans.

Returns:
an array of one or more Scan objects which can then be rendered (and saved to files).
Throws:
XMLParseException
XMLUnhandledTypeException

parseRequest

public static Scan[] parseRequest(org.jdom.Element parentElem,
                                  XMLAltData altData)
                           throws XMLParseException,
                                  XMLUnhandledTypeException
Throws:
XMLParseException
XMLUnhandledTypeException

getHandler

protected static XMLHandler getHandler(java.lang.Class cls)
                                throws XMLUnhandledTypeException
Return the handler instance associated with a handled data type.

Parameters:
cls - the Class of interest
Returns:
The XMLHandler instance associated with class of interest
Throws:
XMLUnhandledTypeException

allowMultiple

protected abstract boolean allowMultiple()

allowBackwardRef

protected abstract boolean allowBackwardRef()
Allow multiple elements for this data type ?


needsTypedef

protected abstract boolean needsTypedef()
Allow data in the "defs" section, with later backward references ?


typeDescription

public java.lang.String typeDescription()

schemaTypedef

protected org.jdom.Element schemaTypedef()
                                  throws XMLUnhandledTypeException
Generate Schema type definition for the class (using JDOM).

Returns:
a JDOM Element with schema for type
Throws:
XMLUnhandledTypeException

alternateElement

protected static org.jdom.Element alternateElement(java.lang.String parseLabel,
                                                   boolean forExternal)
Create the element for either "ext_*" or "ref_*" with given parse label.

Parameters:
parseLabel -
forExternal - indicates this should be an external data element rather than a backward ref element.

schemaInContext

protected org.jdom.Element schemaInContext(boolean required,
                                           boolean allowExternalData)
                                    throws XMLUnhandledTypeException
Throws:
XMLUnhandledTypeException

schemaInContext

protected org.jdom.Element schemaInContext(boolean required,
                                           boolean allowExternalData,
                                           java.lang.String description)
                                    throws XMLUnhandledTypeException
Return an element for a particular context

Parameters:
allowExternalData - indicates whether to add an "externalData" element.
Returns:
an element for this data type
Throws:
XMLUnhandledTypeException

schemaInContext

protected org.jdom.Element schemaInContext(java.lang.String parseLabel,
                                           boolean required,
                                           boolean allowExternalData)
                                    throws XMLUnhandledTypeException
Throws:
XMLUnhandledTypeException

schemaInContext

protected org.jdom.Element schemaInContext(java.lang.String parseLabel,
                                           boolean required,
                                           boolean allowExternalData,
                                           java.lang.String description)
                                    throws XMLUnhandledTypeException
Return an element for a particular context

Parameters:
allowExternalData - indicates whether to add an "externalData" element.
Returns:
an element for this data type
Throws:
XMLUnhandledTypeException

parseChildren

protected java.lang.Object parseChildren(org.jdom.Element parentElem,
                                         org.jdom.filter.Filter childFilter,
                                         XMLAltData altData,
                                         boolean required)
                                  throws XMLParseException,
                                         XMLUnhandledTypeException
Parse zero or more children of the same data type. Given the parent element below which the data resides for the field of interest, parse it and return and object of the appropriate type for the handler. If the data is absent, then either a null is returned or an an exception is thrown, depending upon the 'required' field.

Parameters:
parentElem - the JDOM element under which the data should be found.
childFilter - a JDOM element filter object applied on the children
altData - Alternate source of data: external and cached data
required - indicates if it's not OK for the data to be absent
Returns:
an object of the appropriate type (or null if data absent)
Throws:
XMLParseException
XMLUnhandledTypeException

extractChildren

protected java.util.List extractChildren(org.jdom.Element parentElem,
                                         org.jdom.filter.Filter childFilter,
                                         boolean required)
                                  throws XMLParseException
Throws:
XMLParseException

parseElement

protected abstract java.lang.Object parseElement(org.jdom.Element elem,
                                                 XMLAltData altData)
                                          throws XMLParseException,
                                                 XMLUnhandledTypeException
Given that the element already extracted from it's context, parse the data (whose type should match that of the handler).

Parameters:
elem - the JDOM element containing the data
altData - the background data context for parsing
Returns:
an object of the appropriate type
Throws:
XMLParseException
XMLUnhandledTypeException

handledClass

public java.lang.Class handledClass()
Return the Class object for the data type handled by this wrapper.

Returns:
handled Class

xmlTypeName

public abstract java.lang.String xmlTypeName()
Return the label to be used in the name of schema type defs.

Returns:
schema type label (or null if no data type name is to be used)

getXMLChildFilter

public XMLChildFilter getXMLChildFilter(boolean allowExternalData)

getXMLChildFilter

public XMLChildFilter getXMLChildFilter(java.lang.String parseLabel,
                                        boolean allowExternalData)

compareTo

public int compareTo(java.lang.Object o)
To implement Comparable

Specified by:
compareTo in interface java.lang.Comparable