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 {@link #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 * {@link org.xml.sax.helpers.XMLFilterImpl 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 {@link EventProducer} on the * event production part of a pipeline. * * @author David Brownell * @version $Date: 2002/09/30 15:08:52 $ */ public class EventFilter implements EventConsumer, ContentHandler, DTDHandler, LexicalHandler, DeclHandler // // The is-a-handler API is only provided for // the convenience of filter implementors. // { // SAX handlers private ContentHandler docHandler, docNext; private DTDHandler dtdHandler, dtdNext; private LexicalHandler lexHandler, lexNext; private DeclHandler declHandler, declNext; // and ideally, one more for the stuff SAX2 doesn't show private Hashtable properties; private EventConsumer next; private ErrorHandler errHandler; // XXX robustly support getDocumentLocator /** SAX2 URI prefix for standard handlers */ public static final String HANDLER_URI = "http://xml.org/sax/properties/"; /** * Initializes all handlers to null. */ // constructor used by PipelineFactory public EventFilter () { } /** * 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. */ // constructor used by PipelineFactory public EventFilter (EventConsumer consumer) { if (consumer == null) return; next = consumer; docHandler = docNext = consumer.getContentHandler (); dtdHandler = dtdNext = consumer.getDTDHandler (); try { declHandler = declNext = (DeclHandler) consumer.getProperty (HANDLER_URI + "declaration-handler"); } catch (SAXException e) { /* leave value null */ } try { lexHandler = lexNext = (LexicalHandler) consumer.getProperty (HANDLER_URI + "lexical-handler"); } catch (SAXException e) { /* leave value null */ } } /** * Records the error handler that should be used by this stage, and * passes it on to any subsequent stage. */ final public void setErrorHandler (ErrorHandler handler) { errHandler = handler; if (next != null) next.setErrorHandler (handler); } /** * Returns the error handler assigned this filter stage, or null * if no such assigment has been made. */ final public ErrorHandler getErrorHandler () { return errHandler; } /** * Returns the next event consumer in sequence; or null if there * is no such handler. */ final public EventConsumer getNext () { return next; } /** * 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. */ final public void setContentHandler (ContentHandler h) { docHandler = h; } /** Returns the content handler being used. */ final public ContentHandler getContentHandler () { return docHandler; } /** * 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. */ final public void setDTDHandler (DTDHandler h) { dtdHandler = h; } /** Returns the dtd handler being used. */ final public DTDHandler getDTDHandler () { return dtdHandler; } /** Stores a property of unknown intent (usually a handler) */ final public void setProperty (String id, Object o) throws SAXNotRecognizedException, SAXNotSupportedException { try { Object value = getProperty (id); if (id == o) return; if ((HANDLER_URI + "declaration-handler").equals (id)) { declHandler = (DeclHandler) o; return; } if ((HANDLER_URI + "lexical-handler").equals (id)) { lexHandler = (LexicalHandler) o; return; } // builtin key that's not settable if (properties != null && !properties.containsKey (id)) throw new SAXNotSupportedException (id); } catch (SAXNotRecognizedException e) { if (properties == null) properties = new Hashtable (5); } properties.put (id, o); } /** Retrieves a property of unknown intent (usually a handler) */ final public Object getProperty (String id) throws SAXNotRecognizedException { if ((HANDLER_URI + "declaration-handler").equals (id)) return declHandler; if ((HANDLER_URI + "lexical-handler").equals (id)) return lexHandler; Object property = null; if (properties != null) property = properties.get (id); if (property != null) return property; throw new SAXNotRecognizedException (id); } // CONTENT HANDLER DELEGATIONS /** SAX2: passes this callback to the next consumer, if any */ public void setDocumentLocator (Locator l) { if (docNext != null) docNext.setDocumentLocator (l); } /** SAX2: passes this callback to the next consumer, if any */ public void startDocument () throws SAXException { if (docNext != null) docNext.startDocument (); } /** SAX2: passes this callback to the next consumer, if any */ public void skippedEntity (String n) throws SAXException { if (docNext != null) docNext.skippedEntity (n); } /** SAX2: passes this callback to the next consumer, if any */ public void processingInstruction (String target, String data) throws SAXException { if (docNext != null) docNext.processingInstruction (target, data); } /** SAX2: passes this callback to the next consumer, if any */ public void characters (char buf [], int off, int len) throws SAXException { if (docNext != null) docNext.characters (buf, off, len); } /** SAX2: passes this callback to the next consumer, if any */ public void ignorableWhitespace (char buf [], int off, int len) throws SAXException { if (docNext != null) docNext.ignorableWhitespace (buf, off, len); } /** SAX2: passes this callback to the next consumer, if any */ public void startPrefixMapping (String p, String u) throws SAXException { if (docNext != null) docNext.startPrefixMapping (p, u); } /** SAX2: passes this callback to the next consumer, if any */ public void startElement ( String ns, String l, String name, Attributes atts ) throws SAXException { if (docNext != null) docNext.startElement (ns, l, name, atts); } /** SAX2: passes this callback to the next consumer, if any */ public void endElement (String ns, String l, String n) throws SAXException { if (docNext != null) docNext.endElement (ns, l, n); } /** SAX2: passes this callback to the next consumer, if any */ public void endPrefixMapping (String p) throws SAXException { if (docNext != null) docNext.endPrefixMapping (p); } /** SAX2: passes this callback to the next consumer, if any */ public void endDocument () throws SAXException { if (docNext != null) docNext.endDocument (); } // DTD HANDLER DELEGATIONS /** SAX2: passes this callback to the next consumer, if any */ public void unparsedEntityDecl (String s1, String s2, String s3, String s4) throws SAXException { if (dtdNext != null) dtdNext.unparsedEntityDecl (s1, s2, s3, s4); } /** SAX2: passes this callback to the next consumer, if any */ public void notationDecl (String s1, String s2, String s3) throws SAXException { if (dtdNext != null) dtdNext.notationDecl (s1, s2, s3); } // LEXICAL HANDLER DELEGATIONS /** SAX2: passes this callback to the next consumer, if any */ public void startDTD (String root, String p, String s) throws SAXException { if (lexNext != null) lexNext.startDTD (root, p, s); } /** SAX2: passes this callback to the next consumer, if any */ public void endDTD () throws SAXException { if (lexNext != null) lexNext.endDTD (); } /** SAX2: passes this callback to the next consumer, if any */ public void comment (char buf [], int off, int len) throws SAXException { if (lexNext != null) lexNext.comment (buf, off, len); } /** SAX2: passes this callback to the next consumer, if any */ public void startCDATA () throws SAXException { if (lexNext != null) lexNext.startCDATA (); } /** SAX2: passes this callback to the next consumer, if any */ public void endCDATA () throws SAXException { if (lexNext != null) lexNext.endCDATA (); } /** * SAX2: passes this callback to the next consumer, if any. */ public void startEntity (String name) throws SAXException { if (lexNext != null) lexNext.startEntity (name); } /** * SAX2: passes this callback to the next consumer, if any. */ public void endEntity (String name) throws SAXException { if (lexNext != null) lexNext.endEntity (name); } // DECLARATION HANDLER DELEGATIONS /** SAX2: passes this callback to the next consumer, if any */ public void elementDecl (String name, String model) throws SAXException { if (declNext != null) declNext.elementDecl (name, model); } /** SAX2: passes this callback to the next consumer, if any */ public void attributeDecl (String e, String a, String b, String c, String d) throws SAXException { if (declNext != null) declNext.attributeDecl (e, a, b, c, d); } /** SAX2: passes this callback to the next consumer, if any */ public void externalEntityDecl (String name, String pub, String sys) throws SAXException { if (declNext != null) declNext.externalEntityDecl (name, pub, sys); } /** SAX2: passes this callback to the next consumer, if any */ public void internalEntityDecl (String name, String value) throws SAXException { if (declNext != null) declNext.internalEntityDecl (name, value); } }