org.apache.tapestry.util.xml
Class RuleDirectedParser

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.apache.tapestry.util.xml.RuleDirectedParser

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class RuleDirectedParser
extends DefaultHandler

A simplified version of org.apache.commons.digester.Digester. This version is without as many bells and whistles but has some key features needed when parsing a document (rather than a configuration file):

• Notifications for each bit of text
• Tracking of exact location within the document.

Like Digester, there's an object stack and a rule stack. The rules are much simpler (more coding), in that there's a one-to-one relationship between an element and a rule.

Based on SAX2.

Since:

3.0

Author:

Howard Lewis Ship

Constructor Summary

RuleDirectedParser()

Method Summary

void	addRule(String localElementName, IRule rule)
void	characters(char[] ch, int start, int length) Accumulates the content in a buffer; the concatinated content is provided to the top rule just before any start or end tag.
protected void	configureParserFactory(SAXParserFactory factory) Configures a SAXParserFactorybefore SAXParserFactory.newSAXParser()is invoked.
protected SAXParser	constructParser() Uses SAXParserFactoryto create a instance of a validation SAX2 parser.
void	endElement(String uri, String localName, String qName) Pops the top rule off the stack and invokes IRule.endElement(RuleDirectedParser).
void	error(SAXParseException ex) Throws the exception.
void	fatalError(SAXParseException ex) Throws the exception.
org.apache.hivemind.Resource	getDocumentLocation()
String	getLocalName() Returns the localName for the current element.
org.apache.hivemind.Location	getLocation() Returns an Locationrepresenting the current position within the document (depending on the parser, this may be accurate to column number level).
String	getQName() Returns the qualified name for the current element.
String	getUri() Returns the URI for the current element.
void	ignorableWhitespace(char[] ch, int start, int length) Ignorable content is ignored.
Object	parse(org.apache.hivemind.Resource documentLocation)
protected Object	parse(URL url)
Object	peek() Returns the top object on the object stack.
Object	peek(int depth) Returns an object within the object stack, at depth.
protected IRule	peekRule() Returns the top rule on the stack.
Object	pop() Removes and returns the top object on the object stack.
protected IRule	popRule()
void	push(Object object) Pushes an object onto the object stack.
protected void	pushRule(IRule rule) Pushes a new rule onto the rule stack.
void	registerEntity(String publicId, String entityPath) Registers a public id and corresponding input source.
InputSource	resolveEntity(String publicId, String systemId)
protected IRule	selectRule(String localName, Attributes attributes)
void	setDocumentLocator(Locator locator) Uses the Locatorto track the position in the document as a Location.
void	startElement(String uri, String localName, String qName, Attributes attributes) Invokes selectRule(String, Attributes)to choose a new rule, which is pushed onto the rule stack, then invokes IRule.startElement(RuleDirectedParser, Attributes).
void	validate(String value, String pattern, String errorKey) Validates that the input value matches against the specified Perl5 pattern.
void	warning(SAXParseException ex) Throws the exception.

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

RuleDirectedParser

public RuleDirectedParser()

Method Detail

parse

public Object parse(org.apache.hivemind.Resource documentLocation)

parse

protected Object parse(URL url)

getLocation

public org.apache.hivemind.Location getLocation()

Returns an Locationrepresenting the current position within the document (depending on the parser, this may be accurate to column number level).

push

public void push(Object object)

Pushes an object onto the object stack. The first object pushed is the "document object", the root object returned by the parse.

peek

public Object peek()

Returns the top object on the object stack.

peek

public Object peek(int depth)

Returns an object within the object stack, at depth. Depth 0 is the top object, depth 1 is the next-to-top object, etc.

pop

public Object pop()

Removes and returns the top object on the object stack.

pushRule

protected void pushRule(IRule rule)

Pushes a new rule onto the rule stack.

peekRule

protected IRule peekRule()

Returns the top rule on the stack.

popRule

protected IRule popRule()

addRule

public void addRule(String localElementName,
                    IRule rule)

registerEntity

public void registerEntity(String publicId,
                           String entityPath)

Registers a public id and corresponding input source. Generally, the source is a wrapper around an input stream to a package resource.

Parameters:

publicId - the public identifier to be registerred, generally the publicId of a DTD related to the document being parsed

entityPath - the resource path of the entity, typically a DTD file. Relative files names are expected to be stored in the same package as the class file, otherwise a leading slash is an absolute pathname within the classpath.

selectRule

protected IRule selectRule(String localName,
                           Attributes attributes)

setDocumentLocator

public void setDocumentLocator(Locator locator)

Uses the Locatorto track the position in the document as a Location. This is invoked once (before the initial element is parsed) and the Locator is retained and queried as to the current file location.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

setDocumentLocator in class DefaultHandler

See Also:

getLocation()

characters

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

Accumulates the content in a buffer; the concatinated content is provided to the top rule just before any start or end tag.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class DefaultHandler

Throws:

SAXException

endElement

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

Pops the top rule off the stack and invokes IRule.endElement(RuleDirectedParser).

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class DefaultHandler

Throws:

SAXException

ignorableWhitespace

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

Ignorable content is ignored.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class DefaultHandler

Throws:

SAXException

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes attributes)
                  throws SAXException

Invokes selectRule(String, Attributes)to choose a new rule, which is pushed onto the rule stack, then invokes IRule.startElement(RuleDirectedParser, Attributes).

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class DefaultHandler

Throws:

SAXException

constructParser

protected SAXParser constructParser()

Uses SAXParserFactoryto create a instance of a validation SAX2 parser.

configureParserFactory

protected void configureParserFactory(SAXParserFactory factory)

Configures a SAXParserFactorybefore SAXParserFactory.newSAXParser()is invoked. The default implementation sets validating to true and namespaceAware to false,

error

public void error(SAXParseException ex)
           throws SAXException

Throws the exception.

Specified by:

error in interface ErrorHandler

Overrides:

error in class DefaultHandler

Throws:

SAXException

fatalError

public void fatalError(SAXParseException ex)
                throws SAXException

Throws the exception.

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class DefaultHandler

Throws:

SAXException

warning

public void warning(SAXParseException ex)
             throws SAXException

Throws the exception.

Specified by:

warning in interface ErrorHandler

Overrides:

warning in class DefaultHandler

Throws:

SAXException

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException

Specified by:

resolveEntity in interface EntityResolver

Overrides:

resolveEntity in class DefaultHandler

Throws:

SAXException

validate

public void validate(String value,
                     String pattern,
                     String errorKey)

Validates that the input value matches against the specified Perl5 pattern. If valid, the method simply returns. If not a match, then an error message is generated (using the errorKey and the input value) and a InvalidStringExceptionis thrown.

getDocumentLocation

public org.apache.hivemind.Resource getDocumentLocation()

getLocalName

public String getLocalName()

Returns the localName for the current element.

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

getQName

public String getQName()

Returns the qualified name for the current element.

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

getUri

public String getUri()

Returns the URI for the current element.

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)