001: /*
002: * Copyright 2007 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: import javax.xml.transform.Source;
021:
022: import org.w3c.dom.Node;
023:
024: /**
025: * Interface that specifies a basic set of XPath operations, implemented by various XPathTemplates. Contains numerous
026: * evaluation methods,
027: * <p/>
028: * The templates that implement this interface do not use precompiled XPath expressions. Consider using the {@link
029: * XPathExpressionFactory} or the {@link XPathExpressionFactoryBean} for optimal performance, but less flexibility.
030: *
031: * @author Arjen Poutsma
032: * @see Jaxp13XPathTemplate
033: * @see JaxenXPathTemplate
034: * @since 1.0.0
035: */
036: public interface XPathOperations {
037:
038: /**
039: * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or
040: * <code>false</code> if it is invalid.
041: *
042: * @param expression the XPath expression
043: * @param context the context starting point
044: * @return the result of the evaluation
045: * @throws XPathException in case of XPath errors
046: * @see <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a>
047: */
048: boolean evaluateAsBoolean(String expression, Source context)
049: throws XPathException;
050:
051: /**
052: * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code>
053: * if it is invalid.
054: *
055: * @param expression the XPath expression
056: * @param context the context starting point
057: * @return the result of the evaluation
058: * @throws XPathException in case of XPath errors
059: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
060: */
061: Node evaluateAsNode(String expression, Source context)
062: throws XPathException;
063:
064: /**
065: * Evaluates the given expression as a list of {@link Node} objects. Returns the evaluation of the expression, or an
066: * empty list if no results are found.
067: *
068: * @param expression the XPath expression
069: * @param context the context starting point
070: * @return the result of the evaluation
071: * @throws XPathException in case of XPath errors
072: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
073: */
074: List evaluateAsNodeList(String expression, Source context)
075: throws XPathException;
076:
077: /**
078: * Evaluates the given expression as a <code>double</code>. Returns the evaluation of the expression, or {@link
079: * Double#NaN} if it is invalid.
080: *
081: * @param expression the XPath expression
082: * @param context the context 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#numbers">XPath specification</a>
086: */
087: double evaluateAsDouble(String expression, Source context)
088: throws XPathException;
089:
090: /**
091: * Evaluates the given expression as a {@link String}. Returns the evaluation of the expression, or
092: * <code>null</code> if it is invalid.
093: *
094: * @param expression the XPath expression
095: * @param context the context starting point
096: * @return the result of the evaluation
097: * @throws XPathException in case of XPath errors
098: * @see <a href="http://www.w3.org/TR/xpath#strings">XPath specification</a>
099: */
100: String evaluateAsString(String expression, Source context)
101: throws XPathException;
102:
103: /**
104: * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}.
105: *
106: * @param expression the XPath expression
107: * @param context the context starting point
108: * @param nodeMapper object that will map one object per node
109: * @return the single mapped object
110: * @throws XPathException in case of XPath errors
111: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
112: */
113: Object evaluateAsObject(String expression, Source context,
114: NodeMapper nodeMapper) throws XPathException;
115:
116: /**
117: * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link
118: * NodeMapper}.
119: *
120: * @param expression the XPath expression
121: * @param context the context starting point
122: * @param nodeMapper object that will map one object per node
123: * @return the result list, containing mapped objects
124: * @throws XPathException in case of XPath errors
125: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
126: */
127: List evaluate(String expression, Source context,
128: NodeMapper nodeMapper) throws XPathException;
129:
130: /**
131: * Evaluates the given expression, handling the result {@link Node} objects on a per-node basis with a {@link
132: * NodeCallbackHandler}.
133: *
134: * @param expression the XPath expression
135: * @param context the context starting point
136: * @param callbackHandler object that will extract results, one row at a time
137: * @throws XPathException in case of XPath errors
138: * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
139: */
140: void evaluate(String expression, Source context,
141: NodeCallbackHandler callbackHandler) throws XPathException;
142: }
|