com.aliasi.xml

Class DelegatingHandler

java.lang.Object

org.xml.sax.helpers.DefaultHandler

com.aliasi.xml.SimpleElementHandler

com.aliasi.xml.DelegatingHandler

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler

public class DelegatingHandler
extends SimpleElementHandler

A DelegatingHandler is a SAX filter that routes events to embedded handlers based on their element embedding. Although delegating handler can be embedded inside one another for recursive embedding, it is more efficient to use instances of DelegateHandler below the top level. This allows what would otherwise be recursion on the execution stack to be represented internally to this class. Directly embedding delegating handlers may lead to stack overflow.

Together with delegate handlers, delegating handlers implement some of the same functionality as the Apache Commons Digester. The difference is that there are no XPath specifications in LingPipe's delegating handler and all delegation is handled programatically in one step, not by pattern matching as in XPath. The result is that LingPipe's handlers will be much more efficient than the Digester's in situations where their functionality is adequate.

Since:

LingPipe2.0

Version:

3.8

Author:

Bob Carpenter

Field Summary

Fields inherited from class com.aliasi.xml.SimpleElementHandler

CDATA_ATTS_TYPE, EMPTY_ATTS, NO_OP_DEFAULT_HANDLER

Constructor Summary

Constructors

Constructor and Description
DelegatingHandler() Construct a delegating handler with delegation depth 512.
DelegatingHandler(int maxDelegationDepth) Construct a delegating handler with up to the specified maximum delegation depth.

Method Summary

Methods

Modifier and Type	Method and Description
void	characters(char[] ch, int start, int length) Call delegated or ignored.
void	endElement(String namespaceURI, String localName, String qName) Call is delegated to the delegate and may trigger a finish delegate callback.
void	endPrefixMapping(String prefix) Call delegated.
void	error(SAXParseException exception) Call delegated.
void	fatalError(SAXParseException exception) Call delegated.
void	finishDelegate(String qName, org.xml.sax.helpers.DefaultHandler handler) This method will be called whenever the close tag for the specified element is found.
org.xml.sax.helpers.DefaultHandler	getDelegate(String qName) Returns the delegate for the specified qualified element name.
void	ignorableWhitespace(char[] ch, int start, int length) Call ignored.
void	notationDecl(String name, String publicId, String systemId) Call delegated.
void	processingInstruction(String target, String data) Call delegated.
InputSource	resolveEntity(String publicId, String systemId) Call delegated.
void	setDelegate(String qName, org.xml.sax.helpers.DefaultHandler handler) Set the specified handler to handle events contains in the the specified element.
void	setDocumentLocator(Locator locator) Call delegated.
void	skippedEntity(String name) Call delegated.
void	startDocument() Sets this handler to start a new document by resetting any internal state.
void	startElement(String namespaceURI, String localName, String qName, Attributes atts) Call delegated.
void	startPrefixMapping(String prefix, String uri) Call delegated.
void	unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Call delegated.
void	warning(SAXParseException exception) Call delegated.

Methods inherited from class com.aliasi.xml.SimpleElementHandler

addSimpleAttribute, characters, characters, characters, characters, createAttributes, createAttributes, createAttributes, createAttributes, createAttributes, createAttributes, endSimpleElement, endSimpleElement, startEndSimpleElement, startEndSimpleElement, startSimpleElement, startSimpleElement, startSimpleElement, startSimpleElement, startSimpleElement, startSimpleElement, startSimpleElement

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

endDocument

Methods inherited from class java.lang.Object

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

Constructor Detail

DelegatingHandler

public DelegatingHandler(int maxDelegationDepth)

Construct a delegating handler with up to the specified maximum delegation depth. This should not exceed the stack size of the JVM. Attempts to exceed the maximum depth will throw an array out of bounds runtime exception.

Parameters:

maxDelegationDepth - Maximum delegation depth.

DelegatingHandler

public DelegatingHandler()

Construct a delegating handler with delegation depth 512.

Method Detail

setDelegate

public void setDelegate(String qName,
               org.xml.sax.helpers.DefaultHandler handler)

Set the specified handler to handle events contains in the the specified element. If the handler is an instance of DelegateHandler, it should be constructed to contain this delegating handler to ensure cooperation on delegation. Setting the delegate handler to null will remove any existing delegation for the specified element.

Note that the element is specified by means of its qualified name, not its base name or URL plus base name.

Parameters:

qName - Qualified name of element.

handler - Handler to accept delegated events.

Throws:

IllegalArgumentException - If the handler is a delegate handler that is tied to a different delegating handler.

finishDelegate

public void finishDelegate(String qName,
                  org.xml.sax.helpers.DefaultHandler handler)

This method will be called whenever the close tag for the specified element is found. The handler provided is the handler that was delegated to handle the specified element. This method is useful for incorporating data extracted by a delegate into a larger data structure.

This is a default no-operation implementation. Subclasses may override it to handle the end of delegates.

Parameters:

qName - Qualified name of element that finished.

handler - Handler that was delegated to handle the specified element.

getDelegate

public org.xml.sax.helpers.DefaultHandler getDelegate(String qName)

Returns the delegate for the specified qualified element name. If a delegate has not been declared for the specified element, the default delegate is returned, which may be null.

Parameters:

qName - Qualified name of delegated element.

Returns:

The delegate for the specified element.

startDocument

public void startDocument()
                   throws SAXException

Sets this handler to start a new document by resetting any internal state.

Specified by:

startDocument in interface ContentHandler

Overrides:

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

Throws:

SAXException - if the contained hanlder throws a SAX exception.

startElement

public void startElement(String namespaceURI,
                String localName,
                String qName,
                Attributes atts)
                  throws SAXException

Call delegated.

Specified by:

startElement in interface ContentHandler

Overrides:

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

Parameters:

namespaceURI - The URI identifying the name space, or null if there isn't one.

localName - Local name of element.

qName - Qualified name of element, which is prefixed with the name space URI and a colon if it is non-null, and is equal to local name if there is no name space specified.

atts - Attributes for this element.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

endElement

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

Call is delegated to the delegate and may trigger a finish delegate callback.

Specified by:

endElement in interface ContentHandler

Overrides:

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

Parameters:

namespaceURI - The URI identifying the name space, or null if there isn't one.

localName - Local name of element.

qName - Qualified name of element, which is prefixed with the name space URI and a colon if it is non-null, and is equal to local name if there is no name space specified.

Throws:

SAXException - if the contained handler throws a SAX exception.

characters

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

Call delegated or ignored.

Specified by:

characters in interface ContentHandler

Overrides:

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

Parameters:

ch - Character array containing characters to handle.

start - Index of first character to handle.

length - Number of characters to handle.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

ignorableWhitespace

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

Call ignored.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

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

Parameters:

ch - Character array containing characters to handle.

start - Index of first character to handle.

length - Number of characters to handle.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

processingInstruction

public void processingInstruction(String target,
                         String data)
                           throws SAXException

Call delegated.

Specified by:

processingInstruction in interface 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 is supplied.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

startPrefixMapping

public void startPrefixMapping(String prefix,
                      String uri)
                        throws SAXException

Call delegated.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

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

Parameters:

prefix - The namespace prefix being declared.

uri - The namespace URI mapped to the prefix.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Call delegated.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

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

Parameters:

prefix - The namespace prefix being declared.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

skippedEntity

public void skippedEntity(String name)
                   throws SAXException

Call delegated.

Specified by:

skippedEntity in interface ContentHandler

Overrides:

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

Parameters:

name - The name of the skipped entity.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

setDocumentLocator

public void setDocumentLocator(Locator locator)

Call delegated.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

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

Parameters:

locator - A locator for all SAX document events.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

resolveEntity

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

Call delegated.

Specified by:

resolveEntity in interface EntityResolver

Overrides:

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

Parameters:

publicId - The public identifier, or null if none is available.

systemId - The system identifier provided in the XML document.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

error

public void error(SAXParseException exception)
           throws SAXException

Call delegated.

Specified by:

error in interface ErrorHandler

Overrides:

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

Parameters:

exception - The error information, encoded as an exception.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

fatalError

public void fatalError(SAXParseException exception)
                throws SAXException

Call delegated.

Specified by:

fatalError in interface ErrorHandler

Overrides:

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

Parameters:

exception - The fatal error information, encoded as an exception.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

warning

public void warning(SAXParseException exception)
             throws SAXException

Call delegated.

Specified by:

warning in interface ErrorHandler

Overrides:

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

Parameters:

exception - The warning information, encoded as an exception.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

notationDecl

public void notationDecl(String name,
                String publicId,
                String systemId)
                  throws SAXException

Call delegated.

Specified by:

notationDecl in interface DTDHandler

Overrides:

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

Parameters:

name - The notation name.

publicId - The notation public identifier, or null if none is available.

systemId - The notation system identifier.

Throws:

SAXException - if the contained hanlder throws a SAX exception.

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                      String publicId,
                      String systemId,
                      String notationName)
                        throws SAXException

Call delegated.

Specified by:

unparsedEntityDecl in interface DTDHandler

Overrides:

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

Parameters:

name - The entity name.

publicId - The entity public identifier, or null if none is available.

systemId - The entity system identifier.

notationName - The name of the associated notation.

Throws:

SAXException - if the contained hanlder throws a SAX exception.