gnu.xml.pipeline
Class EventFilter

java.lang.Object
  |
  +--gnu.xml.pipeline.EventFilter

All Implemented Interfaces:

ContentHandler, DeclHandler, DTDHandler, EventConsumer, LexicalHandler

Direct Known Subclasses:

LinkFilter, NSFilter, ValidationConsumer, WellFormednessFilter

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:

• To serve as a passthrough, sending all events to a second consumer. The second consumer may be identified through getNext().
• To serve as a dead end, with all handlers null; getNext() returns null.

Additionally, SAX handlers may be provided, which completely replace handlers from the consumer provided through the constructor. To make it easier to build specialized filter classes, this class implements all the standard SAX consumer handlers, and those implementations will delegate 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, and then itself registers as a handler (for those interfaces) to the base class using a call such as setContentHandler(this). That way, those overridden methods will intercept those event callbacks, and all other event callbacks will pass events to the next consumer. Overridden methods may invoke superclass methods (perhaps after modifying parameters) should they wish to delegate such calls. Such subclasses should use shared ErrorHandler to report errors.

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 the events on, or null handlers.

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

• This fully separates consumer and producer roles: it does not implement the producer side XMLReader or EntityResolver interfaces, so it can only be used in "push" mode (it has no parse() methods).
• "Extension" handlers are fully supported, enabling a richer set of application requirements. And it implements EventConsumer, which groups related consumer methods together, rather than leaving them separated.
• ErrorHandler support is separated, on the grounds that pipeline stages need to share the same error handling policy.
• The chaining which is visible is to the next consumer, not to the preceding producer. It supports "fan-in", where a consumer can be fed by several producers. (For "fan-out", see the TeeConsumer class.)
• The chaining is set up differently. It is intended to be set up fron terminus towards producer, during filter construction, as described above. This is part of an early binding model; events don't need to pass through stages which ignore them.

The bind(org.xml.sax.XMLReader, gnu.xml.pipeline.EventConsumer) 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/07/11 16:56:24 $

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 e, java.lang.String a, java.lang.String b, java.lang.String c, java.lang.String d) 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	characters(char[] buf, int off, int len) SAX2: passes this callback to the next consumer, if any
void	comment(char[] buf, int off, int len) 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 ns, java.lang.String l, java.lang.String n) 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 p) SAX2: passes this callback to the next consumer, if any
void	externalEntityDecl(java.lang.String name, java.lang.String pub, java.lang.String sys) 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[] buf, int off, int len) 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 s1, java.lang.String s2, java.lang.String s3) 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 l) 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 on 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 n) 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 root, java.lang.String p, java.lang.String s) SAX2: passes this callback to the next consumer, if any
void	startElement(java.lang.String ns, java.lang.String l, java.lang.String name, 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 p, java.lang.String u) SAX2: passes this callback to the next consumer, if any
void	unparsedEntityDecl(java.lang.String s1, java.lang.String s2, java.lang.String s3, java.lang.String s4) 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.

PROPERTY_URI

public static final java.lang.String PROPERTY_URI

SAX2 URI prefix for standard properties (mostly for handlers).

DECL_HANDLER

public static final java.lang.String DECL_HANDLER

SAX2 property identifier for DeclHandler events

LEXICAL_HANDLER

public static final java.lang.String LEXICAL_HANDLER

SAX2 property identifier for LexicalHandler events

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.

• NSFilter will be removed if the producer can be told not to discard namespace data, using the "namespace-prefixes" feature flag.
• ValidationConsumer will be removed if the producer can be told to validate, using the "validation" feature flag.
• WellFormednessFilter is always removed, on the grounds that no XMLReader is permitted to producee malformed event streams and this would just be processing overhead.
• The first consumer which is not one of those classes stops such special handling. This means that if you want to force one of those filters to be used, you could just precede it with an instance of EventFilter configured as a pass-through. You might need to do that if you are using an NSFilter subclass to fix names found in attributes or character data.

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

setErrorHandler

public final void setErrorHandler(ErrorHandler handler)

Records the error handler that should be used by this stage, and passes it on to any subsequent stage.

Specified by:

setErrorHandler in interface EventConsumer

Following copied from interface: gnu.xml.pipeline.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.

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

Following copied from interface: gnu.xml.pipeline.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 l)

SAX2: passes this callback to the next consumer, if any

Specified by:

setDocumentLocator in interface ContentHandler

Following copied from interface: org.xml.sax.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

Following copied from interface: org.xml.sax.ContentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.endDocument()

skippedEntity

public void skippedEntity(java.lang.String n)
                   throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

skippedEntity in interface ContentHandler

Following copied from interface: org.xml.sax.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

Following copied from interface: org.xml.sax.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[] buf,
                       int off,
                       int len)
                throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

characters in interface ContentHandler

Following copied from interface: org.xml.sax.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[] buf,
                                int off,
                                int len)
                         throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

ignorableWhitespace in interface ContentHandler

Following copied from interface: org.xml.sax.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 p,
                               java.lang.String u)
                        throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

startPrefixMapping in interface ContentHandler

Following copied from interface: org.xml.sax.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 ns,
                         java.lang.String l,
                         java.lang.String name,
                         Attributes atts)
                  throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

startElement in interface ContentHandler

Following copied from interface: org.xml.sax.ContentHandler

Parameters:

uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

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 ns,
                       java.lang.String l,
                       java.lang.String n)
                throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

endElement in interface ContentHandler

Following copied from interface: org.xml.sax.ContentHandler

Parameters:

uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.

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 p)
                      throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

endPrefixMapping in interface ContentHandler

Following copied from interface: org.xml.sax.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

Following copied from interface: org.xml.sax.ContentHandler

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

ContentHandler.startDocument()

unparsedEntityDecl

public void unparsedEntityDecl(java.lang.String s1,
                               java.lang.String s2,
                               java.lang.String s3,
                               java.lang.String s4)
                        throws SAXException

SAX1: passes this callback to the next consumer, if any

Specified by:

unparsedEntityDecl in interface DTDHandler

Following copied from interface: org.xml.sax.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.

notation - name 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), AttributeList

notationDecl

public void notationDecl(java.lang.String s1,
                         java.lang.String s2,
                         java.lang.String s3)
                  throws SAXException

SAX1: passes this callback to the next consumer, if any

Specified by:

notationDecl in interface DTDHandler

Following copied from interface: org.xml.sax.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), AttributeList

startDTD

public void startDTD(java.lang.String root,
                     java.lang.String p,
                     java.lang.String s)
              throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

startDTD in interface LexicalHandler

Following copied from interface: org.xml.sax.ext.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.

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

Following copied from interface: org.xml.sax.ext.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[] buf,
                    int off,
                    int len)
             throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

comment in interface LexicalHandler

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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 e,
                          java.lang.String a,
                          java.lang.String b,
                          java.lang.String c,
                          java.lang.String d)
                   throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

attributeDecl in interface DeclHandler

Following copied from interface: org.xml.sax.ext.DeclHandler

Parameters:

eName - The name of the associated element.

aName - The name of the attribute.

type - A string representing the attribute type.

valueDefault - A string representing the attribute default ("#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 pub,
                               java.lang.String sys)
                        throws SAXException

SAX2: passes this callback to the next consumer, if any

Specified by:

externalEntityDecl in interface DeclHandler

Following copied from interface: org.xml.sax.ext.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

Following copied from interface: org.xml.sax.ext.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)