org.springframework.xml.xpath.XPathExpression Maven / Gradle / Ivy
/*
* Copyright 2005-2010 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.xml.xpath;
import java.util.List;
import org.w3c.dom.Node;
/**
* Defines the contract for a precompiled XPath expression. Concrete instances can be obtained through the {@link
* XPathExpressionFactory}.
*
* Implementations of this interface are precompiled, and thus faster, but less flexible, than the XPath expressions
* used by {@link XPathOperations} implementations.
*
* @author Arjen Poutsma
* @since 1.0.0
*/
public interface XPathExpression {
/**
* Evaluates the given expression as a {@code boolean}. Returns the boolean evaluation of the expression, or
* {@code false} if it is invalid.
*
*
The return value is determined per the {@code boolean()} function defined in the XPath specification.
* This means that an expression that selects zero nodes will return {@code false}, while an expression that
* selects one or more nodes will return {@code true}.
* An expression that returns a string returns {@code false} for empty strings and {@code true} for all other
* strings.
* An expression that returns a number returns {@code false} for zero and {@code true} for non-zero numbers.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
* @see XPath specification - boolean() function
*/
boolean evaluateAsBoolean(Node node) throws XPathException;
/**
* Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or {@code null}
* if it is invalid.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
* @see XPath specification
*/
Node evaluateAsNode(Node node) throws XPathException;
/**
* Evaluates the given expression, and returns all {@link Node} objects that conform to it. Returns an empty list if
* no result could be found.
*
* @param node the starting point
* @return a list of {@code Node}s that are selected by the expression
* @throws XPathException in case of XPath errors
* @see XPath specification
*/
List evaluateAsNodeList(Node node) throws XPathException;
/**
* Evaluates the given expression as a number ({@code double}). Returns the numeric evaluation of the
* expression, or {@link Double#NaN} if it is invalid.
*
* The return value is determined per the {@code number()} function as defined in the XPath specification.
* This means that if the expression selects multiple nodes, it will return the number value of the first node.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
* @see XPath specification - number() function
*/
double evaluateAsNumber(Node node) throws XPathException;
/**
* Evaluates the given expression as a String. Returns {@code null} if no result could be found.
*
*
The return value is determined per the {@code string()} function as defined in the XPath specification.
* This means that if the expression selects multiple nodes, it will return the string value of the first node.
*
* @param node the starting point
* @return the result of the evaluation
* @throws XPathException in case of XPath errors
* @see XPath specification - string() function
*/
String evaluateAsString(Node node) throws XPathException;
/**
* Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}.
*
* @param node the starting point
* @param nodeMapper object that will map one object per node
* @return the single mapped object
* @throws XPathException in case of XPath errors
* @see XPath specification
*/
T evaluateAsObject(Node node, NodeMapper nodeMapper) throws XPathException;
/**
* Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link
* NodeMapper}.
*
* @param node the starting point
* @param nodeMapper object that will map one object per node
* @return the result list, containing mapped objects
* @throws XPathException in case of XPath errors
* @see XPath specification
*/
List evaluate(Node node, NodeMapper nodeMapper) throws XPathException;
}