com.deltaxml.pipe

Class AncestorXMLFilter

java.lang.Object

org.xml.sax.helpers.XMLFilterImpl

com.deltaxml.pipe.XMLFilterImpl2

com.deltaxml.pipe.AncestorXMLFilter

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.ext.DeclHandler, org.xml.sax.ext.LexicalHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

Direct Known Subclasses:

PCDataConcatenatingInfilter, WordBufferingFilter

public class AncestorXMLFilter
extends XMLFilterImpl2

Stores a stack of the elements that are ancestor to the current context in the SAXStream.

Example

With the following XML:

 <root>
   <a/>
   <b>
     <c/>
   </b>
 </root>
 

When the startElement SAXEvent has been called for the element <c/>, the ancestor stack will look like:

• c
• b
• root

This allows your code (which extends AncestorXMLFilter) to query the stack to find out if there are ancestors which meet given criteria (for example am I a descendant of <b/>).

This saves you from having to store lots of status information in your filter (e.g. booleans like inA or inB).

Use

To make use of this filter, extend it (rather than extending XMLFilterImpl). Elements are added to the stack in the AncestorXMLFilter.startElement(String, String, String, Attributes) methods and removed from the stack in the AncestorXMLFilter.endElement(String, String, String) methods.

If you need to push/pop an element before you make your super.startElement call, for example if you're buffering, then you can use AncestorXMLFilter.pushAncestorStack(String, String, String, Attributes) and AncestorXMLFilter.popAncestorStack(String, String, String) to control the stack. These should be used in conjunction with AncestorXMLFilter.outputStartElement(String, String, String, Attributes) and AncestorXMLFilter.outputEndElement(String, String, String) which are the same as startElement and endElement, but don't push/pop the stack.

Constructor Summary

Constructors

Constructor and Description
AncestorXMLFilter() Constructs a new AncestorXMLFilter.

Method Summary

Modifier and Type	Method and Description
void	endDocument() Overrides the default endDocument method.
void	endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) Overrides the default endElement method.
java.lang.String	getClosestAttributeValueFromAncestor(java.lang.String elementURI, java.lang.String elementLocalName, java.lang.String attrURI, java.lang.String attrLocalName, int ancestorLimit) Returns the value of the given attribute on the ancestor of the given type that is nearest the top of the ancestor stack which has a value for the given attribute.
java.lang.String	getClosestAttributeValueFromAnyAncestor(java.lang.String attrURI, java.lang.String attrLocalName, int ancestorLimit) Returns the value of the given attribute on the ancestor nearest the top of the ancestor stack which has a value for the given attribute.
java.lang.String	getGrandParentLocalName() Returns the localName of the grand parent element.
java.lang.String	getParentLocalName() Returns the localName of the parent element.
java.lang.String	getParentQName() Returns the qName of the parent element.
java.lang.Object	getProperty(java.lang.String name) Reports a current property setting.
boolean	hasAncestor(java.lang.String uri, java.lang.String localName) Looks for matching ancestors along the entire depth of the ancestor stack.
boolean	hasAncestor(java.lang.String uri, java.lang.String localName, int ancestorLimit) Looks for ancestors.
boolean	hasAncestorWithAttr(java.lang.String elementURI, java.lang.String elementLocalName, java.lang.String attrURI, java.lang.String attrLocalName, int ancestorLimit) Returns whether there is an ancestor with the given attribute.
boolean	hasAncestorWithAttrValue(java.lang.String elementURI, java.lang.String elementLocalName, java.lang.String attrURI, java.lang.String attrLocalName, java.lang.String attrValue, boolean ignoreCase, int ancestorLimit) Returns whether there is an ancestor of the given element type that has an attribute that matches the supplied value.
boolean	hasAncestorWithAttrValues(java.lang.String elementURI, java.lang.String elementLocalName, java.lang.String attrURI, java.lang.String attrLocalName, java.lang.String[] allowedValues, boolean ignoreCase, int ancestorLimit) Returns whether there is an ancestor of the given element type that has an attribute that matches the supplied values.
void	outputCharacters(char[] ch, int start, int length) Identical to the characters method.
void	outputEndElement(java.lang.String uri, java.lang.String localName, java.lang.String qName) Similar to endElement.
void	outputStartElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) Similar to startElement.
void	popAncestorStack(java.lang.String uri, java.lang.String localName, java.lang.String qName) Checks that the top element of the stack is the same as the supplied element, if it is then pops the top of the stack.
void	pushAncestorStack(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) Pushes the supplied element onto the ancestor stack.
void	setProperty(java.lang.String name, java.lang.Object value) Specifies a property used to configure the filter.
int	stackDepth() Returns the current depth of the ancestor stack.
void	startDocument() Overrides the default startDocument method.
void	startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts) Overrides the default startElement method.

Methods inherited from class com.deltaxml.pipe.XMLFilterImpl2

attributeDecl, comment, elementDecl, endCDATA, endDTD, endEntity, externalEntityDecl, internalEntityDecl, parse, parse, startCDATA, startDTD, startEntity

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

characters, endPrefixMapping, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, skippedEntity, startPrefixMapping, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

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

Constructor Detail

AncestorXMLFilter

public AncestorXMLFilter()

Constructs a new AncestorXMLFilter.

Method Detail

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)
                 throws org.xml.sax.SAXNotRecognizedException,
                        org.xml.sax.SAXNotSupportedException

Specifies a property used to configure the filter. In addition to the property values typically supported by the standard (supertype) XMLFilterImpl this class also supports the following properties:

• http://xml.org/sax/properties/lexical-handler
• http://xml.org/sax/properties/declaration-handler

Specified by:

setProperty in interface org.xml.sax.XMLReader

Overrides:

setProperty in class XMLFilterImpl2

Parameters:

name - the name of the property to be assigned

value - the new value of the property

Throws:

org.xml.sax.SAXNotRecognizedException - if the feature name is not recognized

org.xml.sax.SAXNotSupportedException - if it is not possible to configure the feature with the specified value

See Also:

XMLFilterImpl.setProperty(String, Object), XMLReader.setProperty(String, Object), SAX Property documentation

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws org.xml.sax.SAXNotRecognizedException,
                                    org.xml.sax.SAXNotSupportedException

Reports a current property setting. Properties are used to configure the filter behaviour. In addition to the property values typically supported by the standard (supertype) XMLFilterImpl this class also supports the following properties:

• http://xml.org/sax/properties/lexical-handler
• http://xml.org/sax/properties/declaration-handler

Specified by:

getProperty in interface org.xml.sax.XMLReader

Overrides:

getProperty in class XMLFilterImpl2

Parameters:

name - the name of the property to be reported

Returns:

an Object representing the value of the requested property

Throws:

org.xml.sax.SAXNotRecognizedException - if the property name is not recognized

org.xml.sax.SAXNotSupportedException - if it is not possible to determine the property's value

See Also:

XMLFilterImpl.getProperty(String), XMLReader.getProperty(String), SAX Property documentation

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 the default startElement method. It calls AncestorXMLFilter.pushAncestorStack(String, String, String, Attributes), which pushes the supplied element onto the ancestor stack.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

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

Parameters:

uri - the element's namespace URI

localName - the element's localname

qName - the element's qualified name

atts - the element's attributes

Throws:

org.xml.sax.SAXException - the superclass may throw an exception during processing.

See Also:

XMLFilterImpl.startElement(String, String, String, Attributes), XMLFilterImpl.startElement(String, String, String, Attributes)

endElement

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

Overrides the default endElement method. It calls AncestorXMLFilter.popAncestorStack(String, String, String), which pops the supplied element off the ancestor stack.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

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

Parameters:

uri - the element's namespace URI

localName - the element's localname

qName - the element's qualified name

Throws:

org.xml.sax.SAXException - the superclass may throw an exception during processing.

See Also:

XMLFilterImpl.endElement(String, String, String), XMLFilterImpl.endElement(String, String, String)

pushAncestorStack

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

Pushes the supplied element onto the ancestor stack.

Parameters:

uri - The element's NS uri.

localName - The element's localName

qName - The element's qName

atts - The element's attributes

See Also:

Stack.push(Object)

popAncestorStack

public void popAncestorStack(java.lang.String uri,
                             java.lang.String localName,
                             java.lang.String qName)
                      throws java.lang.IllegalStateException

Checks that the top element of the stack is the same as the supplied element, if it is then pops the top of the stack.

Parameters:

uri - The element's NS uri.

localName - The element's localName

qName - The element's qName

Throws:

java.lang.IllegalStateException - is thrown when the element at the top of the stack is not the same as the supplied element's details.

See Also:

Stack.pop()

startDocument

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

Overrides the default startDocument method. Clears the ancestor stack.

Specified by:

startDocument in interface org.xml.sax.ContentHandler

Overrides:

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

Throws:

org.xml.sax.SAXException - the superclass may throw an exception during processing.

See Also:

XMLFilterImpl.startDocument(), XMLFilterImpl.startDocument(), Vector.clear()

endDocument

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

Overrides the default endDocument method. Clears the ancestor stack.

Specified by:

endDocument in interface org.xml.sax.ContentHandler

Overrides:

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

Throws:

org.xml.sax.SAXException - the superclass may throw an exception during processing. Also thrown if the stack is not empty.

See Also:

XMLFilterImpl.endDocument(), XMLFilterImpl.endDocument(), Vector.clear()

getParentLocalName

public java.lang.String getParentLocalName()
                                    throws java.lang.IllegalStateException

Returns the localName of the parent element.

Returns:

the localname of the parent element on the ancestor stack

Throws:

java.lang.IllegalStateException - when called before the first startElement

getParentQName

public java.lang.String getParentQName()
                                throws java.lang.IllegalStateException

Returns the qName of the parent element.

Returns:

the qualified name of the parent element on the ancestor stack

Throws:

java.lang.IllegalStateException - when called before the first startElement

getGrandParentLocalName

public java.lang.String getGrandParentLocalName()
                                         throws java.lang.IllegalStateException,
                                                java.lang.UnsupportedOperationException

Returns the localName of the grand parent element.

Returns:

the local name of the grandparent element on the ancestor stack

Throws:

java.lang.IllegalStateException - when called before the first startElement

java.lang.UnsupportedOperationException - when there is not enough depth in the ancestor stack

hasAncestor

public boolean hasAncestor(java.lang.String uri,
                           java.lang.String localName,
                           int ancestorLimit)
                    throws java.lang.IllegalArgumentException

Looks for ancestors.

Parameters:

uri - the namespace uri of the ancestor element to look for

localName - the localname of the ancestor element to look for

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

a boolean stating whether or not the ancestor stack contains the element specified within the given distance

Throws:

java.lang.IllegalArgumentException - when the ancestorLimit parameter is zero

hasAncestor

public boolean hasAncestor(java.lang.String uri,
                           java.lang.String localName)

Looks for matching ancestors along the entire depth of the ancestor stack. Same as calling hasAncestor(uri, localName, -1).

Parameters:

uri - the namespace URI of the ancestor element to test for

localName - the localname of the ancestor to test for

Returns:

a boolean stating whether or not the ancestor stack contains the element specified

See Also:

AncestorXMLFilter.hasAncestor(String, String, int)

hasAncestorWithAttr

public boolean hasAncestorWithAttr(java.lang.String elementURI,
                                   java.lang.String elementLocalName,
                                   java.lang.String attrURI,
                                   java.lang.String attrLocalName,
                                   int ancestorLimit)

Returns whether there is an ancestor with the given attribute.

Parameters:

elementURI - The namespace URI of the element to match

elementLocalName - The local name of the element to match

attrURI - The namespace URI of the attribute to match

attrLocalName - The local name of the attribute to match

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

whether there is an ancestor with the given attribute.

hasAncestorWithAttrValue

public boolean hasAncestorWithAttrValue(java.lang.String elementURI,
                                        java.lang.String elementLocalName,
                                        java.lang.String attrURI,
                                        java.lang.String attrLocalName,
                                        java.lang.String attrValue,
                                        boolean ignoreCase,
                                        int ancestorLimit)

Returns whether there is an ancestor of the given element type that has an attribute that matches the supplied value.

Parameters:

elementURI - The namespace URI of the element to match

elementLocalName - The local name of the element to match

attrURI - The namespace URI of the attribute to match

attrLocalName - The local name of the attribute to match

attrValue - The value allowed for the attribute's value

ignoreCase - Whether to ignore the case of the attribute's value

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

whether there is an ancestor of the given element type that has an attribute that matches the supplied value

hasAncestorWithAttrValues

public boolean hasAncestorWithAttrValues(java.lang.String elementURI,
                                         java.lang.String elementLocalName,
                                         java.lang.String attrURI,
                                         java.lang.String attrLocalName,
                                         java.lang.String[] allowedValues,
                                         boolean ignoreCase,
                                         int ancestorLimit)

Returns whether there is an ancestor of the given element type that has an attribute that matches the supplied values.

Parameters:

elementURI - The namespace URI of the element to match

elementLocalName - The local name of the element to match

attrURI - The namespace URI of the attribute to match

attrLocalName - The local name of the attribute to match

allowedValues - The values allowed for the attribute's value

ignoreCase - Whether to ignore the case of the attribute's value

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

whether there is an ancestor of the given element type that has an attribute that matches the supplied values

getClosestAttributeValueFromAncestor

public java.lang.String getClosestAttributeValueFromAncestor(java.lang.String elementURI,
                                                             java.lang.String elementLocalName,
                                                             java.lang.String attrURI,
                                                             java.lang.String attrLocalName,
                                                             int ancestorLimit)

Returns the value of the given attribute on the ancestor of the given type that is nearest the top of the ancestor stack which has a value for the given attribute.

Parameters:

elementURI - The namespace URI of the element to match

elementLocalName - The local name of the element to match

attrURI - The namespace URI of the attribute to match

attrLocalName - The local name of the attribute to match

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

the value of the given attribute on a given ancestor, returns null if no ancestor has the attribute.

getClosestAttributeValueFromAnyAncestor

public java.lang.String getClosestAttributeValueFromAnyAncestor(java.lang.String attrURI,
                                                                java.lang.String attrLocalName,
                                                                int ancestorLimit)

Returns the value of the given attribute on the ancestor nearest the top of the ancestor stack which has a value for the given attribute.

Parameters:

attrURI - the namespace URI of the requested attribute

attrLocalName - the localname of the requested attribute

ancestorLimit - The number of ancestors to consider. If negative unlimited ancestors are considered, otherwise a number representing the number to consider; to only consider parents should be 1, grandparents 2 etc. If zero then will not consider anything and will throw an IllegalArgumentException.

Returns:

the value of the given attribute on a ancestor, returns null if no ancestor has the attribute.

outputStartElement

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

Similar to startElement. However, unlike startElement, the element is not pushed onto the ancestor stack.

Parameters:

uri - the element's namespace URI

localName - the element's localname

qName - the element's qualified name

atts - the element's attributes

Throws:

org.xml.sax.SAXException - the supertype may throw a SAXException during processing

See Also:

XMLFilterImpl.startElement(String, String, String, Attributes), XMLFilterImpl.startElement(String, String, String, Attributes)

outputCharacters

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

Identical to the characters method.

Parameters:

ch - an array of characters

start - the starting position in the array

length - the nu,ber of characters to use from the array

Throws:

org.xml.sax.SAXException - the supertype may throw a SAXException during processing

See Also:

XMLFilterImpl.characters(char[], int, int), XMLFilterImpl.characters(char[], int, int)

outputEndElement

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

Similar to endElement. However, unlike endElement, the element is not popped from the ancestor stack.

Parameters:

uri - the element's namespace URI

localName - the element's localname

qName - the element's qualified name

Throws:

org.xml.sax.SAXException - the supertype may throw a SAXException during processing

See Also:

XMLFilterImpl.endElement(String, String, String), XMLFilterImpl.endElement(String, String, String)

stackDepth

public int stackDepth()

Returns the current depth of the ancestor stack. A value of 0 is returned when the stack is currently empty and that you're processing the root node.

Returns:

the current depth of the ancestor stack.