edu.isi.pegasus.planner.parser

## Class Parser

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

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

Direct Known Subclasses:
  ConfigXmlParser, DAXParser2, PDAXParser, SiteCatalogXMLMetadataParser, StackBasedXMLParser, XML2

    public abstract class Parser
    extends org.xml.sax.helpers.DefaultHandler

This is the base class which all the xml parsing classes extend. It initializes the xml parser namely Xerces, sets it's various features like turning on validation against schema etc, plus the namespace resolution.

Version:
  $Revision$
Author:
  Karan Vahi, Gaurang Mehta

### Field Summary

Fields
`protected java.lang.String` `DEFAULT_PARSER_NAME` Default parser name.
`protected boolean` `mAdjFName` Boolean flag to ensure that two adjacent filenames are separated by a whitespace.
`protected org.xml.sax.Locator` `mLocator` Locator object to determine on which line in the xml has the error occured.
`protected LogManager` `mLogger` The LogManager object which logs the Pegasus messages.
`protected java.lang.String` `mLogMsg` The String which contains the messages to be logged.
`protected org.xml.sax.XMLReader` `mParser` The object which is used to parse the dax.
`protected PegasusProperties` `mProps` The object holding all the properties pertaining to Pegasus.
`protected java.lang.StringBuffer` `mTextContent` Holds the text in an element (text between start and final tags if any).
`protected java.lang.String` `mTextString` A String that holds the contents of data passed as text.

### Constructor Summary

Constructors
Constructor and Description
`Parser(PegasusBag bag)` Intialises the parser.
`Parser(PegasusProperties properties)` Intialises the parser.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `characters(char[] chars, int start, int length)` This is used to store the character data that is in xml.
`private void` `createParserInstance()` Creates an instance of the parser, and sets the various options to it.
`abstract void` `endDocument()` This is called automatically when the end of the XML file is reached.
`abstract void` `endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)` An empty implementation is provided by DefaultHandler class.
`abstract java.lang.String` `getSchemaLocation()` Helps the load database to locate the XML schema, if available.
`abstract java.lang.String` `getSchemaNamespace()` Returns the XML schema namespace that a document being parsed conforms to.
`java.lang.String` `ignoreWhitespace(java.lang.String str)` Our own implementation for ignorable whitespace.
`java.lang.String` `ignoreWhitespace(java.lang.String str, boolean preserveLineBreak)` Our own implementation for ignorable whitespace.
`void` `setDocumentLocator(org.xml.sax.Locator loc)` Overrides the empty implementation provided by Default Handler and sets the locator variable for the locator.
`boolean` `setParserFeature(java.lang.String uri, boolean flag)` Sets a parser feature, and fails here enabling us to set all the following features.
`void` `setSchemaLocations(java.lang.String list)` Sets the list of external real locations where the XML schema may be found.
`abstract void` `startElement(java.lang.String uri, java.lang.String local, java.lang.String raw, org.xml.sax.Attributes attrs)` An empty implementation is provided by DefaultHandler of ContentHandler.
`abstract void` `startParser(java.lang.String file)` Start the parser.
`void` `testForFile(java.lang.String file)` Tests whether the file exists or not.

### 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

#### DEFAULT_PARSER_NAME

    protected final java.lang.String DEFAULT_PARSER_NAME

Default parser name. Using Xerces at present.

See Also:
  Constant Field Values

#### mLocator

    protected org.xml.sax.Locator mLocator

Locator object to determine on which line in the xml has the error occured.

#### mTextContent

    protected java.lang.StringBuffer mTextContent

Holds the text in an element (text between start and final tags if any). Used in case of elements of mixed type.

#### mLogger

    protected LogManager mLogger

The LogManager object which logs the Pegasus messages.

#### mLogMsg

    protected java.lang.String mLogMsg

The String which contains the messages to be logged.

#### mParser

    protected org.xml.sax.XMLReader mParser

The object which is used to parse the dax. This reads the XML document and sends it to the event handlers.

#### mProps

    protected PegasusProperties mProps

The object holding all the properties pertaining to Pegasus.

#### mTextString

    protected java.lang.String mTextString

A String that holds the contents of data passed as text. The string should only be trimmed when the appropriate end tag of the element is invoked. At this point, a whitespace is added if there are whitespaces in at the ends.

#### mAdjFName

    protected boolean mAdjFName

Boolean flag to ensure that two adjacent filenames are separated by a whitespace.

### Constructor Detail

#### Parser

    public Parser(PegasusBag bag)

Intialises the parser. Sets the various features. However the parsing is done in the implementing class, by call mParser.parse(filename).

Parameters:
  `bag` - the bag of objects that is useful for initialization.

#### Parser

    public Parser(PegasusProperties properties)

Intialises the parser. Sets the various features. However the parsing is done in the implementing class, by call mParser.parse(filename).

Parameters:
  `properties` - the properties passed at runtime.

### Method Detail

#### startElement

    public abstract void startElement(java.lang.String uri,
                                      java.lang.String local,
                                      java.lang.String raw,
                                      org.xml.sax.Attributes attrs)
                               throws org.xml.sax.SAXException

An empty implementation is provided by DefaultHandler of ContentHandler. This method receives the notification from the sacks parser when start tag of an element comes. Any parser class must implement this method.

Specified by:
  `startElement` in interface `org.xml.sax.ContentHandler`
Overrides:
  `startElement` in class `org.xml.sax.helpers.DefaultHandler`
Throws:
  `org.xml.sax.SAXException`

#### endElement

    public abstract void endElement(java.lang.String uri,
                                    java.lang.String localName,
                                    java.lang.String qName)
                             throws org.xml.sax.SAXException

An empty implementation is provided by DefaultHandler class. This method is called automatically by the Sax parser when the end tag of an element comes in the xml file. Any parser class should implement this method

Specified by:
  `endElement` in interface `org.xml.sax.ContentHandler`
Overrides:
  `endElement` in class `org.xml.sax.helpers.DefaultHandler`
Throws:
  `org.xml.sax.SAXException`

#### endDocument

    public abstract void endDocument()

This is called automatically when the end of the XML file is reached.

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

#### startParser

    public abstract void startParser(java.lang.String file)

Start the parser. This starts the parsing of the file by the parser.

Parameters:
  `file` - the path to the XML file you want to parse.

#### getSchemaLocation

    public abstract java.lang.String getSchemaLocation()

Helps the load database to locate the XML schema, if available. Please note that the schema location URL in the instance document is only a hint, and may be overriden by the findings of this method.

Returns:
  a location pointing to a definition document of the XML schema that can read VDLx. Result may be null, if such a document is unknown or unspecified.

#### getSchemaNamespace

    public abstract java.lang.String getSchemaNamespace()

Returns the XML schema namespace that a document being parsed conforms to.

Returns:
  the schema namespace

#### 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.

#### characters

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

This is used to store the character data that is in xml. An implementation of the interface for the Sacks parser.

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

#### ignoreWhitespace

    public java.lang.String ignoreWhitespace(java.lang.String str)

Our own implementation for ignorable whitespace. A String that holds the contents of data passed as text by the underlying parser. The whitespaces at the end are replaced by one whitespace.

Parameters:
  `str` - The string that contains whitespaces.
Returns:
  String corresponding to the trimmed version.

#### ignoreWhitespace

    public java.lang.String ignoreWhitespace(java.lang.String str,
                                             boolean preserveLineBreak)

Our own implementation for ignorable whitespace. A String that holds the contents of data passed as text by the underlying parser. The whitespaces at the end are replaced by one whitespace.

Parameters:
  `str` - The string that contains whitespaces.
Returns:
  String corresponding to the trimmed version.

#### setDocumentLocator

    public void setDocumentLocator(org.xml.sax.Locator loc)

Overrides the empty implementation provided by Default Handler and sets the locator variable for the locator.

Specified by:
  `setDocumentLocator` in interface `org.xml.sax.ContentHandler`
Overrides:
  `setDocumentLocator` in class `org.xml.sax.helpers.DefaultHandler`
Parameters:
  `loc` - the Locator object which keeps the track as to the line numbers of the line being parsed.

#### testForFile

    public void testForFile(java.lang.String file)
                     throws java.io.FileNotFoundException

Tests whether the file exists or not.

Throws:
  `java.io.FileNotFoundException`

#### createParserInstance

    private void createParserInstance()

Creates an instance of the parser, and sets the various options to it.

#### setParserFeature

    public boolean setParserFeature(java.lang.String uri,
                                    boolean flag)

Sets a parser feature, and fails here enabling us to set all the following features.

Parameters:
  `uri` - is the feature's URI to modify
  `flag` - is the new value to set.
Returns:
  true if the feature could be set, else false for an exception.