edu.isi.pegasus.planner.parser

## Class InvocationParser

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

All Implemented Interfaces:
  org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

    public class InvocationParser
    extends org.xml.sax.helpers.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$
Author:
  Jens-S. Vöckler, Yong Zhao

### Field Summary

Fields
`private java.text.SimpleDateFormat` `m_coarse` Parsing for ISO dates without milliseconds
`private int` `m_depth` Count the depths of elements in the document
`private java.text.SimpleDateFormat` `m_fine` Parsing for ISO dates with millisecond extension.
`private java.util.Map` `m_forward` A Hashmap to forward resolve namespaces that were encountered during parsing.
`private org.xml.sax.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 org.xml.sax.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 java.util.Map` `m_reverse` A Hashmap to reverse resolve namespaces that were encountered during parsing.
`private java.util.Stack` `m_stack` A stack of namespaces?
`protected static java.lang.String` `vendorParserClass` Default parser is the Xerces parser.

### Constructor Summary

Constructors
Constructor and Description
`InvocationParser(java.lang.String schemaLocation)` The class constructor.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `characters(char[] ch, int start, int length)` This method is the callback function for characters in an element.
`private void` `complain(java.lang.String subject, java.lang.String name, java.lang.String value)` Small helper method to bundle repetitive complaints in a template for reporting progress.
`protected Invocation` `createObject(Invocation parent, java.lang.String e, java.util.List names, java.util.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(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)` The parser is at the end of an element.
`void` `endPrefixMapping(java.lang.String prefix)` Out of the reach of the prefix, remove it from the HashMap.
`private java.lang.String` `full_where()`
`void` `ignorableWhitespace(char[] ch, int start, int length)` Currently, ignorable whitespace will be ignored.
`private void` `log(java.lang.String subject, java.lang.String name, java.lang.String value)` Small helper method to bundle repetitive parameters in a template for reporting progress.
`private java.lang.String` `map(java.lang.String uri)` Helper function to map prefixes correctly onto the elements.
`InvocationRecord` `parse(java.io.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(java.io.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 java.util.Date` `parseDate(java.lang.String date)` Small helper to parse the different date varieties and deal with Java obnoxeity.
`void` `processingInstruction(java.lang.String target, java.lang.String data)` Receive a processing instruction.
`private boolean` `set(java.lang.String uri, boolean flag)` Sets a feature while capturing failed features right here.
`void` `setDocumentLocator(org.xml.sax.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(java.lang.String list)` Sets the list of external real locations where the XML schema may be found.
`private void` `setupJob(Job job, java.util.List names, java.util.List values)` Small helper method to set up the attributes for the job elements.
`void` `skippedEntity(java.lang.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(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)` This method defines the action to take when the parser begins to parse an element.
`void` `startPrefixMapping(java.lang.String prefix, java.lang.String uri)` There is a prefix or namespace defined, put the prefix and its URI in the HashMap.
`private java.lang.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 java.lang.String vendorParserClass

Default parser is the Xerces parser.

See Also:
  Constant Field Values

#### m_parser

    private org.xml.sax.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 org.xml.sax.Locator m_location

Keep the location within the document

#### m_forward

    private java.util.Map m_forward

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

#### m_reverse

    private java.util.Map m_reverse

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

#### m_coarse

    private java.text.SimpleDateFormat m_coarse

Parsing for ISO dates without milliseconds

#### m_fine

    private java.text.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 java.util.Stack m_stack

A stack of namespaces?

### Constructor Detail

#### InvocationParser

    public InvocationParser(java.lang.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(java.lang.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(java.lang.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(java.io.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(java.io.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(org.xml.sax.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 `org.xml.sax.ContentHandler`
Overrides:
  `setDocumentLocator` in class `org.xml.sax.helpers.DefaultHandler`
Parameters:
  `locator` - is the externally set current position

#### full_where

    private java.lang.String full_where()

#### where

    private java.lang.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 `org.xml.sax.ContentHandler`
Overrides:
  `startDocument` in class `org.xml.sax.helpers.DefaultHandler`

#### endDocument

    public void endDocument()

The parser comes to the end of the document.

Specified by:
  `endDocument` in interface `org.xml.sax.ContentHandler`
Overrides:
  `endDocument` in class `org.xml.sax.helpers.DefaultHandler`

#### startPrefixMapping

    public void startPrefixMapping(java.lang.String prefix,
                                   java.lang.String uri)
                            throws org.xml.sax.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 `org.xml.sax.ContentHandler`
Overrides:
  `startPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
Parameters:
  `prefix` - the Namespace prefix being declared.
  `uri` - the Namespace URI the prefix is mapped to.
Throws:
  `org.xml.sax.SAXException`

#### endPrefixMapping

    public void endPrefixMapping(java.lang.String prefix)
                          throws org.xml.sax.SAXException

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

Specified by:
  `endPrefixMapping` in interface `org.xml.sax.ContentHandler`
Overrides:
  `endPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
Parameters:
  `prefix` - is the prefix that was being mapped previously.
Throws:
  `org.xml.sax.SAXException`

#### map

    private java.lang.String map(java.lang.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(java.lang.String namespaceURI,
                             java.lang.String localName,
                             java.lang.String qName,
                             org.xml.sax.Attributes atts)
                      throws org.xml.sax.SAXException

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

Specified by:
  `startElement` in interface `org.xml.sax.ContentHandler`
Overrides:
  `startElement` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### endElement

    public void endElement(java.lang.String namespaceURI,
                           java.lang.String localName,
                           java.lang.String qName)
                    throws org.xml.sax.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 `org.xml.sax.ContentHandler`
Overrides:
  `endElement` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### characters

    public void characters(char[] ch,
                           int start,
                           int length)
                    throws org.xml.sax.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 `org.xml.sax.ContentHandler`
Overrides:
  `characters` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### ignorableWhitespace

    public void ignorableWhitespace(char[] ch,
                                    int start,
                                    int length)
                             throws org.xml.sax.SAXException

Currently, ignorable whitespace will be ignored.

Specified by:
  `ignorableWhitespace` in interface `org.xml.sax.ContentHandler`
Overrides:
  `ignorableWhitespace` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### processingInstruction

    public void processingInstruction(java.lang.String target,
                                      java.lang.String data)
                               throws org.xml.sax.SAXException

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

Specified by:
  `processingInstruction` in interface `org.xml.sax.ContentHandler`
Overrides:
  `processingInstruction` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### skippedEntity

    public void skippedEntity(java.lang.String name)
                       throws org.xml.sax.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 `org.xml.sax.ContentHandler`
Overrides:
  `skippedEntity` in class `org.xml.sax.helpers.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:
  `org.xml.sax.SAXException`

#### log

    private void log(java.lang.String subject,
                     java.lang.String name,
                     java.lang.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(java.lang.String subject,
                          java.lang.String name,
                          java.lang.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 java.util.Date parseDate(java.lang.String date)
                              throws java.text.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:
  `java.text.ParseException` - thrown if the date cannot be parsed

#### setupJob

    private void setupJob(Job job,
                          java.util.List names,
                          java.util.List values)
                   throws java.lang.NumberFormatException,
                          java.text.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:
  `java.lang.NumberFormatException`
  `java.text.ParseException`

#### createObject

    protected Invocation createObject(Invocation parent,
                                      java.lang.String e,
                                      java.util.List names,
                                      java.util.List values)
                               throws java.lang.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:
  `java.lang.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.