org.jdom.contrib.input.scanner
Class XPathMatcher

java.lang.Object
  extended by org.jdom.contrib.input.scanner.XPathMatcher

public abstract class XPathMatcher
extends java.lang.Object

The base class for all XPath matchers used by ElementScanner.

This class also plays the role of factory for concrete implementations: The system property "org.jdom.XPathMatcher.class" shall contain the fully-qualified name of a concrete subclass of XPatchMatcher with a public two argument constructor. If this property is not defined, the default concrete implementation (supporting only node matching patterns) will be used.

As the default implementation relies on Perl5-like regular expression to match nodes, any regular expression can be used as "XPath expression" with the restriction that any '*' character be escaped (i.e. preceded with a '\' character).

Author:
Laurent Bihanic

Constructor Summary
protected XPathMatcher(java.lang.String expression, ElementListener listener)
          Default constructor, protected on purpose.
 
Method Summary
 java.lang.String getExpression()
          Returns the XPath expression this matcher matches.
 ElementListener getListener()
          Returns the element listener associated to this matcher object.
protected static java.lang.String getPathPatternAsRE(java.lang.String expr)
          Extracts the node matching pattern part from an XPath expression and converts it into a Perl5-like regular expression.
protected static java.lang.String getTestPattern(java.lang.String expr)
          Extracts the test part from an XPath expression.
static boolean isDebug()
          Returns whether debug traces are active.
abstract  boolean match(java.lang.String path, org.xml.sax.Attributes attrs)
          Tries to match an element path and attributes with the XPath expression this matcher matches.
abstract  boolean match(java.lang.String path, org.jdom.Element elt)
          Tries to match an element with the XPath expression this matcher matches.
static XPathMatcher newXPathMatcher(java.lang.String expression, ElementListener listener)
          Creates a new XPath matcher matching the specified XPath expression.
static void setDebug(boolean value)
          Activates or deactivates debug traces on the process standard output.
static void setXPathMatcherClass(java.lang.Class aClass)
          Sets the concrete XPathMatcher subclass to be used when allocating XPathMatcher instances.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XPathMatcher

protected XPathMatcher(java.lang.String expression,
                       ElementListener listener)
                throws org.jdom.JDOMException
Default constructor, protected on purpose.

Parameters:
expression - the XPath-like expression to match.
listener - the element listener to notify when an element matches the expression.
Throws:
org.jdom.JDOMException - if one of the arguments is invalid.
Method Detail

getExpression

public java.lang.String getExpression()
Returns the XPath expression this matcher matches.

Returns:
the XPath expression this matcher matches.

getListener

public ElementListener getListener()
Returns the element listener associated to this matcher object.

Returns:
the element listener.

match

public abstract boolean match(java.lang.String path,
                              org.xml.sax.Attributes attrs)
Tries to match an element path and attributes with the XPath expression this matcher matches.

This method is invoked when processing the startElement SAX event.

Note: The default implementation ignores the attributes.

Parameters:
path - the path to the element.
attrs - the SAX attributes of the element.
Returns:
true is the element matches the XPath expression, false otherwise.

match

public abstract boolean match(java.lang.String path,
                              org.jdom.Element elt)
Tries to match an element with the XPath expression this matcher matches.

This method is invoked when processing the endElement SAX event. It allows matching on data not part of the startElement event such as the presence of child elements.

Note: The default implementation always returns true as it only supports filtering on the node path.

Parameters:
path - the path to the element.
elt - the JDOM element.
Returns:
true is the element matches the XPath expression, false otherwise.

getPathPatternAsRE

protected static java.lang.String getPathPatternAsRE(java.lang.String expr)
                                              throws org.jdom.JDOMException
Extracts the node matching pattern part from an XPath expression and converts it into a Perl5-like regular expression.

Parameters:
expr - an XPath expression.
Returns:
the RE to match the element path.
Throws:
org.jdom.JDOMException - if expression is invalid.

getTestPattern

protected static java.lang.String getTestPattern(java.lang.String expr)
                                          throws org.jdom.JDOMException
Extracts the test part from an XPath expression. The test part if the part of the XPath expression between square backets.

Parameters:
expr - an XPath expression.
Returns:
the test part of the expression of null if no test was specified.
Throws:
org.jdom.JDOMException - if expression is invalid.

setDebug

public static void setDebug(boolean value)
Activates or deactivates debug traces on the process standard output. Debug traces allow to trace the mapping between the XPath-like expressions provided when registering a listener and the regular expressions and/or XPath expressions actually used to filter elements.

Parameters:
value - whether to activate debug traces.

isDebug

public static boolean isDebug()
Returns whether debug traces are active.

Returns:
true if debug traces are active; false otherwise.

setXPathMatcherClass

public static void setXPathMatcherClass(java.lang.Class aClass)
                                 throws java.lang.IllegalArgumentException,
                                        org.jdom.JDOMException
Sets the concrete XPathMatcher subclass to be used when allocating XPathMatcher instances.

Parameters:
aClass - the concrete subclass of XPathMatcher.
Throws:
java.lang.IllegalArgumentException - if aClass is null.
org.jdom.JDOMException - if aClass is not a concrete subclass of XPathMatcher.

newXPathMatcher

public static final XPathMatcher newXPathMatcher(java.lang.String expression,
                                                 ElementListener listener)
                                          throws org.jdom.JDOMException
Creates a new XPath matcher matching the specified XPath expression.

Parameters:
expression - the XPath-like expression to match.
listener - the element listener to notify when an element matches the expression.
Throws:
org.jdom.JDOMException - if expression is invalid.


Copyright © 2011 Jason Hunter, Brett McLaughlin. All Rights Reserved.