org.brownell.xml.pipeline
Class EventFilter

java.lang.Object
  |
  +--org.brownell.xml.pipeline.EventFilter
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 initialized in two ways:

SAX handlers given to these objects will often consume events completely, or chain them to the second consumer after filtering. That second consumer may be acquired through getNext().

The simplest way to build such handlers is to create a subclass which overrides one or more handler methods, and register an instance of that subclass to serve as one or more of the SAX handlers. Methods which aren't overridden will automatically chain to the appropriate method in the next event consumer. Subclass methods may invoke superclass methods to do similar chaining, perhaps after modifying parameters. Event filter subclasses should use the ErrorHandler to report most errors. Record and use the locator, for more useful diagnostics.

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, such as an instance of the DefaultHandler class.

This may be viewed as the consumer side analogue of the XMLFilterImpl class, introduced in SAX2. Events are pushed through an EventFilter (like normal method calls), not pulled through like data through a parser. Also, there is no policy that the producer must look like a SAX parser; application modules can send events directly. Implementations of that "XMLFilter" interface may be used with an EventProducer on the event production part of a pipeline.

Version:
$Date: 2000/05/29 12:09:40 $
Author:
David Brownell

Field Summary
static java.lang.String HANDLER_URI
          SAX2 URI prefix for standard 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
 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.
 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)
          SAX2: 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.
 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 a property of unknown intent (usually a handler)
 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)
          SAX2: 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

HANDLER_URI

public static final java.lang.String HANDLER_URI
SAX2 URI prefix for standard handlers
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

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
Tags copied from 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; if that handler needs to be called, it must be separately saved.

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. This overrides the previous settting for this handler; if that handler needs to be called, it must be separately saved.

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 a property of unknown intent (usually a handler)

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
Tags copied from 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.

setDocumentLocator

public void setDocumentLocator(Locator l)
SAX2: passes this callback to the next consumer, if any
Specified by:
setDocumentLocator in interface ContentHandler
Tags copied from 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
Tags copied from interface: 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
Tags copied from 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
Tags copied from 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[] buf,
                       int off,
                       int len)
                throws SAXException
SAX2: passes this callback to the next consumer, if any
Specified by:
characters in interface ContentHandler
Tags copied from 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[] buf,
                                int off,
                                int len)
                         throws SAXException
SAX2: passes this callback to the next consumer, if any
Specified by:
ignorableWhitespace in interface ContentHandler
Tags copied from 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 p,
                               java.lang.String u)
                        throws SAXException
SAX2: passes this callback to the next consumer, if any
Specified by:
startPrefixMapping in interface ContentHandler
Tags copied from 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 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
Tags copied from interface: 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
Tags copied from interface: 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
Tags copied from 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
Tags copied from interface: 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
SAX2: passes this callback to the next consumer, if any
Specified by:
unparsedEntityDecl in interface DTDHandler
Tags copied from 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.
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
SAX2: passes this callback to the next consumer, if any
Specified by:
notationDecl in interface DTDHandler
Tags copied from 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), 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
Tags copied from 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.
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
Tags copied from 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[] buf,
                    int off,
                    int len)
             throws SAXException
SAX2: passes this callback to the next consumer, if any
Specified by:
comment in interface LexicalHandler
Tags copied from 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
Tags copied from 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
Tags copied from 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
Tags copied from 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
Tags copied from 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
Tags copied from 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 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
Tags copied from interface: 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
Tags copied from 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
Tags copied from 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)