edu.isi.pegasus.planner.parser
Class InvocationParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      edu.isi.pegasus.planner.parser.InvocationParser

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class InvocationParser
extends DefaultHandler

This class uses the Xerces SAX2 parser to validate and parse an XML document which contains information from kickstart generated invocation record.

Version:

$Revision: 3732 $

Author:

Jens-S. Vöckler, Yong Zhao

Field Summary

private SimpleDateFormat	m_coarse Parsing for ISO dates without milliseconds
private int	m_depth Count the depths of elements in the document
private SimpleDateFormat	m_fine Parsing for ISO dates with millisecond extension.
private Map	m_forward A Hashmap to forward resolve namespaces that were encountered during parsing.
private Locator	m_location Keep the location within the document
private org.griphyn.vdl.util.Logging	m_log Obtain our logger once for multiple uses.
private XMLReader	m_parser Holds the instance of a XMLReader class.
private InvocationRecord	m_result Holds the result, will be overwritten by each invocation of parse().
private Map	m_reverse A Hashmap to reverse resolve namespaces that were encountered during parsing.
private Stack	m_stack A stack of namespaces?
protected static String	vendorParserClass Default parser is the Xerces parser.

Constructor Summary

InvocationParser(String schemaLocation)
The class constructor.

Method Summary

void	characters(char[] ch, int start, int length) This method is the callback function for characters in an element.
private void	complain(String subject, String name, String value) Small helper method to bundle repetitive complaints in a template for reporting progress.
protected Invocation	createObject(Invocation parent, String e, List names, List values) This method determines the actively parsed element, creates the Java object that corresponds to the element, and sets the member variables with the values of the attributes of the element.
void	endDocument() The parser comes to the end of the document.
void	endElement(String namespaceURI, String localName, String qName) The parser is at the end of an element.
void	endPrefixMapping(String prefix) Out of the reach of the prefix, remove it from the HashMap.
private String	full_where()
void	ignorableWhitespace(char[] ch, int start, int length) Currently, ignorable whitespace will be ignored.
private void	log(String subject, String name, String value) Small helper method to bundle repetitive parameters in a template for reporting progress.
private String	map(String uri) Helper function to map prefixes correctly onto the elements.
InvocationRecord	parse(InputStream reader) This function parses a XML source from an InputStream source, and creates java class instances that correspond to different elements in the XML source.
InvocationRecord	parse(Reader reader) This function parses a XML source from the new Reader source, and creates java class instances that correspond to different elements in the XML source.
private Date	parseDate(String date) Small helper to parse the different date varieties and deal with Java obnoxeity.
void	processingInstruction(String target, String data) Receive a processing instruction.
private boolean	set(String uri, boolean flag) Sets a feature while capturing failed features right here.
void	setDocumentLocator(Locator locator) Obtains the document locator from the parser.
protected boolean	setElementRelation(char initial, Invocation parent, Invocation child) This method sets the relations between the currently finished XML element and its containing element in terms of Java objects.
void	setSchemaLocations(String list) Sets the list of external real locations where the XML schema may be found.
private void	setupJob(Job job, List names, List values) Small helper method to set up the attributes for the job elements.
void	skippedEntity(String name) Receive a notification that an entity was skipped.
void	startDocument() This method specifies what to do when the parser is at the beginning of the document.
void	startElement(String namespaceURI, String localName, String qName, Attributes atts) This method defines the action to take when the parser begins to parse an element.
void	startPrefixMapping(String prefix, String uri) There is a prefix or namespace defined, put the prefix and its URI in the HashMap.
private String	where()

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

error, fatalError, notationDecl, resolveEntity, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Field Detail

vendorParserClass

protected static final String vendorParserClass

Default parser is the Xerces parser.

See Also:

Constant Field Values

m_parser

private XMLReader m_parser

Holds the instance of a XMLReader class.

m_result

private InvocationRecord m_result

Holds the result, will be overwritten by each invocation of parse().

m_location

private Locator m_location

Keep the location within the document

m_forward

private Map m_forward

A Hashmap to forward resolve namespaces that were encountered during parsing.

m_reverse

private Map m_reverse

A Hashmap to reverse resolve namespaces that were encountered during parsing.

m_coarse

private SimpleDateFormat m_coarse

Parsing for ISO dates without milliseconds

m_fine

private SimpleDateFormat m_fine

Parsing for ISO dates with millisecond extension.

m_log

private org.griphyn.vdl.util.Logging m_log

Obtain our logger once for multiple uses.

m_depth

private int m_depth

Count the depths of elements in the document

m_stack

private Stack m_stack

A stack of namespaces?

Constructor Detail

InvocationParser

public InvocationParser(String schemaLocation)

The class constructor. This function initializes the Xerces parser and the features that enable schema validation.

Parameters:

schemaLocation - is the default location of the XML Schema which this parser is capable of parsing. It may be null to use the defaults provided in the document.

Method Detail

set

private boolean set(String uri,
                    boolean flag)

Sets a feature while capturing failed features right here.

Parameters:

uri - is the feature's URI to modify

flag - is the new value to set.

Returns:

true, if the feature could be set, false for an exception

setSchemaLocations

public void setSchemaLocations(String list)

Sets the list of external real locations where the XML schema may be found. Since this list can be determined at run-time through properties etc., we expect this function to be called between instantiating the parser, and using the parser

Parameters:

list - is a list of strings representing schema locations. The content exists in pairs, one of the namespace URI, one of the location URL.

parse

public InvocationRecord parse(InputStream reader)

This function parses a XML source from an InputStream source, and creates java class instances that correspond to different elements in the XML source.

Parameters:

reader - is a bytestream opened for reading.

Returns:

the records with the invocation information, or null on failure.

parse

public InvocationRecord parse(Reader reader)

This function parses a XML source from the new Reader source, and creates java class instances that correspond to different elements in the XML source.

Parameters:

reader - is a character stream opened for reading.

Returns:

the records with the invocation information, or null on failure.

setDocumentLocator

public void setDocumentLocator(Locator locator)

Obtains the document locator from the parser. The document location can be used to print debug information, i.e the current location (line, column) in the document.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

Parameters:

locator - is the externally set current position

full_where

private String full_where()

where

private String where()

startDocument

public void startDocument()

This method specifies what to do when the parser is at the beginning of the document. In this case, we simply print a message for debugging.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class DefaultHandler

endDocument

public void endDocument()

The parser comes to the end of the document.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class DefaultHandler

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

There is a prefix or namespace defined, put the prefix and its URI in the HashMap. We can get the URI when the prefix is used here after.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class DefaultHandler

Parameters:

prefix - the Namespace prefix being declared.

uri - the Namespace URI the prefix is mapped to.

Throws:

SAXException

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Out of the reach of the prefix, remove it from the HashMap.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class DefaultHandler

Parameters:

prefix - is the prefix that was being mapped previously.

Throws:

SAXException

map

private String map(String uri)

Helper function to map prefixes correctly onto the elements.

Parameters:

uri - is the parser-returned URI that needs translation.

Returns:

the correct prefix for the URI

startElement

public void startElement(String namespaceURI,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

This method defines the action to take when the parser begins to parse an element.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Parameters:

namespaceURI - is the URI of the namespace for the element

localName - is the element name without namespace

qName - is the element name as it appears in the docment

atts - has the names and values of all the attributes

Throws:

SAXException

endElement

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

The parser is at the end of an element. Each successfully and completely parsed Definition will trigger a callback to the registered DefinitionHandler.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Parameters:

namespaceURI - is the URI of the namespace for the element

localName - is the element name without namespace

qName - is the element name as it appears in the docment

Throws:

SAXException

characters

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

This method is the callback function for characters in an element. The element is expected to be of mixed content.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

Parameters:

ch - are the characters from the XML document

start - is the start position into the array

length - is the amount of valid data in the array

Throws:

SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Currently, ignorable whitespace will be ignored.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class DefaultHandler

Parameters:

ch - are the characters from the XML document

start - is the start position into the array

length - is the amount of valid data in the array

Throws:

SAXException

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Receive a processing instruction. Currently, we are just printing a debug message that we received a PI.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

processingInstruction in class DefaultHandler

Parameters:

target - the processing instruction target

data - the processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target.

Throws:

SAXException

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Receive a notification that an entity was skipped. Currently, we are just printing a debug message to this fact.

Specified by:

skippedEntity in interface ContentHandler

Overrides:

skippedEntity in class DefaultHandler

Parameters:

name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".

Throws:

SAXException

log

private void log(String subject,
                 String name,
                 String value)

Small helper method to bundle repetitive parameters in a template for reporting progress.

Parameters:

subject - is the name of the XML element that is being scrutinized.

name - is then name of the element we are working with.

value - is the attribute value.

complain

private void complain(String subject,
                      String name,
                      String value)

Small helper method to bundle repetitive complaints in a template for reporting progress.

Parameters:

subject - is the name of the XML element that is being scrutinized.

name - is then name of the element we are working with.

value - is the attribute value.

parseDate

private Date parseDate(String date)
                throws ParseException

Small helper to parse the different date varieties and deal with Java obnoxeity.

Parameters:

date - is an ISO 8601 timestamp

Returns:

a date field

Throws:

ParseException - thrown if the date cannot be parsed

setupJob

private void setupJob(Job job,
                      List names,
                      List values)
               throws NumberFormatException,
                      ParseException

Small helper method to set up the attributes for the job elements.

Parameters:

job - is the job to set up.

names - is the list of attribute names

values - is the list of attribute values

Throws:

NumberFormatException

ParseException

createObject

protected Invocation createObject(Invocation parent,
                                  String e,
                                  List names,
                                  List values)
                           throws IllegalArgumentException

This method determines the actively parsed element, creates the Java object that corresponds to the element, and sets the member variables with the values of the attributes of the element.

Parameters:

parent - is the parent element

e - is the name of the element

names - is a list of attribute names, as strings.

values - is a list of attribute values, to match the key list.

Returns:

A new VDL Java object, which may only be partly constructed.

Throws:

IllegalArgumentException - if the element name is too short.

setElementRelation

protected boolean setElementRelation(char initial,
                                     Invocation parent,
                                     Invocation child)

This method sets the relations between the currently finished XML element and its containing element in terms of Java objects. Usually it involves adding the object to the parent's child object list.

Parameters:

initial - is the first charactor of the parent element name

parent - is a reference to the parent's Java object

child - is the completed child object to connect to the parent

Returns:

true if the element was added successfully, false, if the child does not match into the parent.