001: /*
002: * Copyright 2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.xml.xpath;
018:
019: import java.util.List;
020:
021: import org.w3c.dom.Node;
022:
023: /**
024: * Defines the contract for a precompiled XPath expression. Concrete instances can be obtained through the {@link
025: * XPathExpressionFactory}.
026: * <p/>
027: * Implementations of this interface are precompiled, and thus faster, but less flexible, than the XPath expressions
028: * used by {@link XPathOperations} implementations.
029: *
030: * @author Arjen Poutsma
031: * @since 1.0.0
032: */
033: public interface XPathExpression {
034:
035: /**
036: * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or
037: * <code>false</code> if it is invalid.
038: *
039: * @param node the starting point
040: * @return the result of the evaluation
041: * @throws XPathException in case of XPath errors
042: * @see <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a>
043: */
044: boolean evaluateAsBoolean(Node node) throws XPathException;
045:
046: /**
047: * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code>
048: * if it is invalid.
049: *
050: * @param node the starting point
051: * @return the result of the evaluation
052: * @throws XPathException in case of XPath errors
053: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
054: */
055: Node evaluateAsNode(Node node) throws XPathException;
056:
057: /**
058: * Evaluates the given expression, and returns all {@link Node} objects that conform to it. Returns an empty list if
059: * no result could be found.
060: *
061: * @param node the starting point
062: * @return a list of <code>Node</code>s that are selected by the expression
063: * @throws XPathException in case of XPath errors
064: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
065: */
066: List evaluateAsNodeList(Node node) throws XPathException;
067:
068: /**
069: * Evaluates the given expression as a number (<code>double</code>). Returns the numeric evaluation of the
070: * expression, or {@link Double#NaN} if it is invalid.
071: *
072: * @param node the starting point
073: * @return the result of the evaluation
074: * @throws XPathException in case of XPath errors
075: * @see <a href="http://www.w3.org/TR/xpath#numbers">XPath specification</a>
076: */
077: double evaluateAsNumber(Node node) throws XPathException;
078:
079: /**
080: * Evaluates the given expression as a String. Returns <code>null</code> if no result could be found.
081: *
082: * @param node the starting point
083: * @return the result of the evaluation
084: * @throws XPathException in case of XPath errors
085: * @see <a href="http://www.w3.org/TR/xpath#strings">XPath specification</a>
086: */
087: String evaluateAsString(Node node) throws XPathException;
088:
089: /**
090: * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}.
091: *
092: * @param node the starting point
093: * @param nodeMapper object that will map one object per node
094: * @return the single mapped object
095: * @throws XPathException in case of XPath errors
096: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
097: */
098: Object evaluateAsObject(Node node, NodeMapper nodeMapper)
099: throws XPathException;
100:
101: /**
102: * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link
103: * NodeMapper}.
104: *
105: * @param node the starting point
106: * @param nodeMapper object that will map one object per node
107: * @return the result list, containing mapped objects
108: * @throws XPathException in case of XPath errors
109: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
110: */
111: List evaluate(Node node, NodeMapper nodeMapper)
112: throws XPathException;
113: }
|