4.5.1. The XMLFilterImpl Class

public class ExtendedFilter extends XMLFilterImpl
    implements LexicalHandler, DeclHandler
{
    DeclHandler		declHandler;
    LexicalHandler	lexicalHandler;

    private static String	declID =
	    "http://xml.org/sax/properties/declaration-handler";
    private static String	lexicalID =
	    "http://xml.org/sax/properties/lexical-handler";

    public void setProperty (String uri, Object handler)
    throws SAXNotRecognizedException, SAXNotSupportedException
    {
	if (declID.equals (uri))
	    declHandler = (DeclHandler) handler;
	else if (lexicalID.equals (uri))
	    lexicalHandler = (LexicalHandler) handler;
	else
	    super.setProperty (uri, handler);
    }

    // support producer mode operations
    public void parse (InputSource in)
    throws SAXException, IOException
    {
	XMLReader	parent = getParent ();

	if (parent != null) {
	    parent.setProperty (declID, this);
	    parent.setProperty (lexicalID, this);
	}
	super.parse (in);
    }

    // support consumer mode operations
    public void comment (char buf [], int offset, int length)
    throws SAXException
    {
	if (lexicalHandler != null)
	    lexicalHandler.comment (buf, offset, length);
    }

    // ... likewise for other LexicalHandler and DeclHandler methods
}

When you're using such a filter just as a consumer, you'll have to register it as a handler for the event classes you're interested in, using methods like setContentHandler() as you would for any other event consumer. In such a case there's never any confusion about which XMLReader to use to parse since any filter component is only postprocessing.

When you use an XMLFilterImpl to produce events, you need to provide a parent parser, probably by using XMLFilter.setParent(). When you invoke parse(), the filter sets itself up to proxy all of the SAX core event handler methods (as shown earlier for one of the extension methods) as well as EntityResolver and ErrorHandler. You'll need to pay particular attention that you invoke the filter, instead of that "real" parser. It's easy to run into bugs that way, particularly if you're chaining multiple filters together. Although every filter stage has a parse() method, you only want to invoke it on the last postprocessing stage. It's easy to get confused about that.

4.5.2. XMLFilter Examples

import javax.xml.transform.TransformerFactory;
import javax.xml.transform.sax.*;

String			stylesheetURI = ...;
String			documentURI = ...;
ContentHandler		contentHandler = ...;
LexicalHandler		lexicalHandler = ...;
TransformerFactory	tf
SAXTransformerFactory	stf;
SAXSource		stylesheet;

tf = TransformerFactory.newInstance ();
if (!tf.getFeature (SAXTransformerFactory.FEATURE)
	|| !tf.getFeature (SAXSource.FEATURE))
    throw new Exception ("not enough API support");
stylesheet = new SAXSource (new InputSource (stylesheetURI));
stf = (SAXTransformerFactory) tf;

4.5.4. The gnu.xml.pipeline Framework

public interface EventConsumer
{
    public ContentHandler getContentHandler ();
    public DTDHandler getDTDHandler ();

    public Object getProperty (String id)
    throws SAXNotRecognizedException;

    public void setErrorHandler (ErrorHandler handler);
} 

With that interface, pipelines are normally set up beginning with the last consumer and then working toward the first consumer. There is a formal convention that states pipeline stages have a constructor that takes an EventConsumer parameter, which is used to construct pipelines from simple textual descriptions (which look like Unix-style command pipelines). That convention makes it easy to construct a pipeline by hand, as shown in the following code. Stages are strongly expected to share the same error handling; the error handler is normally established after the pipeline is set up, when a pipeline is bound to an event producer.

There is a class that corresponds to the pure consumer mode XMLFilterImpl, except that it implements all the SAX2 event consumer interfaces, not just the ones in the core API. LexicalHandler and DeclHandler are fully supported. This class also adds convenience methods such as the following:

public class EventFilter
    implements EventConsumer, ContentHandler, DTDHandler,
	    LexicalHandler, DeclHandler
{
    ... lots omitted ...

    // hook up all event consumer interfaces to the producer
    // map some known EventFilters into XMLReader feature settings
    public static void bind (XMLReader producer, EventConsumer consumer)
	{ /* code omitted */ }
    
    // wrap a "consumer mode" XMLFilterImpl
    public void chainTo (XMLFilterImpl next)
	{ /* code omitted */ }

    ... lots omitted ...
}

There are some interesting notions lurking in this example. For instance, when validation is a postprocessing stage, it can be initialized with a particular DTD and hooked up to an XMLReader that walks DOM nodes. That way, that DOM content can be incrementally validated as applications change it. Similarly, application code can produce a SAX event stream and validate content without saving it to a file. This same postprocessing approach could be taken with validators based on any of the various schema systems.