edu.isi.pegasus.planner.parser

## Class StackBasedXMLParser

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

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

Direct Known Subclasses:
  DAXParser3, SiteCatalogXMLParser3, SiteCatalogXMLParser4

    public abstract class StackBasedXMLParser
    extends Parser

An abstract base class that XML Parsers can use if they use stack internally to store the elements encountered while parsing XML documents using SAX

Version:
  $Revision$
Author:
  Karan Vahi vahi@isi.edu

### Field Summary

Fields
`protected int` `mDepth` Count the depths of elements in the document
`protected boolean` `mParsingDone` A boolean indicating that parsing is done.
`protected java.util.Stack` `mStack` The stack of objects kept around.

### Fields inherited from class edu.isi.pegasus.planner.parser.Parser

`DEFAULT_PARSER_NAME, mAdjFName, mLocator, mLogger, mLogMsg, mParser, mProps, mTextContent, mTextString`

### Constructor Summary

Constructors
Constructor and Description
`StackBasedXMLParser(PegasusBag bag)` The overloaded constructor.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `attributeNotSupported(java.lang.String element, java.lang.String attribute, java.lang.String value)` This is called when an attribute is encountered for an element that is valid in the schema context but not supported right now.
`void` `complain(java.lang.String element, java.lang.String attribute, java.lang.String value)` This is called when an attribute is encountered for an element that is invalid from the schema context and is not supported.
`abstract java.lang.Object` `createObject(java.lang.String element, java.util.List names, java.util.List values)` Composes the `SiteData` object corresponding to the element name in the XML document.
`void` `endDocument()` This is called automatically when the end of the XML file is reached.
`void` `endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)` The parser is at the end of an element.
`void` `log(java.lang.String element, java.lang.String attribute, java.lang.String value)`
`abstract boolean` `setElementRelation(java.lang.String childElement, java.lang.Object parent, java.lang.Object child)` This method sets the relations between the currently finished XML element(child) and its containing element in terms of Java objects.
`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` `unSupportedNestingOfElements(java.lang.String parent, java.lang.String child)` Called when certain element nesting is allowed in the XML schema but is not supported in the code as yet.

### Methods inherited from class edu.isi.pegasus.planner.parser.Parser

`characters, getSchemaLocation, getSchemaNamespace, ignoreWhitespace, ignoreWhitespace, setDocumentLocator, setParserFeature, setSchemaLocations, startParser, testForFile`

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

`endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### mDepth

    protected int mDepth

Count the depths of elements in the document

#### mStack

    protected java.util.Stack mStack

The stack of objects kept around.

#### mParsingDone

    protected boolean mParsingDone

A boolean indicating that parsing is done.

### Constructor Detail

#### StackBasedXMLParser

    public StackBasedXMLParser(PegasusBag bag)

The overloaded constructor.

Parameters:
  `bag` - the `PegasusBag` to be used.

### Method Detail

#### createObject

    public abstract java.lang.Object createObject(java.lang.String element,
                                                  java.util.List names,
                                                  java.util.List values)

Composes the `SiteData` object corresponding to the element name in the XML document.

Parameters:
  `element` - the element name encountered while parsing.
  `names` - is a list of attribute names, as strings.
  `values` - is a list of attribute values, to match the key list.
Returns:
  the relevant SiteData object, else null if unable to construct.
Throws:
  `java.lang.IllegalArgumentException` - if the element name is too short.

#### setElementRelation

    public abstract boolean setElementRelation(java.lang.String childElement,
                                               java.lang.Object parent,
                                               java.lang.Object child)

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

Parameters:
  `childElement` - name is the the child 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.

#### endDocument

    public void endDocument()

Description copied from class: `Parser`
This is called automatically when the end of the XML file is reached.

Specified by:
  `endDocument` in interface `org.xml.sax.ContentHandler`
Specified by:
  `endDocument` in class `Parser`

#### 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`
Specified by:
  `startElement` in class `Parser`
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. Triggers the association of the child elements with the appropriate parent elements.

Specified by:
  `endElement` in interface `org.xml.sax.ContentHandler`
Specified by:
  `endElement` in class `Parser`
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`

#### log

    public void log(java.lang.String element,
                    java.lang.String attribute,
                    java.lang.String value)

Parameters:
  `element` -
  `attribute` -
  `value` -

#### complain

    public void complain(java.lang.String element,
                         java.lang.String attribute,
                         java.lang.String value)

This is called when an attribute is encountered for an element that is invalid from the schema context and is not supported.

Parameters:
  `element` - the element name
  `attribute` - the attribute name
  `value` - the attribute value

#### attributeNotSupported

    public void attributeNotSupported(java.lang.String element,
                                      java.lang.String attribute,
                                      java.lang.String value)

This is called when an attribute is encountered for an element that is valid in the schema context but not supported right now.

Parameters:
  `element` - the element name
  `attribute` - the attribute name
  `value` - the attribute value

#### unSupportedNestingOfElements

    public void unSupportedNestingOfElements(java.lang.String parent,
                                             java.lang.String child)

Called when certain element nesting is allowed in the XML schema but is not supported in the code as yet.

Parameters:
  `parent` - parent element
  `child` - child element