gnu.xml.pipeline
Class EventFilter

java.lang.Object
  extended by gnu.xml.pipeline.EventFilter
All Implemented Interfaces:
EventConsumer, ContentHandler, DTDHandler, DeclHandler, LexicalHandler
Direct Known Subclasses:
LinkFilter, NSFilter, ValidationConsumer, WellFormednessFilter, XIncludeFilter, XsltFilter

public class EventFilter
extends java.lang.Object
implements EventConsumer, ContentHandler, DTDHandler, LexicalHandler, DeclHandler

A customizable event consumer, used to assemble various kinds of filters using SAX handlers and an optional second consumer. It can be constructed in two ways:

Additionally, SAX handlers may be assigned, which completely replace the "upstream" view (through EventConsumer) of handlers, initially null or the "next" consumer provided to the constructor. To make it easier to build specialized filter classes, this class implements all the standard SAX consumer handlers, and those implementations delegate "downstream" to the consumer accessed by getNext().

The simplest way to create a custom a filter class is to create a subclass which overrides one or more handler interface methods. The constructor for that subclass then registers itself as a handler for those interfaces using a call such as setContentHandler(this), so the "upstream" view of event delivery is modified from the state established in the base class constructor. That way, the overridden methods intercept those event callbacks as they go "downstream", and all other event callbacks will pass events to any next consumer. Overridden methods may invoke superclass methods (perhaps after modifying parameters) if they wish to delegate such calls. Such subclasses should use getErrorHandler() to report errors using the common error reporting mechanism.

Another important technique is to construct a filter consisting of only a few specific types of handler. For example, one could easily prune out lexical events or various declarations by providing handlers which don't pass those events downstream, or by providing null handlers.


This may be viewed as the consumer oriented analogue of the SAX2 XMLFilterImpl class. Key differences include:

The chainTo() convenience routine supports chaining to an XMLFilterImpl, in its role as a limited functionality event consumer. Its event producer role (XMLFilter) is ignored.


The bind() routine may be used associate event pipelines with any kind of XMLReader that will produce the events. Such pipelines don't necessarily need to have any members which are implemented using this class. That routine has some intelligence which supports automatic changes to parser feature flags, letting event piplines become largely independent of the particular feature sets of parsers.

Version:
$Date: 2001/11/11 03:27:56 $
Author:
David Brownell

Field Summary
static java.lang.String DECL_HANDLER
          SAX2 property identifier for DeclHandler events
static java.lang.String FEATURE_URI
          SAX2 URI prefix for standard feature flags.
static java.lang.String LEXICAL_HANDLER
          SAX2 property identifier for LexicalHandler events
static java.lang.String PROPERTY_URI
          SAX2 URI prefix for standard properties (mostly for handlers).
 
Constructor Summary
EventFilter()
          Initializes all handlers to null.
EventFilter(EventConsumer consumer)
          Handlers that are not otherwise set will default to those from the specified consumer, making it easy to pass events through.
 
Method Summary
 void attributeDecl(java.lang.String eName, java.lang.String aName, java.lang.String type, java.lang.String mode, java.lang.String value)
          SAX2: passes this callback to the next consumer, if any
static void bind(XMLReader producer, EventConsumer consumer)
          Binds the standard SAX2 handlers from the specified consumer pipeline to the specified producer.
 void chainTo(XMLFilterImpl next)
          Treats the XMLFilterImpl as a limited functionality event consumer, by arranging to deliver events to it; this lets such classes be "wrapped" as pipeline stages.
 void characters(char[] ch, int start, int length)
          SAX2: passes this callback to the next consumer, if any
 void comment(char[] ch, int start, int length)
          SAX2: passes this callback to the next consumer, if any
 void elementDecl(java.lang.String name, java.lang.String model)
          SAX2: passes this callback to the next consumer, if any
 void endCDATA()
          SAX2: passes this callback to the next consumer, if any
 void endDocument()
          SAX2: passes this callback to the next consumer, if any
 void endDTD()
          SAX2: passes this callback to the next consumer, if any
 void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)
          SAX2: passes this callback to the next consumer, if any
 void endEntity(java.lang.String name)
          SAX2: passes this callback to the next consumer, if any.
 void endPrefixMapping(java.lang.String prefix)
          SAX2: passes this callback to the next consumer, if any
 void externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          SAX2: passes this callback to the next consumer, if any
 ContentHandler getContentHandler()
          Returns the content handler being used.
 Locator getDocumentLocator()
          Returns any locator provided to the next consumer, if this class (or a subclass) is handling ContentHandler events.
 DTDHandler getDTDHandler()
          Returns the dtd handler being used.
 ErrorHandler getErrorHandler()
          Returns the error handler assigned this filter stage, or null if no such assigment has been made.
 EventConsumer getNext()
          Returns the next event consumer in sequence; or null if there is no such handler.
 java.lang.Object getProperty(java.lang.String id)
          Retrieves a property of unknown intent (usually a handler)
 void ignorableWhitespace(char[] ch, int start, int length)
          SAX2: passes this callback to the next consumer, if any
 void internalEntityDecl(java.lang.String name, java.lang.String value)
          SAX2: passes this callback to the next consumer, if any
 void notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          SAX1: passes this callback to the next consumer, if any
 void processingInstruction(java.lang.String target, java.lang.String data)
          SAX2: passes this callback to the next consumer, if any
 void setContentHandler(ContentHandler h)
          Assigns the content handler to use; a null handler indicates that these events will not be forwarded.
 void setDocumentLocator(Locator locator)
          SAX2: passes this callback to the next consumer, if any
 void setDTDHandler(DTDHandler h)
          Assigns the DTD handler to use; a null handler indicates that these events will not be forwarded.
 void setErrorHandler(ErrorHandler handler)
          Records the error handler that should be used by this stage, and passes it "downstream" to any subsequent stage.
 void setProperty(java.lang.String id, java.lang.Object o)
          Stores the property, normally a handler; a null handler indicates that these events will not be forwarded.
 void skippedEntity(java.lang.String name)
          SAX2: passes this callback to the next consumer, if any
 void startCDATA()
          SAX2: passes this callback to the next consumer, if any
 void startDocument()
          SAX2: passes this callback to the next consumer, if any
 void startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
          SAX2: passes this callback to the next consumer, if any
 void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, Attributes atts)
          SAX2: passes this callback to the next consumer, if any
 void startEntity(java.lang.String name)
          SAX2: passes this callback to the next consumer, if any.
 void startPrefixMapping(java.lang.String prefix, java.lang.String uri)
          SAX2: passes this callback to the next consumer, if any
 void unparsedEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notationName)
          SAX1: passes this callback to the next consumer, if any
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FEATURE_URI

public static final java.lang.String FEATURE_URI
SAX2 URI prefix for standard feature flags.

See Also:
Constant Field Values

PROPERTY_URI

public static final java.lang.String PROPERTY_URI
SAX2 URI prefix for standard properties (mostly for handlers).

See Also:
Constant Field Values

DECL_HANDLER

public static final java.lang.String DECL_HANDLER
SAX2 property identifier for DeclHandler events

See Also:
Constant Field Values

LEXICAL_HANDLER

public static final java.lang.String LEXICAL_HANDLER
SAX2 property identifier for LexicalHandler events

See Also:
Constant Field Values
Constructor Detail

EventFilter

public EventFilter()
Initializes all handlers to null.


EventFilter

public EventFilter(EventConsumer consumer)
Handlers that are not otherwise set will default to those from the specified consumer, making it easy to pass events through. If the consumer is null, all handlers are initialzed to null.

Method Detail

bind

public static void bind(XMLReader producer,
                        EventConsumer consumer)
Binds the standard SAX2 handlers from the specified consumer pipeline to the specified producer. These handlers include the core ContentHandler and DTDHandler, plus the extension DeclHandler and LexicalHandler. Any additional application-specific handlers need to be bound separately. The ErrorHandler is handled differently: the producer's error handler is passed through to the consumer pipeline.

At the head of the pipeline, certain standard event filters are recognized and handled specially. This facilitates construction of processing pipelines that work regardless of the capabilities of the XMLReader implementation in use; for example, it permits validating output of a DomParser.

Other than that, this method works with any kind of event consumer, not just event filters. Note that in all cases, the standard handlers are assigned; any previous handler assignments for the handler will be overridden.

Parameters:
producer - will deliver events to the specified consumer
consumer - pipeline supplying event handlers to be associated with the producer

chainTo

public void chainTo(XMLFilterImpl next)
Treats the XMLFilterImpl as a limited functionality event consumer, by arranging to deliver events to it; this lets such classes be "wrapped" as pipeline stages.

Upstream Event Setup: If no handlers have been assigned to this EventFilter, then the handlers from specified XMLFilterImpl are returned from this EventConsumer: the XMLFilterImpl is just "wrapped". Otherwise the specified handlers will be returned.

Downstream Event Setup: Subclasses may chain event delivery to the specified XMLFilterImpl by invoking the appropiate superclass methods, as if their constructor passed a "next" EventConsumer to the constructor for this class. If this EventFilter has an ErrorHandler, it is assigned as the error handler for the XMLFilterImpl, just as would be done for a next stage implementing EventConsumer.

Parameters:
next - the next downstream component of the pipeline.
Throws:
java.lang.IllegalStateException - if the "next" consumer has already been set through the constructor.

setErrorHandler

public final void setErrorHandler(ErrorHandler handler)
Records the error handler that should be used by this stage, and passes it "downstream" to any subsequent stage.

Specified by:
setErrorHandler in interface EventConsumer
Parameters:
handler - encapsulates error handling policy for this stage

getErrorHandler

public final ErrorHandler getErrorHandler()
Returns the error handler assigned this filter stage, or null if no such assigment has been made.


getNext

public final EventConsumer getNext()
Returns the next event consumer in sequence; or null if there is no such handler.


setContentHandler

public final void setContentHandler(ContentHandler h)
Assigns the content handler to use; a null handler indicates that these events will not be forwarded. This overrides the previous settting for this handler, which was probably pointed to the next consumer by the base class constructor.


getContentHandler

public final ContentHandler getContentHandler()
Returns the content handler being used.

Specified by:
getContentHandler in interface EventConsumer

setDTDHandler

public final void setDTDHandler(DTDHandler h)
Assigns the DTD handler to use; a null handler indicates that these events will not be forwarded. This overrides the previous settting for this handler, which was probably pointed to the next consumer by the base class constructor.


getDTDHandler

public final DTDHandler getDTDHandler()
Returns the dtd handler being used.

Specified by:
getDTDHandler in interface EventConsumer

setProperty

public final void setProperty(java.lang.String id,
                              java.lang.Object o)
                       throws SAXNotRecognizedException,
                              SAXNotSupportedException
Stores the property, normally a handler; a null handler indicates that these events will not be forwarded. This overrides the previous handler settting, which was probably pointed to the next consumer by the base class constructor.

Throws:
SAXNotRecognizedException
SAXNotSupportedException

getProperty

public final java.lang.Object getProperty(java.lang.String id)
                                   throws SAXNotRecognizedException
Retrieves a property of unknown intent (usually a handler)

Specified by:
getProperty in interface EventConsumer
Parameters:
id - This is a URI identifying the type of property desired.
Returns:
The value of that property, if it is defined.
Throws:
SAXNotRecognizedException - Thrown if the particular pipeline stage does not understand the specified identifier.

getDocumentLocator

public Locator getDocumentLocator()
Returns any locator provided to the next consumer, if this class (or a subclass) is handling ContentHandler events.


setDocumentLocator

public void setDocumentLocator(Locator locator)
SAX2: passes this callback to the next consumer, if any

Specified by:
setDocumentLocator in interface ContentHandler
Parameters:
locator - An object that can return the location of any SAX document event.
See Also:
Locator

startDocument

public void startDocument()
                   throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
startDocument in interface ContentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.endDocument()

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
skippedEntity in interface ContentHandler
Parameters:
name - The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
processingInstruction in interface ContentHandler
Parameters:
target - The processing instruction target.
data - The processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
characters in interface ContentHandler
Parameters:
ch - The characters from the XML document.
start - The start position in the array.
length - The number of characters to read from the array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
ignorableWhitespace in interface ContentHandler
Parameters:
ch - The characters from the XML document.
start - The start position in the array.
length - The number of characters to read from the array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.characters(char[], int, int)

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
startPrefixMapping in interface ContentHandler
Parameters:
prefix - The Namespace prefix being declared.
uri - The Namespace URI the prefix is mapped to.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.endPrefixMapping(java.lang.String), ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

startElement

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         Attributes atts)
                  throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
startElement in interface ContentHandler
localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - The qualified name (with prefix), or the empty string if qualified names are not available.
atts - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String), Attributes

endElement

public void endElement(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName)
                throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
endElement in interface ContentHandler
localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
endPrefixMapping in interface ContentHandler
Parameters:
prefix - The prefix that was being mapping.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.startPrefixMapping(java.lang.String, java.lang.String), ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

endDocument

public void endDocument()
                 throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
endDocument in interface ContentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.startDocument()

unparsedEntityDecl

public void unparsedEntityDecl(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId,
                               java.lang.String notationName)
                        throws SAXException
SAX1: passes this callback to the next consumer, if any

Specified by:
unparsedEntityDecl in interface DTDHandler
Parameters:
name - The unparsed entity's name.
publicId - The entity's public identifier, or null if none was given.
systemId - The entity's system identifier.
notationName - The name of the associated notation.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String), Attributes

notationDecl

public void notationDecl(java.lang.String name,
                         java.lang.String publicId,
                         java.lang.String systemId)
                  throws SAXException
SAX1: passes this callback to the next consumer, if any

Specified by:
notationDecl in interface DTDHandler
Parameters:
name - The notation name.
publicId - The notation's public identifier, or null if none was given.
systemId - The notation's system identifier, or null if none was given.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String), Attributes

startDTD

public void startDTD(java.lang.String name,
                     java.lang.String publicId,
                     java.lang.String systemId)
              throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
startDTD in interface LexicalHandler
Parameters:
name - The document type name.
publicId - The declared public identifier for the external DTD subset, or null if none was declared.
systemId - The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endDTD(), LexicalHandler.startEntity(java.lang.String)

endDTD

public void endDTD()
            throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
endDTD in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startDTD(java.lang.String, java.lang.String, java.lang.String)

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
comment in interface LexicalHandler
Parameters:
ch - An array holding the characters in the comment.
start - The starting position in the array.
length - The number of characters to use from the array.
Throws:
SAXException - The application may raise an exception.

startCDATA

public void startCDATA()
                throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
startCDATA in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endCDATA()

endCDATA

public void endCDATA()
              throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
endCDATA in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startCDATA()

startEntity

public void startEntity(java.lang.String name)
                 throws SAXException
SAX2: passes this callback to the next consumer, if any.

Specified by:
startEntity in interface LexicalHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endEntity(java.lang.String), DeclHandler.internalEntityDecl(java.lang.String, java.lang.String), DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)

endEntity

public void endEntity(java.lang.String name)
               throws SAXException
SAX2: passes this callback to the next consumer, if any.

Specified by:
endEntity in interface LexicalHandler
Parameters:
name - The name of the entity that is ending.
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startEntity(java.lang.String)

elementDecl

public void elementDecl(java.lang.String name,
                        java.lang.String model)
                 throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
elementDecl in interface DeclHandler
Parameters:
name - The element type name.
model - The content model as a normalized string.
Throws:
SAXException - The application may raise an exception.

attributeDecl

public void attributeDecl(java.lang.String eName,
                          java.lang.String aName,
                          java.lang.String type,
                          java.lang.String mode,
                          java.lang.String value)
                   throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
attributeDecl in interface DeclHandler
Parameters:
eName - The name of the associated element.
aName - The name of the attribute.
type - A string representing the attribute type.
mode - A string representing the attribute defaulting mode ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
value - A string representing the attribute's default value, or null if there is none.
Throws:
SAXException - The application may raise an exception.

externalEntityDecl

public void externalEntityDecl(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId)
                        throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
externalEntityDecl in interface DeclHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId - The declared public identifier of the entity, or null if none was declared.
systemId - The declared system identifier of the entity.
Throws:
SAXException - The application may raise an exception.
See Also:
DeclHandler.internalEntityDecl(java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

internalEntityDecl

public void internalEntityDecl(java.lang.String name,
                               java.lang.String value)
                        throws SAXException
SAX2: passes this callback to the next consumer, if any

Specified by:
internalEntityDecl in interface DeclHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
value - The replacement text of the entity.
Throws:
SAXException - The application may raise an exception.
See Also:
DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)


Source code is under GPL (with library exception) in the JAXP project at http://www.gnu.org/software/classpathx/jaxp
This documentation was derived from that source code on 2012-01-06.