class XIncludeFilter extends 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 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


XIncludeFilter includer = new XIncludeFilter(base);
 includer.setContentHandler(new SAXXIncluder(System.out));

translated from Elliotte Rusty Harold's Java source


  1. XMLFilterImpl
  2. ErrorHandler
  3. ContentHandler
  4. DTDHandler
  5. EntityResolver
  6. XMLFilter
  7. XMLReader
  8. AnyRef
  9. Any

Value Members


  2. def characters(ch: Array[Char], start: Int, length: Int): Unit

  3. def endDocument(): Unit

  4. def endElement(uri: String, localName: String, qName: String): Unit

  5. def endPrefixMapping(prefix: String): Unit

  6. def equals(arg0: Any): Boolean

    This method is used to compare the receiver object (this) with the argument object (arg0) for equivalence

    This method is used to compare the receiver object (this) with the argument object (arg0) for equivalence.

    The default implementations of this method is an equivalence relation:

    • It is reflexive: for any instance x of type Any, x.equals(x) should return true.
    • It is symmetric: for any instances x and y of type Any, x.equals(y) should return true if and only if y.equals(x) returns true.
    • It is transitive: for any instances x, y, and z of type AnyRef if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.

    If you override this method, you should verify that your implementation remains an equivalence relation. Additionally, when overriding this method it is often necessary to override hashCode to ensure that objects that are "equal" (o1.equals(o2) returns true) hash to the same Int (o1.hashCode.equals(o2.hashCode)).


    the object to compare against this object for equality.


    true if the receiver object is equivalent to the argument; false otherwise.

    definition classes: AnyRef ⇐ Any
  7. def error(arg0: SAXParseException): Unit

  8. def fatalError(arg0: SAXParseException): Unit

  9. def getContentHandler(): ContentHandler

  10. def getDTDHandler(): DTDHandler

  11. def getEntityResolver(): EntityResolver

  12. def getErrorHandler(): ErrorHandler

  13. def getFeature(arg0: String): Boolean

  14. def getParent(): XMLReader

  15. def getProperty(arg0: String): AnyRef

  16. def hashCode(): Int

    Returns a hash code value for the object

    Returns a hash code value for the object.

    The default hashing algorithm is platform dependent.

    Note that it is allowed for two objects to have identical hash codes (o1.hashCode.equals(o2.hashCode)) yet not be equal (o1.equals(o2) returns false). A degenerate implementation could always return 0. However, it is required that if two objects are equal (o1.equals(o2) returns true) that they have identical hash codes (o1.hashCode.equals(o2.hashCode)). Therefore, when overriding this method, be sure to verify that the behavior is consistent with the equals method.

    definition classes: AnyRef ⇐ Any
  17. def ignorableWhitespace(ch: Array[Char], start: Int, length: Int): Unit

  18. def insideIncludeElement(): Boolean

    This utility method returns true if and only if this reader is currently inside a non-empty include element

    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 which 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.

  19. def notationDecl(arg0: String, arg1: String, arg2: String): Unit

  20. def parse(arg0: String): Unit

  21. def parse(arg0: InputSource): Unit

  22. def processingInstruction(target: String, data: String): Unit

  23. def resolveEntity(arg0: String, arg1: String): InputSource

  24. def setContentHandler(arg0: ContentHandler): Unit

  25. def setDTDHandler(arg0: DTDHandler): Unit

  26. def setDocumentLocator(locator: Locator): Unit

  27. def setEntityResolver(arg0: EntityResolver): Unit

  28. def setErrorHandler(arg0: ErrorHandler): Unit

  29. def setFeature(arg0: String, arg1: Boolean): Unit

  30. def setParent(arg0: XMLReader): Unit

  31. def setProperty(arg0: String, arg1: Any): Unit

  32. def skippedEntity(name: String): Unit

  33. def startDocument(): Unit

  34. def startElement(uri: String, localName: String, qName: String, atts1: Attributes): Unit

  35. def startPrefixMapping(prefix: String, uri: String): Unit

  36. def toString(): String

    Returns a string representation of the object

    Returns a string representation of the object.

    The default representation is platform dependent.

    definition classes: AnyRef ⇐ Any
  37. def unparsedEntityDecl(arg0: String, arg1: String, arg2: String, arg3: String): Unit

  38. def warning(arg0: SAXParseException): Unit

Instance constructors

  1. new XIncludeFilter()

  2. new XIncludeFilter(arg0: XMLReader)