Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
gnu.xml.pipeline

Class EventFilter

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

All Implemented Interfaces:

EventConsumer, ContentHandler, DTDHandler, LexicalHandler, DeclHandler


public class EventFilter

extends 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 org.xml.sax.helpers.XMLFilterImpl XMLFilterImpl class. Key differences include:

The #chainTo 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 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.

Author:

Field Summary

static java.lang.StringDECL_HANDLER

SAX2 property identifier for DeclHandler events
static java.lang.StringFEATURE_URI

SAX2 URI prefix for standard feature flags.
static java.lang.StringLEXICAL_HANDLER

SAX2 property identifier for LexicalHandler events
static java.lang.StringPROPERTY_URI

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

Constructor Summary

EventFilter()

Initializes all handlers to null.
EventFilter(gnu.xml.pipeline.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

voidattributeDecl(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 voidbind(org.xml.sax.XMLReader producer, gnu.xml.pipeline.EventConsumer consumer)

Binds the standard SAX2 handlers from the specified consumer pipeline to the specified producer.
voidchainTo(org.xml.sax.helpers.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.
voidcharacters(char ch[][] , int start, int length)

SAX2: passes this callback to the next consumer, if any
voidcomment(char ch[][] , int start, int length)

SAX2: passes this callback to the next consumer, if any
voidelementDecl(java.lang.String name, java.lang.String model)

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

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

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

SAX2: passes this callback to the next consumer, if any
voidendElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)

SAX2: passes this callback to the next consumer, if any
voidendEntity(java.lang.String name)

SAX2: passes this callback to the next consumer, if any.
voidendPrefixMapping(java.lang.String prefix)

SAX2: passes this callback to the next consumer, if any
voidexternalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

SAX2: passes this callback to the next consumer, if any
org.xml.sax.ContentHandlergetContentHandler()

Returns the content handler being used.
org.xml.sax.DTDHandlergetDTDHandler()

Returns the dtd handler being used.
org.xml.sax.LocatorgetDocumentLocator()

Returns any locator provided to the next consumer, if this class (or a subclass) is handling ContentHandler events.
org.xml.sax.ErrorHandlergetErrorHandler()

Returns the error handler assigned this filter stage, or null if no such assigment has been made.
gnu.xml.pipeline.EventConsumergetNext()

Returns the next event consumer in sequence; or null if there is no such handler.
java.lang.ObjectgetProperty(java.lang.String id)

Retrieves a property of unknown intent (usually a handler)
voidignorableWhitespace(char ch[][] , int start, int length)

SAX2: passes this callback to the next consumer, if any
voidinternalEntityDecl(java.lang.String name, java.lang.String value)

SAX2: passes this callback to the next consumer, if any
voidnotationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

SAX1: passes this callback to the next consumer, if any
voidprocessingInstruction(java.lang.String target, java.lang.String data)

SAX2: passes this callback to the next consumer, if any
voidsetContentHandler(org.xml.sax.ContentHandler h)

Assigns the content handler to use; a null handler indicates that these events will not be forwarded.
voidsetDTDHandler(org.xml.sax.DTDHandler h)

Assigns the DTD handler to use; a null handler indicates that these events will not be forwarded.
voidsetDocumentLocator(org.xml.sax.Locator locator)

SAX2: passes this callback to the next consumer, if any
voidsetErrorHandler(org.xml.sax.ErrorHandler handler)

Records the error handler that should be used by this stage, and passes it "downstream" to any subsequent stage.
voidsetProperty(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.
voidskippedEntity(java.lang.String name)

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

SAX2: passes this callback to the next consumer, if any
voidstartDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

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

SAX2: passes this callback to the next consumer, if any
voidstartElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)

SAX2: passes this callback to the next consumer, if any
voidstartEntity(java.lang.String name)

SAX2: passes this callback to the next consumer, if any.
voidstartPrefixMapping(java.lang.String prefix, java.lang.String uri)

SAX2: passes this callback to the next consumer, if any
voidunparsedEntityDecl(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

Field Details

DECL_HANDLER

public static final String DECL_HANDLER

SAX2 property identifier for DeclHandler events


FEATURE_URI

public static final String FEATURE_URI

SAX2 URI prefix for standard feature flags.


LEXICAL_HANDLER

public static final String LEXICAL_HANDLER

SAX2 property identifier for LexicalHandler events


PROPERTY_URI

public static final String PROPERTY_URI

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


Constructor Details

EventFilter

public EventFilter()

Initializes all handlers to null.


EventFilter

public EventFilter(gnu.xml.pipeline.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.

Parameters:


Method Details

attributeDecl

public 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

Parameters:


bind

public static void bind(org.xml.sax.XMLReader producer, gnu.xml.pipeline.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. The producer is told to include namespace prefix information if it can, since many pipeline stages need that Infoset information to work well.

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 gnu.xml.util.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:


chainTo

public void chainTo(org.xml.sax.helpers.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:

Throws:


characters

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

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

Parameters:


comment

public void comment(char ch[][] , int start, int length)

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

Parameters:


elementDecl

public void elementDecl(java.lang.String name, java.lang.String model)

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

Parameters:


endCDATA

public void endCDATA()

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


endDTD

public void endDTD()

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


endDocument

public void endDocument()

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


endElement

public void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)

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

Parameters:


endEntity

public void endEntity(java.lang.String name)

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

Parameters:


endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)

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

Parameters:


externalEntityDecl

public void externalEntityDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

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

Parameters:


getContentHandler

public final ContentHandler getContentHandler()

Returns the content handler being used.


getDTDHandler

public final DTDHandler getDTDHandler()

Returns the dtd handler being used.


getDocumentLocator

public Locator getDocumentLocator()

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


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.


getProperty

public final Object getProperty(java.lang.String id)

Retrieves a property of unknown intent (usually a handler)

Parameters:


ignorableWhitespace

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

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

Parameters:


internalEntityDecl

public void internalEntityDecl(java.lang.String name, java.lang.String value)

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

Parameters:


notationDecl

public void notationDecl(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

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

Parameters:


processingInstruction

public void processingInstruction(java.lang.String target, java.lang.String data)

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

Parameters:


setContentHandler

public final void setContentHandler(org.xml.sax.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.

Parameters:


setDTDHandler

public final void setDTDHandler(org.xml.sax.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.

Parameters:


setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

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

Parameters:


setErrorHandler

public final void setErrorHandler(org.xml.sax.ErrorHandler handler)

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

Parameters:


setProperty

public final 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. This overrides the previous handler settting, which was probably pointed to the next consumer by the base class constructor.

Parameters:


skippedEntity

public void skippedEntity(java.lang.String name)

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

Parameters:


startCDATA

public void startCDATA()

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


startDTD

public void startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId)

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

Parameters:


startDocument

public void startDocument()

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


startElement

public void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)

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

Parameters:


startEntity

public void startEntity(java.lang.String name)

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

Parameters:


startPrefixMapping

public void startPrefixMapping(java.lang.String prefix, java.lang.String uri)

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

Parameters:


unparsedEntityDecl

public 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

Parameters: