org.apache.hivemind.parse
Class AbstractParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.apache.hivemind.parse.AbstractParser

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

Direct Known Subclasses:

DescriptorParser

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

Abstract super-class for parsers based around the SAX event model. This class provides support for managing a stack of elements, making it reasonable to establish relationships between elements. It also assists in setting the Location of elements as they are created.

This support is structured around both XML but is suited towards configuration files rather than documents, in that the content (parsable character data) within an element is concatinated together and tracked as a single blob.

Author:

Howard Lewis Ship

Constructor Summary

AbstractParser()

Method Summary

protected abstract void	begin(java.lang.String elementName, java.util.Map attributes) Invoked when an element's start tag is recognized.
void	characters(char[] ch, int start, int length) Accepts parseable character data from within an element and applies it to the top stack element.
protected abstract void	end(java.lang.String elementName) Invoked when an element's close tag is recognized.
void	endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)
void	error(org.xml.sax.SAXParseException ex) Invokes fatalError(SAXParseException).
void	fatalError(org.xml.sax.SAXParseException ex)
protected java.lang.String	getElementPath() Returns a "path" to the current element, as a series of element names seperated by slashes, i.e., "top/middle/leaf".
protected Location	getLocation() Returns the current lcoation, as reported by the parser.
protected Resource	getResource() Returns the Resource being parsed (as set by initializeParser(Resource, int).
protected int	getState() Returns the current state of the parser.
protected void	initializeParser(Resource resource, int startState) Initializes the parser; this should be called before any SAX parse events are received.
protected java.lang.String	peekContent() Peeks at the top element on the stack, and returns its content (the accumuulated parseable character data directly enclosed by its start/end tags.
protected java.lang.String	peekElementName() Peeks at the top element on the stack and returns its element name.
protected java.lang.Object	peekObject() Peeks at the top element on the stack and returns the object for that element.
protected void	pop() Invoked when the closing tag for an element is enountered {i.e, from endElement(String, String, String).
protected void	push(java.lang.String elementName, java.lang.Object object, int state) Enters a new state, pushing an object onto the stack.
protected void	push(java.lang.String elementName, java.lang.Object object, int state, boolean ignoreCharacterData) Enters a new state, pusubhing an object onto the stack.
protected void	resetParser() Resets all state after a parse.
void	setDocumentLocator(org.xml.sax.Locator locator) Invoked by the parser, the locator is stored and later used by getLocation().
protected void	setState(int state) Forces a change to a specific state.
void	startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attributes)
protected void	unexpectedElement(java.lang.String elementName) Invoked when an unexpected element is parsed (useful for parses that don't perform validation, or when there's no DTD).
protected void	updateObject(java.lang.Object object) Ocassionaly it is necessary to "change our mind" about what's on the top of the stack.
void	warning(org.xml.sax.SAXParseException ex) Invokes fatalError(SAXParseException).

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

endDocument, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractParser

public AbstractParser()

Method Detail

characters

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

Accepts parseable character data from within an element and applies it to the top stack element. This may be invoked multiple times by the parser, and the overall data will accumulate. This content can be retrieved via peekContent().

Specified by:

characters in interface org.xml.sax.ContentHandler

Overrides:

characters in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

error

public void error(org.xml.sax.SAXParseException ex)
           throws org.xml.sax.SAXException

Invokes fatalError(SAXParseException).

Specified by:

error in interface org.xml.sax.ErrorHandler

Overrides:

error in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

fatalError

public void fatalError(org.xml.sax.SAXParseException ex)
                throws org.xml.sax.SAXException

Specified by:

fatalError in interface org.xml.sax.ErrorHandler

Overrides:

fatalError in class org.xml.sax.helpers.DefaultHandler

Parameters:

ex - exception to be thrown

Throws:

org.xml.sax.SAXParseException

org.xml.sax.SAXException

getElementPath

protected java.lang.String getElementPath()

Returns a "path" to the current element, as a series of element names seperated by slashes, i.e., "top/middle/leaf".

getLocation

protected Location getLocation()

Returns the current lcoation, as reported by the parser.

getResource

protected Resource getResource()

Returns the Resource being parsed (as set by initializeParser(Resource, int).

getState

protected int getState()

Returns the current state of the parser. State is initially set by initializeParser(Resource, int) and is later updated by push(String, Object, int, boolean) and pop().

initializeParser

protected void initializeParser(Resource resource,
                                int startState)

Initializes the parser; this should be called before any SAX parse events are received.

Parameters:

resource - the resource being parsed (used for some error messages)

startState - the initial state of the parser (the interpretation of state is determined by subclasses)

peekContent

protected java.lang.String peekContent()

Peeks at the top element on the stack, and returns its content (the accumuulated parseable character data directly enclosed by its start/end tags.

peekElementName

protected java.lang.String peekElementName()

Peeks at the top element on the stack and returns its element name.

peekObject

protected java.lang.Object peekObject()

Peeks at the top element on the stack and returns the object for that element.

pop

protected void pop()

Invoked when the closing tag for an element is enountered {i.e, from endElement(String, String, String). This removes the corresponding item from the stack, and sets the parser state back to the (new) top element's state.

push

protected void push(java.lang.String elementName,
                    java.lang.Object object,
                    int state)

Enters a new state, pushing an object onto the stack. Invokes push(String, Object, int, boolean), and ignores character data within the element.

Parameters:

elementName - the element whose start tag was just parsed

object - the object created to represent the new object

state - the new state for the parse

push

protected void push(java.lang.String elementName,
                    java.lang.Object object,
                    int state,
                    boolean ignoreCharacterData)

Enters a new state, pusubhing an object onto the stack. If the object implements LocationHolder then its location property is set to the current location.

Parameters:

elementName - the element whose start tag was just parsed

object - the object created to represent the new object

state - the new state for the parse

ignoreCharacterData - if true, then any character data (typically whitespace) directly enclosed by the element is ignored

resetParser

protected void resetParser()

Resets all state after a parse.

setDocumentLocator

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

Invoked by the parser, the locator is stored and later used by getLocation().

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

Overrides:

setDocumentLocator in class org.xml.sax.helpers.DefaultHandler

setState

protected void setState(int state)

Forces a change to a specific state.

unexpectedElement

protected void unexpectedElement(java.lang.String elementName)

Invoked when an unexpected element is parsed (useful for parses that don't perform validation, or when there's no DTD).

Throws:

ApplicationRuntimeException - describing the situation

updateObject

protected void updateObject(java.lang.Object object)

Ocassionaly it is necessary to "change our mind" about what's on the top of the stack.

Parameters:

object - the new object for the top stack element

warning

public void warning(org.xml.sax.SAXParseException ex)
             throws org.xml.sax.SAXException

Invokes fatalError(SAXParseException).

Specified by:

warning in interface org.xml.sax.ErrorHandler

Overrides:

warning in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

begin

protected abstract void begin(java.lang.String elementName,
                              java.util.Map attributes)

Invoked when an element's start tag is recognized. The element and attributes are provided to the subclass for further processing.

end

protected abstract void end(java.lang.String elementName)

Invoked when an element's close tag is recognized. The element is provided. The content of the element (the unparsed whitespace within the element's tags) is available via peekContent().

endElement

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

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

endElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

startElement

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attributes)
                  throws org.xml.sax.SAXException

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

startElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException