weblogic.xml.xpath
Class DOMXPath

java.lang.Object
  weblogic.xml.xpath.DOMXPath

public final class DOMXPath
extends Object

Evaluates an XPath against a DOM representation of an XML document.

IMPORTANT: Each of the evaluateAs...() methods can take either a DOM Document or DOM Node. You should only pass a DOM Node if you really mean to evaluate the xpath in relation to a DOM subtree. Do not use the document element (Document.getDocumentElement()) if your intention is to evaluate the xpath against the whole document - these are not the same thing.

To illustrate the difference, consider matching a simple relative location path 'foo' against a document containing a single element . This xpath is really an abbreviation for 'select all child foos of the context node'. The document element (as returned by Document.getDocumentElement()) in this case is the single ; if this is passed as the context node, the xpath is clearly not going to match anything. However, if the Root Node is passed (which DOM represents with the Document object), then the foo will be matched.

Field Summary

static int	BOOLEAN Returned by getType() to indicate that this XPath evaluates to a boolean.
static int	NAMESPACE_NODE_TYPE Type for synthesized namespace nodes.
static int	NODESET Returned by getType() to indicate that this XPath evaluates to a node-set.
static int	NUMBER Returned by getType() to indicate that this XPath evaluates to a floating point number.
static int	OTHER Returned by getType() to indicate that this XPath evaluates to an extension-defined object.
static int	STRING Returned by getType() to indicate that this XPath evaluates to a string.

Constructor Summary

DOMXPath(String xpath)
Constructs an object for evaluating the XPath expression contained in the given String.

Method Summary

boolean	evaluateAsBoolean(Document document) Evaluates this XPath in the context of the given document and returns the result as a boolean.
boolean	evaluateAsBoolean(Node contextNode) Evaluates this XPath in the context of the given Node and returns the result as a boolean.
Set	evaluateAsNodeset(Document document) Evaluates this XPath in the context of the given document and returns the result as a node-set.
Set	evaluateAsNodeset(Node contextNode) Evaluates this XPath in the context of the given Node and returns the result as a node-set.
double	evaluateAsNumber(Document document) Evaluates this XPath in the context of the given document and returns the result as a number.
double	evaluateAsNumber(Node contextNode) Evaluates this XPath in the context of the given Node and returns the result as a number.
String	evaluateAsString(Document document) Evaluates this XPath in the context of the given document and returns the result as a String.
String	evaluateAsString(Node contextNode) Evaluates this XPath in the context of the given Node and returns the result as a String.
int	getType() Returns one of the integer constants declared above to indicate what type of value this XPath returns.
static void	main(String[] args) This method allows an expression to be evaluated from the command line.
void	setVariableBindings(Map bindings) Sets the variable bindings for the evaluation process.
String	toString() Returns the string used to construct thie XPath.

Methods inherited from class java.lang.Object

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

Field Detail

NODESET

public static final int NODESET

Returned by getType() to indicate that this XPath evaluates to a node-set.

See Also:

Constant Field Values

BOOLEAN

public static final int BOOLEAN

Returned by getType() to indicate that this XPath evaluates to a boolean.

See Also:

Constant Field Values

NUMBER

public static final int NUMBER

Returned by getType() to indicate that this XPath evaluates to a floating point number.

See Also:

Constant Field Values

STRING

public static final int STRING

Returned by getType() to indicate that this XPath evaluates to a string.

See Also:

Constant Field Values

OTHER

public static final int OTHER

Returned by getType() to indicate that this XPath evaluates to an extension-defined object.

See Also:

Constant Field Values

NAMESPACE_NODE_TYPE

public static final int NAMESPACE_NODE_TYPE

Type for synthesized namespace nodes. DOM does not provide direct support for the 'namespace' node type described in the XPath data model, so the DOMXPath implementation creates special org.w3c.dom.Nodes for this purpose. Calling getType() on such nodes will return NAMESPACE_NODE_TYPE.

See Also:

Constant Field Values

Constructor Detail

DOMXPath

public DOMXPath(String xpath)
         throws XPathException

Constructs an object for evaluating the XPath expression contained in the given String.

Parameters:

xpath - The XPath to be evaluated.

Throws:

IllegalArgumentException - if xpath is null.

XPathException - if xpath is not a valid xpath or contains xpath constructs which are not supported.

Method Detail

getType

public int getType()
            throws XPathException

Returns one of the integer constants declared above to indicate what type of value this XPath returns.

Throws:

XPathException

evaluateAsNodeset

public Set evaluateAsNodeset(Document document)
                      throws XPathException

Evaluates this XPath in the context of the given document and returns the result as a node-set. The node-set is represented as a Set of org.w3c.dom.Nodes.

Some effort is made to ensure that Iterators retrived from such a Set will traverse the matched nodes in document order. This guarantee is not made for XPaths which make use of the union or composition operators.

Because the specification does not define conversions to node-set from other types, this method will return null if the XPath naturally evaluates to a type other than node-set.

Throws:

XPathException

evaluateAsString

public String evaluateAsString(Document document)
                        throws XPathException

Evaluates this XPath in the context of the given document and returns the result as a String. If this XPath naturally evaluates to a type other than String, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

evaluateAsBoolean

public boolean evaluateAsBoolean(Document document)
                          throws XPathException

Evaluates this XPath in the context of the given document and returns the result as a boolean. If this XPath naturally evaluates to a type other than boolean, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

evaluateAsNumber

public double evaluateAsNumber(Document document)
                        throws XPathException

Evaluates this XPath in the context of the given document and returns the result as a number. If this XPath naturally evaluates to a type other than number, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

evaluateAsNodeset

public Set evaluateAsNodeset(Node contextNode)
                      throws XPathException

Evaluates this XPath in the context of the given Node and returns the result as a node-set. The node-set is represented as a Set of org.w3c.dom.Nodes.

Some effort is made to ensure that Iterators retrived from such a Set will traverse the matched nodes in document order. This guarantee is not made for XPaths which make use of the union or composition operators.

Because the specification does not define conversions to node-set from other types, this method will return null if the XPath naturally evaluates to a type other than node-set.

Throws:

XPathException

evaluateAsString

public String evaluateAsString(Node contextNode)
                        throws XPathException

Evaluates this XPath in the context of the given Node and returns the result as a String. If this XPath naturally evaluates to a type other than String, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

evaluateAsBoolean

public boolean evaluateAsBoolean(Node contextNode)
                          throws XPathException

Evaluates this XPath in the context of the given Node and returns the result as a boolean. If this XPath naturally evaluates to a type other than boolean, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

evaluateAsNumber

public double evaluateAsNumber(Node contextNode)
                        throws XPathException

Evaluates this XPath in the context of the given Node and returns the result as a number. If this XPath naturally evaluates to a type other than number, the necessary type conversion will be performed as described in the XPath specification.

Throws:

XPathException

setVariableBindings

public void setVariableBindings(Map bindings)

Sets the variable bindings for the evaluation process. This method must not be called after one of the xpath's evaluate methods has been called.

Parameters:

variableBindings - Provides a mapping for resolving variable names which may appear in the XPath. Values in the map which are instances of java.lang.String, java.lang.Boolean, or java.lang.Number will be used as values of the corresponding XPath types. Values which are instances of java.util.List are assumed to be node-lists. Values of other types are not currently recognized.

toString

public String toString()

Returns the string used to construct thie XPath.

Overrides:

toString in class Object

main

public static void main(String[] args)
                 throws Exception

This method allows an expression to be evaluated from the command line. Simply pass a url or filename as the first argument and an xpath as the second argument.

Throws:

Exception