From 86ce86f353372ac0e3e58476750124edb67fbb87 Mon Sep 17 00:00:00 2001
From: Arjen Poutsma <apoutsma@vmware.com>
Date: Wed, 1 Sep 2010 11:25:21 +0000
Subject: [PATCH] SWS-640 - evaluateAsBoolean returns true for node with text
 content "false"

---
 .../xml/xpath/XPathExpression.java            | 19 ++++++++++++++---
 .../xml/xpath/XPathOperations.java            | 21 +++++++++++++++----
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java b/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
index eece0bc4..e0d88ace 100644
--- a/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
+++ b/xml/src/main/java/org/springframework/xml/xpath/XPathExpression.java
@@ -35,11 +35,18 @@ public interface XPathExpression {
     /**
      * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or
      * <code>false</code> if it is invalid.
+     * <p/>
+     * 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 <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-boolean">XPath specification - boolean() function</a>
      */
     boolean evaluateAsBoolean(Node node) throws XPathException;
 
@@ -68,21 +75,27 @@ public interface XPathExpression {
     /**
      * Evaluates the given expression as a number (<code>double</code>). Returns the numeric evaluation of the
      * expression, or {@link Double#NaN} if it is invalid.
+     * <p/>
+     * 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 <a href="http://www.w3.org/TR/xpath#numbers">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-number">XPath specification - number() function</a>
      */
     double evaluateAsNumber(Node node) throws XPathException;
 
     /**
      * Evaluates the given expression as a String. Returns <code>null</code> if no result could be found.
+     * <p/>
+     * 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 <a href="http://www.w3.org/TR/xpath#strings">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-string">XPath specification - string() function</a>
      */
     String evaluateAsString(Node node) throws XPathException;
 
diff --git a/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java b/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
index 32086c4d..beadd7f2 100644
--- a/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
+++ b/xml/src/main/java/org/springframework/xml/xpath/XPathOperations.java
@@ -38,12 +38,19 @@ public interface XPathOperations {
     /**
      * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or
      * <code>false</code> if it is invalid.
+     * <p/>
+     * 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 expression the XPath expression
      * @param context    the context starting point
      * @return the result of the evaluation
      * @throws XPathException in case of XPath errors
-     * @see <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-boolean">XPath specification - boolean() function</a>
      */
     boolean evaluateAsBoolean(String expression, Source context) throws XPathException;
 
@@ -74,24 +81,30 @@ public interface XPathOperations {
     /**
      * Evaluates the given expression as a <code>double</code>. Returns the evaluation of the expression, or {@link
      * Double#NaN} if it is invalid.
-     *
+     * <p/>
+     * 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 expression the XPath expression
      * @param context    the context starting point
      * @return the result of the evaluation
      * @throws XPathException in case of XPath errors
-     * @see <a href="http://www.w3.org/TR/xpath#numbers">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-number">XPath specification - number() function</a>
      */
     double evaluateAsDouble(String expression, Source context) throws XPathException;
 
     /**
      * Evaluates the given expression as a {@link String}. Returns the evaluation of the expression, or
      * <code>null</code> if it is invalid.
+     * <p/>
+     * 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 expression the XPath expression
      * @param context    the context starting point
      * @return the result of the evaluation
      * @throws XPathException in case of XPath errors
-     * @see <a href="http://www.w3.org/TR/xpath#strings">XPath specification</a>
+     * @see <a href="http://www.w3.org/TR/xpath/#function-string">XPath specification - string() function</a>
      */
     String evaluateAsString(String expression, Source context) throws XPathException;