weblogic.xml.xpath
Class StreamXPath

java.lang.Object
  weblogic.xml.xpath.StreamXPath

public final class StreamXPath
extends Object

Represents an xpath for evaluation against an XMLInputStream. Instances of this class are installed in an XPathStreamFactory which in turn can create XMLInputStreams which performs xpath matching.

An instance of StreamXPath is a handle to a parsed representation of a particular xpath expression - parsing occurs when the StreamXPath is constructed. A single StreamXPath instance can be installed any number of times in any number of factories so that the expense of parsing a given xpath expression is paid only once.

XPath Support

The sequential nature of stream-based XML processing makes it impractical for StreamXPath to fully support the XPath specification. The StreamXPath constructor will throw an XPathUnsupportedException if the given XPath contains any of the unsupported features or constructs described below:

General

The root expression of a StreamXPath is always a location path which describes the node-set to be observed. It may be absolute or relative; in fact, it makes no difference, since the evaluation always occurs relative to the first node (Element event) encountered on the stream (which is assumed to be the doucment root element).

Core Functions

All of the XPath 1.0 core functions are supported with the exception of the following: last, size, id, lang, and count.

The string() function is not fully supported; it cannot convert a nodeset containing element nodes to a string. This is because the string value of an element is dependent on it's descendant elements, which will not be processed until later in the stream. This limitation also applies to implicit uses of 'string()' as described in the spec - any case where the string-value of a nodeset must be determined.

Axes

The following axes are supported in the location path which is the root expression of the xpath: self, child, descendant, descendant-or-self, following, following-sibling, attribute and namespace.

Predicates

The root location path may contain predicates, and those predicate expressions may in turn contain location paths. Location paths appearing anywhere inside a predicate must be relative (i.e. no leading slash) and may only use the following axes: self, ancestor, and ancestor-or-self, attribute, and namespace.

Data Model

XPath models an XML document as a tree of nodes. For purposes of streaming evaluation, a node is actually described by two XMLEvents - a START_ELEMENT and an END_ELEMENT. Whenever a START_ELEMENT is encountered that matches the stream, it's corresponding END_ELEMENT will eventually be observed as well.

START_DOCUMENT and END_DOCUMENT are just treated as special cases of START_ELEMENT and END_ELEMENT. It is expected that the first event on the stream will be a START_DOCUMENT event, and the last event will be END_DOCUMENT, although this is not strictly enforced. START_DOCUMENT (along with it's corresponding END_DOCUMENT event) is mapped to the 'Root Node' of the XPath Data model described in section 5.1 of the XPath specification. Thus, an observer on an XPath '.' will always see the START_DOCUMENT and END_DOCUMENT events.

Note: when a both a START-ELEMENT and its attribute and/or namespace declarations element are matches, the element notification is sent out first, followed by the attributes, and finally the namespaces.

StreamXPath

public StreamXPath(String xpath)
            throws XPathException

Constructs a new representation of the given xpath. The xpath provided in the string must be either a location path or an expression which evaluates to a boolean value. If the former, then the given location path simply becomes the 'root location path' as described in the 'XPath Support' section above.

In the latter case, where the given 'xpath' is a boolean expression, it is implicitly converted into a location path that is the equivalent of the following: (//.[xpath] | //attribute::*[xpath] | //namespace::*[xpath]) which is to say, a node n (including attribute and namespace nodes) is considered to be a match if and only if 'xpath' evaluates to true in an xpath context whose context node is n. This idiom is included primarily to facilitate the use of StreamXPath in processing XML Signatures (see http://www.w3.org/TR/xmldsig-core/#sec-XPath).

Note that all of the restrictions described above under 'XPath Support' will apply to such a synthesized location path. The boolean expression appears as a predicate in the location path, and so all of the restrictions described under 'Predicates' apply. In particular, note that only the acceptable predicate axes may be used within the boolean expression: self, ancestor, and ancestor-or-self, attribute, and namespace.

Parameters:

xpath - The string form of 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.

setVariableBindings

public void setVariableBindings(Map variableBindings)

Sets the variable bindings to be used when evaluating this XPath.

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.Collection are assumed to be node-lists. Values of other types are not currently recognized. Passing null has the effect of removing all bindings.

toString

public String toString()

Overrides:

toString in class Object

Returns:

The string used to construct this XPath. May be useful for debugging.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

main

public static void main(String[] args)

This method allows an expression to be evaluated from the command line using the stream infrastructure. The first command line argument should be the url of a document to evaluate, and the second is an xpath expression to match against that document. Each of the matching events are then printed to std out.