org.jboss.dna.graph.property
Class PathExpression

java.lang.Object
  extended by org.jboss.dna.graph.property.PathExpression
All Implemented Interfaces:
Serializable

@Immutable
public class PathExpression
extends Object
implements Serializable

An expression that defines an acceptable path using a regular-expression-like language. Path expressions can be used to represent node paths or properties.

Path expressions consist of two parts: a selection criteria (or an input path) and an output path:

 inputPath => outputPath
 

The inputPath part defines an expression for the path of a node that is to be sequenced. Input paths consist of ' /' separated segments, where each segment represents a pattern for a single node's name (including the same-name-sibling indexes) and '@' signifies a property name.

Let's first look at some simple examples:

Input Path Description
/a/b Match node "b" that is a child of the top level node "a". Neither node may have any same-name-sibilings.
/a/* Match any child node of the top level node "a".
/a/*.txt Match any child node of the top level node "a" that also has a name ending in ".txt".
/a/b@c Match the property "c" of node "/a/b".
/a/b[2] The second child named "b" below the top level node "a".
/a/b[2,3,4] The second, third or fourth child named "b" below the top level node "a".
/a/b[*] Any (and every) child named "b" below the top level node "a".
//a/b Any node named "b" that exists below a node named "a", regardless of where node "a" occurs. Again, neither node may have any same-name-sibilings.

With these simple examples, you can probably discern the most important rules. First, the '*' is a wildcard character that matches any character or sequence of characters in a node's name (or index if appearing in between square brackets), and can be used in conjunction with other characters (e.g., "*.txt").

Second, square brackets (i.e., '[' and ']') are used to match a node's same-name-sibiling index. You can put a single non-negative number or a comma-separated list of non-negative numbers. Use '0' to match a node that has no same-name-sibilings, or any positive number to match the specific same-name-sibling.

Third, combining two delimiters (e.g., "//") matches any sequence of nodes, regardless of what their names are or how many nodes. Often used with other patterns to identify nodes at any level matching other patterns. Three or more sequential slash characters are treated as two.

Many input paths can be created using just these simple rules. However, input paths can be more complicated. Here are some more examples:

Input Path Description
/a/(b|c|d) Match children of the top level node "a" that are named "a", "b" or "c ". None of the nodes may have same-name-sibling indexes.
/a/b[c/d] Match node "b" child of the top level node "a", when node "b" has a child named " c", and "c" has a child named "d". Node "b " is the selected node, while nodes "b" and "b" are used as criteria but are not selected.
/a(/(b|c|d|)/e)[f/g/@something] Match node "/a/b/e", "/a/c/e", "/a/d/e", or "/a/e " when they also have a child "f" that itself has a child "g" with property "something". None of the nodes may have same-name-sibling indexes.

These examples show a few more advanced rules. Parentheses (i.e., '(' and ')') can be used to define a set of options for names, as shown in the first and third rules. Whatever part of the selected node's path appears between the parentheses is captured for use within the output path. Thus, the first input path in the previous table would match node " /a/b", and "b" would be captured and could be used within the output path using "$1", where the number used in the output path identifies the parentheses.

Square brackets can also be used to specify criteria on a node's properties or children. Whatever appears in between the square brackets does not appear in the selected node.

See Also:
Serialized Form

Nested Class Summary
static class PathExpression.Matcher
           
 
Constructor Summary
PathExpression(String expression)
          Create the supplied expression.
 
Method Summary
static PathExpression all()
           
static PathExpression compile(String expression)
          Compile the supplied expression and return the resulting path expression instance.
 boolean equals(Object obj)
          
 String getExpression()
           
 String getSelectExpression()
           
 int hashCode()
          
 PathExpression.Matcher matcher(String absolutePath)
           
 boolean matchesAnything()
          Return whether this expression matches anything and therefore is not restrictive.
 String toString()
          
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PathExpression

public PathExpression(String expression)
               throws InvalidPathExpressionException
Create the supplied expression.

Parameters:
expression - the expression
Throws:
IllegalArgumentException - if the expression is null
InvalidPathExpressionException - if the expression is blank or is not a valid expression
Method Detail

compile

public static final PathExpression compile(String expression)
                                    throws InvalidPathExpressionException
Compile the supplied expression and return the resulting path expression instance.

Parameters:
expression - the expression
Returns:
the path expression; never null
Throws:
IllegalArgumentException - if the expression is null
InvalidPathExpressionException - if the expression is blank or is not a valid expression

getExpression

public String getExpression()
Returns:
expression

getSelectExpression

public String getSelectExpression()
Returns:
the expression

hashCode

public int hashCode()

Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:
equals in class Object

toString

public String toString()

Overrides:
toString in class Object

matcher

public PathExpression.Matcher matcher(String absolutePath)
Parameters:
absolutePath -
Returns:
the matcher

matchesAnything

public boolean matchesAnything()
Return whether this expression matches anything and therefore is not restrictive. These include expressions of any nodes (" /"), any sequence of nodes ("//"), the self reference ("."), or wildcard (" *", "*[]" or "*[*]"). Combinations of these individual expressions are also considered to match anything.

Returns:
true if the expression matches anything, or false otherwise

all

public static PathExpression all()


Copyright © 2008-2009 JBoss, a division of Red Hat. All Rights Reserved.