com.elharo.xml.xinclude
Class XIncludeFilter

java.lang.Object
  |
  +--org.xml.sax.helpers.XMLFilterImpl
        |
        +--com.elharo.xml.xinclude.XIncludeFilter

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

public final class XIncludeFilter

extends org.xml.sax.helpers.XMLFilterImpl

This is a SAX filter which resolves all XInclude include elements before passing them on to the client application. Currently this class has the following known deviation from the XInclude specification:

1. XPointer is not supported.

Furthermore, I would definitely use a new instance of this class for each document you want to process. I doubt it can be used successfully on multiple documents. Furthermore, I can virtually guarantee that this class is not thread safe. You have been warned.

Since this class is not designed to be subclassed, and since I have not yet considered how that might affect the methods herein or what other protected methods might be needed to support subclasses, I have declared this class final. I may remove this restriction later, though the use-case for subclassing is weak. This class is designed to have its functionality extended via a a horizontal chain of filters, not a vertical hierarchy of sub and superclasses.

To use this class:

1. Construct an XIncludeFilter object with a known base URL
2. Pass the XMLReader object from which the raw document will be read to the setParent() method of this object.
3. Pass your own ContentHandler object to the setContentHandler() method of this object. This is the object which will receive events from the parsed and included document.
4. Optional: if you wish to receive comments, set your own LexicalHandler object as the value of this object's http://xml.org/sax/properties/lexical-handler property. Also make sure your LexicalHandler asks this object for the status of each comment using insideIncludeElement before doing anything with the comment.
5. Pass the URL of the document to read to this object's parse() method

e.g.

XIncludeFilter includer = new XIncludeFilter(base); 
  includer.setParent(parser);
  includer.setContentHandler(new SAXXIncluder(System.out));
  includer.parse(args[i]);
  

Version:

1.0d9, July 4, 2002

Author:

Elliotte Rusty Harold

Field Summary

static java.lang.String

XINCLUDE_NAMESPACE

Constructor Summary

XIncludeFilter()

Method Summary

void	characters(char[] ch, int start, int length)
void	endDocument()
void	endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)
void	endPrefixMapping(java.lang.String prefix)
void	ignorableWhitespace(char[] ch, int start, int length)
boolean	insideIncludeElement() This utility method returns true if and only if this reader is currently inside a non-empty include element.
void	processingInstruction(java.lang.String target, java.lang.String data)
void	setDocumentLocator(org.xml.sax.Locator locator)
void	skippedEntity(java.lang.String name)
void	startDocument()
void	startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)
void	startPrefixMapping(java.lang.String prefix, java.lang.String uri)

Methods inherited from class org.xml.sax.helpers.XMLFilterImpl

error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, notationDecl, parse, parse, resolveEntity, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XINCLUDE_NAMESPACE

public static final java.lang.String XINCLUDE_NAMESPACE

Constructor Detail

XIncludeFilter

public XIncludeFilter()

Method Detail

setDocumentLocator

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

Overrides:

setDocumentLocator in class org.xml.sax.helpers.XMLFilterImpl

insideIncludeElement

public boolean insideIncludeElement()

This utility method returns true if and only if this reader is currently inside a non-empty include element. (This is not the same as being inside the node set whihc replaces the include element.) This is primarily needed for comments inside include elements. It must be checked by the actual LexicalHandler to see whether a comment is passed or not.

Returns:

boolean

startElement

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

Overrides:

startElement in class org.xml.sax.helpers.XMLFilterImpl

endElement

public void endElement(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException

Overrides:

endElement in class org.xml.sax.helpers.XMLFilterImpl

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

Overrides:

startDocument in class org.xml.sax.helpers.XMLFilterImpl

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

Overrides:

endDocument in class org.xml.sax.helpers.XMLFilterImpl

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws org.xml.sax.SAXException

Overrides:

startPrefixMapping in class org.xml.sax.helpers.XMLFilterImpl

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws org.xml.sax.SAXException

Overrides:

endPrefixMapping in class org.xml.sax.helpers.XMLFilterImpl

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

Overrides:

characters in class org.xml.sax.helpers.XMLFilterImpl

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException

Overrides:

ignorableWhitespace in class org.xml.sax.helpers.XMLFilterImpl

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

Overrides:

processingInstruction in class org.xml.sax.helpers.XMLFilterImpl

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

Overrides:

skippedEntity in class org.xml.sax.helpers.XMLFilterImpl