gnu.xml.pipeline
public class EventFilter extends Object implements EventConsumer, ContentHandler, DTDHandler, LexicalHandler, DeclHandler
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 EventFilter.
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 EventFilter 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 $
Field Summary | |
---|---|
static String | DECL_HANDLER SAX2 property identifier for DeclHandler events |
static String | FEATURE_URI SAX2 URI prefix for standard feature flags. |
static String | LEXICAL_HANDLER SAX2 property identifier for LexicalHandler events |
static 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(String eName, String aName, String type, String mode, 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(String name, 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(String uri, String localName, String qName) SAX2: passes this callback to the next consumer, if any |
void | endEntity(String name)
SAX2: passes this callback to the next consumer, if any. |
void | endPrefixMapping(String prefix) SAX2: passes this callback to the next consumer, if any |
void | externalEntityDecl(String name, String publicId, String systemId) SAX2: passes this callback to the next consumer, if any |
ContentHandler | getContentHandler() Returns the content handler being used. |
Locator | getDocumentLocator() |
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. |
Object | getProperty(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(String name, String value) SAX2: passes this callback to the next consumer, if any |
void | notationDecl(String name, String publicId, String systemId) SAX1: passes this callback to the next consumer, if any |
void | processingInstruction(String target, 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(String id, Object o)
Stores the property, normally a handler; a null handler indicates
that these events will not be forwarded.
|
void | skippedEntity(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(String name, String publicId, String systemId) SAX2: passes this callback to the next consumer, if any |
void | startElement(String uri, String localName, String qName, Attributes atts) SAX2: passes this callback to the next consumer, if any |
void | startEntity(String name)
SAX2: passes this callback to the next consumer, if any. |
void | startPrefixMapping(String prefix, String uri) SAX2: passes this callback to the next consumer, if any |
void | unparsedEntityDecl(String name, String publicId, String systemId, String notationName) SAX1: passes this callback to the next consumer, if any |
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
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: IllegalStateException if the "next" consumer has already been set through the constructor.
events.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 2011-08-26.