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.

Extensions made by JP and TP:
the URL of the included TEXT document (i.e. if parse='text') can be in one of the following forms (lines are numbered starting at 1):

• textfileurl#startLineNumber will include only the line with startLineNumber
  
• textfileurl#startLineNumber$count will include count lines beginning from startLineNumber
  
• textfileurl#startLineNumber-endLineNumber will include all lines beginning from startLineNumber and ending to (including) line endLineNumber
  
• textfileurl#startLineNumber- will include all lines beginning from to the end of file
  
• textfileurl#$countOfLines or textfileurl#-countOfLines will include first countOfLines lines from the file
  

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]);
  

Field Summary

protected static java.lang.String	term1 the number of the first line to be included is specified in the URL after the term1 String
protected static java.lang.String	term2 the number of lines to be included is specified in the URL after the term2 String
protected static java.lang.String	term3 the number of the last line to be included is specified in the URL after the term3 String
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)
protected int	getLineBegin(java.lang.String url) This method reads URL and return the first line to read
protected int	getLineCount(java.lang.String url) This method reads URL and return the amount of line line to read
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

term1

protected static final java.lang.String term1

the number of the first line to be included is specified in the URL after the term1 String

See Also:

Constant Field Values

term2

protected static final java.lang.String term2

the number of lines to be included is specified in the URL after the term2 String

See Also:

Constant Field Values

term3

protected static final java.lang.String term3

the number of the last line to be included is specified in the URL after the term3 String

See Also:

Constant Field Values

XINCLUDE_NAMESPACE

public static final java.lang.String XINCLUDE_NAMESPACE

See Also:

Constant Field Values

Constructor Detail

XIncludeFilter

public XIncludeFilter()

Method Detail

setDocumentLocator

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

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

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

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

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

endElement

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

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

startDocument

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

Specified by:

startDocument in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

endDocument

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

Specified by:

endDocument in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

startPrefixMapping

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

Specified by:

startPrefixMapping in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

endPrefixMapping

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

Specified by:

endPrefixMapping in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

characters

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

Specified by:

characters in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

ignorableWhitespace

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

Specified by:

ignorableWhitespace in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

processingInstruction

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

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

skippedEntity

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

Specified by:

skippedEntity in interface org.xml.sax.ContentHandler

Overrides:

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

org.xml.sax.SAXException

getLineBegin

protected int getLineBegin(java.lang.String url)

This method reads URL and return the first line to read

Parameters:

url - URL of the document that will be read

Returns:

int

getLineCount

protected int getLineCount(java.lang.String url)

This method reads URL and return the amount of line line to read

Parameters:

url - URL of the document that will be read

Returns:

int