com.aliasi.xml
Class DelegatingHandler

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by com.aliasi.xml.SimpleElementHandler
          extended by 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
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
 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, DefaultHandler handler)
          This method will be called whenever the close tag for the specified element is found.
 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, 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,
                        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,
                           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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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.