xv.xml
Class PathContentHandler

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      xv.xml.PathContentHandler

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, LexicalHandler

public class PathContentHandler
extends org.xml.sax.helpers.DefaultHandler
implements LexicalHandler

This is an implementation of a SAX ContentHandler that simply generates a "path" string for each element. It can only be switched into one of two "text content" modes which simply gather up strings and then report them at the end of an element.

This class is intended to be subclassed, with custom implementations provided for startElement(String, Attributes) and endElement(String) . As an example, take the following XML document:

<root>
  <sample>
    <document/>
  </sample>
</root>

The following calls will be made:

1. startElement("/root", attributes);
2. startElement("/root/sample", attributes);
3. startElement("/root/sample/document", attributes);
4. endElement("/root/sample/document");
5. endElement("/root/sample");
6. endElement("/root");

In general, calling any of the SAX events with bad XML events will cause undefined behavior. This class is not even remotely thread-safe and can only parse one document at a time.

Author:

xv

Field Summary

protected Locator

locator The locator as set by setDocumentLocator(Locator).

Constructor Summary

PathContentHandler()

Method Summary

protected String	addLocation(String message) Appends a location string to the given message string.
void	characters(char[] ch, int start, int length) Receives character data.
protected void	clearTextContent() Removes any stored text content.
void	comment(char[] ch, int start, int length) This method checks to see if requireEmptyElement(String) has been called and throws an exception if it has.
void	endCDATA() Part of LexicalHandler.
void	endDocument()
void	endDTD() Part of LexicalHandler.
protected void	endElement(String path) Called by endElement(String, String, String) with the generated path.
void	endElement(String uri, String localName, String name) Receives notification of the end of an element.
void	endEntity(String name) Part of LexicalHandler.
protected SAXException	exception(String message) Creates a new SAXException with the given message.
protected SAXException	exception(String message, Throwable cause) Creates a new SAXException with the given message and cause exception.The current location is appended to the given string via addLocation(String).
protected SAXException	exception(Throwable cause) Creates a new SAXException with the given cause.
protected String	getNamespacePrefix(String uri) Gets the namespace prefix that should be used for the given URI.
protected String	getTextContent() Gets the current text content that has been captured.
void	ignorableWhitespace(char[] ch, int start, int length) Receives ignorable whitespace.
protected void	ignoreChildren() When called, all child element events of the current element event received will be ignored without generating any calls to startElement(String, Attributes) or endElement(String).
boolean	isCapturingIgnorableWhitespace()
void	processingInstruction(String target, String data) This method checks to see if requireEmptyElement(String) has been called and throws an exception if it has.
protected void	requireEmptyElement(String exceptionMessage) Require that the next SAX event must end the current element.
protected void	requireNoChildren(String exceptionMessage) Require that no other element be started following this event.
void	setCapturingIgnorableWhitespace(boolean capturingIgnorableWhitespace) Sets whether or not ignorable whitespace should be included when text content characters are captured.
void	setDocumentLocator(Locator locator) This sets locator to the given value.
protected void	startCapturingChars() Starts capturing characters from this point.
void	startCDATA() Part of LexicalHandler.
void	startDocument() Resets the path and capture character states.
void	startDTD(String name, String publicId, String systemId) Part of LexicalHandler.
protected void	startElement(String path, Attributes attributes) Called by startElement(String, String, String, Attributes) with the generated path.
void	startElement(String uri, String localName, String name, Attributes atts) Receives notification of the start of an element.
void	startEntity(String name) Part of LexicalHandler.
protected void	stopCapturingChars() Stops capturing characters.
protected String	takeTextContent() Gets the current text content and resets it.

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

endPrefixMapping, error, fatalError, notationDecl, resolveEntity, skippedEntity, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Field Detail

locator

protected Locator locator

The locator as set by setDocumentLocator(Locator).

Constructor Detail

PathContentHandler

public PathContentHandler()

Method Detail

startDocument

public void startDocument()
                   throws SAXException

Resets the path and capture character states. You must call super.startDocument() if you override this method.

Specified by:

startDocument in interface ContentHandler

Overrides:

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

Throws:

SAXException

endDocument

public void endDocument()
                 throws SAXException

Specified by:

endDocument in interface ContentHandler

Overrides:

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

Throws:

SAXException

startElement

protected void startElement(String path,
                            Attributes attributes)
                     throws Exception

Called by startElement(String, String, String, Attributes) with the generated path.

The path is simply a path of elements that have been seen so far. The path always starts with a '/'.

The following utilities methods should only be called from this method:

• ignoreChildren()
• requireEmptyElement(String)
• requireNoChildren(String)

The default implementation does nothing.

Parameters:

path - the path

attributes - the attributes for this element

Throws:

Exception - if an error occurs while processing this element, SAXExceptions will be rethrown directly, all other exceptions will be thrown as the cause of a SAXException.

endElement

protected void endElement(String path)
                   throws Exception

Called by endElement(String, String, String) with the generated path.

The path is simply a path of elements that have been seen so far. The path always starts with a '/'.

The default implementation does nothing.

Parameters:

path - the path

Throws:

Exception - if an error occurs while processing this element, SAXExceptions will be rethrown directly, all other exceptions will be thrown as the cause of a SAXException.

isCapturingIgnorableWhitespace

public boolean isCapturingIgnorableWhitespace()

setCapturingIgnorableWhitespace

public void setCapturingIgnorableWhitespace(boolean capturingIgnorableWhitespace)

Sets whether or not ignorable whitespace should be included when text content characters are captured. Note that this only indicates whether text sent via the ignorableWhitespace(char[], int, int) event is captured: not all XML parsers send this event.

By default ignorable whitespace is ignored.

Parameters:

capturingIgnorableWhitespace -

startCapturingChars

protected void startCapturingChars()

Starts capturing characters from this point.

This means there's no (easy) way to get the text content of both a parent element and a child element.

stopCapturingChars

protected void stopCapturingChars()

Stops capturing characters. This does not discard any current characters, just prevents additional characters from being captured.

getTextContent

protected String getTextContent()

Gets the current text content that has been captured.

Returns:

the current text content

takeTextContent

protected String takeTextContent()

Gets the current text content and resets it.

Returns:

the current text content

clearTextContent

protected void clearTextContent()

Removes any stored text content.

ignoreChildren

protected void ignoreChildren()

When called, all child element events of the current element event received will be ignored without generating any calls to startElement(String, Attributes) or endElement(String).

This method should only be called from within a call to startElement(String, Attributes), otherwise undefined behavior will result.

requireEmptyElement

protected void requireEmptyElement(String exceptionMessage)

Require that the next SAX event must end the current element.

This method only triggers an exception if the following events are triggered:

• characters(char[], int, int)
• ignorableWhitespace(char[], int, int)
• processingInstruction(String, String)
• startElement(String, String, String, Attributes)
• comment(char[], int, int) (from LexicalHandler)

Technically this should flag an exception if a comment is encountered. To do this, this class implements LexicalHandler and the comment(char[], int, int) method. However, this is useless if the instance of this class is not set as the lexical handler on the XMLReader doing the parsing.

To do this, use XMLReader's XMLReader.setProperty(String, Object) method to set the "http://xml.org/sax/properties/lexical-handler" property. Be prepared to catch an exception if you do that.

Alternatively, if you just don't care that much, you can always not bothering setting the lexical handler and just accepting that <empty><!-- comment --></empty> will be accepted as empty.

This method should only be called from within a call to startElement(String, Attributes), otherwise undefined behavior will result.

Parameters:

exceptionMessage - the exception message to use if this element isn't empty

requireNoChildren

protected void requireNoChildren(String exceptionMessage)

Require that no other element be started following this event. This throws an exception if startElement(String, String, String, Attributes) is called after this method has been called before endElement(String, String, String) is called.

Note that if this method and requireEmptyElement(String) are both called, requireEmptyElement(String) takes precedence.

This method should only be called from within a call to startElement(String, Attributes), otherwise undefined behavior will result.

Parameters:

exceptionMessage - the exception message to use if this element contains children

getNamespacePrefix

protected String getNamespacePrefix(String uri)

Gets the namespace prefix that should be used for the given URI. This is only used if namespaces are in use and is used to apply prefixes to the path based on URIs.

Use this if you intend to support namespaces. The default implementation always returns null which causes no prefix to ever be appended to path elements.

The prefix you return should not include any path characters (if it does, the resulting ambiguity is your own fault) and should not include the final ':' separator, which will be added.

As an example, assume that an implementation of this method returns "foo" for the prefix when given the URI "http://www.example.com/". A call to startDocument("http://www.example.com/", "bar", "", atts) would append the string "foo:bar" to the path.

Return "foo:" is allowed, but would append "foo::bar".

Parameters:

uri - the URI to look up a prefix for

Returns:

the namespace prefix to use for that URI or null (or the empty string) to use no prefix

startElement

public final void startElement(String uri,
                               String localName,
                               String name,
                               Attributes atts)
                        throws SAXException

Receives notification of the start of an element. This will forward (after generating the path) to startElement(String, Attributes). Do not call unless you're a SAX parser.

Specified by:

startElement in interface ContentHandler

Overrides:

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

Throws:

SAXException

endElement

public final void endElement(String uri,
                             String localName,
                             String name)
                      throws SAXException

Receives notification of the end of an element. This will forward (after generating the path) to endElement(String). Do not call unless you're a SAX parser.

Specified by:

endElement in interface ContentHandler

Overrides:

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

Throws:

SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Receives ignorable whitespace. Do not call unless you're a SAX parser.

If you override this method, you must call super.ignorableWhitespace(ch, start, length).

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

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

Throws:

SAXException

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Receives character data. Do not call unless you're a SAX parser.

If you override this method, you must call super.characters(ch, start, length).

Specified by:

characters in interface ContentHandler

Overrides:

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

Throws:

SAXException

setDocumentLocator

public void setDocumentLocator(Locator locator)

This sets locator to the given value.

Specified by:

setDocumentLocator in interface ContentHandler

Overrides:

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

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

This method checks to see if requireEmptyElement(String) has been called and throws an exception if it has. Code overriding this method should call super.processingInstruction(target, data) as the first line of the overriding method.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

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

Throws:

SAXException

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException

This method checks to see if requireEmptyElement(String) has been called and throws an exception if it has. Code overriding this method should call super.comment(ch, start, length) as the first line of the overriding method.

Specified by:

comment in interface LexicalHandler

Throws:

SAXException

startCDATA

public void startCDATA()
                throws SAXException

Part of LexicalHandler.

Specified by:

startCDATA in interface LexicalHandler

Throws:

SAXException

endCDATA

public void endCDATA()
              throws SAXException

Part of LexicalHandler.

Specified by:

endCDATA in interface LexicalHandler

Throws:

SAXException

startDTD

public void startDTD(String name,
                     String publicId,
                     String systemId)
              throws SAXException

Part of LexicalHandler.

Specified by:

startDTD in interface LexicalHandler

Throws:

SAXException

endDTD

public void endDTD()
            throws SAXException

Part of LexicalHandler.

Specified by:

endDTD in interface LexicalHandler

Throws:

SAXException

startEntity

public void startEntity(String name)
                 throws SAXException

Part of LexicalHandler.

Specified by:

startEntity in interface LexicalHandler

Throws:

SAXException

endEntity

public void endEntity(String name)
               throws SAXException

Part of LexicalHandler.

Specified by:

endEntity in interface LexicalHandler

Throws:

SAXException

addLocation

protected String addLocation(String message)

Appends a location string to the given message string. If the document locator is null this returns the given message string directly. Otherwise it appends whatever information is available in the locator.

Parameters:

message - the message string

Returns:

the message string with location information

exception

protected SAXException exception(String message)

Creates a new SAXException with the given message. The current location is appended to the given string via addLocation(String).

Parameters:

message - the error message

Returns:

a new SAXException

exception

protected SAXException exception(Throwable cause)

Creates a new SAXException with the given cause.

Parameters:

cause - the exception that caused this exception

Returns:

a new SAXException

exception

protected SAXException exception(String message,
                                 Throwable cause)

Creates a new SAXException with the given message and cause exception.The current location is appended to the given string via addLocation(String).

Parameters:

message - the error message

cause - the exception that caused the SAX exception

Returns:

a new SAXException