1 /* 2 * Copyright (c) 2015 Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package javax.xml.xpath; 26 27 import java.util.Objects; 28 import javax.xml.namespace.QName; 29 import org.w3c.dom.Node; 30 /** 31 * The {@code XPathEvaluationResult} interface represents the result of the 32 * evaluation of an XPath expression within the context of a particular node. 33 * The evaluation of an XPath expression can result in various result types as 34 * defined in XML Path Language (XPath) Version 1.0. 35 * <p> 36 * 37 * @param <T> the object type returned by the XPath evaluation. 38 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 39 * 1.0</a> 40 * 41 * @since 1.9 42 */ 43 public interface XPathEvaluationResult<T> { 44 45 /** 46 * XPathResultType represents possible return types of an XPath evaluation. 47 * Provided as an enum type, it allows the use of switch statement. At the 48 * same time, a mapping is provided between the original QName types in 49 * {@link XPathConstants} and class types used in the generic methods. 50 */ 51 public static enum XPathResultType { 52 /** 53 * Any type that represents any of the 5 other types listed below. 54 * Maps to {@link XPathEvaluationResult}. 55 */ 56 ANY(new QName("http://www.w3.org/1999/XSL/Transform", "any"), XPathEvaluationResult.class), 57 /** 58 * The XPath 1.0 boolean data type. Maps to Java {@link Boolean}. 59 */ 60 BOOLEAN(XPathConstants.BOOLEAN, Boolean.class), 61 /** 62 * The XPath 1.0 Number data type. Maps to Java {@link Number}. Of the 63 * subtypes of Number, only Double, Integer and Long are required. 64 */ 65 NUMBER(XPathConstants.NUMBER, Number.class), 66 /** 67 * The XPath 1.0 String data type. Maps to Java {@link String}. 68 */ 69 STRING(XPathConstants.STRING, String.class), 70 /** 71 * The XPath 1.0 NodeSet data type. Maps to {@link org.w3c.dom.NodeList}. 72 */ 73 NODESET(XPathConstants.NODESET, XPathNodes.class), 74 /** 75 * The XPath 1.0 NodeSet data type. Maps to {@link org.w3c.dom.Node}. 76 */ 77 NODE(XPathConstants.NODE, Node.class); 78 79 final QName qnameType; 80 final Class<?> clsType; 81 XPathResultType(QName qnameType, Class<?> clsType) { 82 this.qnameType = qnameType; 83 this.clsType = clsType; 84 } 85 86 /** 87 * Compares this type to the specified class type. 88 * @param clsType class type 89 * @return true if the argument is not null and is a class type that 90 * matches that this type represents, false otherwise. 91 */ 92 private boolean equalsClassType(Class<?> clsType) { 93 Objects.nonNull(clsType); 94 if (clsType.isAssignableFrom(this.clsType)) { 95 return true; 96 } 97 return false; 98 } 99 100 /** 101 * Returns the QName type as specified in {@link XPathConstants} that 102 * corresponds to the specified class type. 103 * @param clsType a class type that the enum type supports 104 * @return the QName type that matches with the specified class type, 105 * null if there is no match 106 */ 107 static public QName getQNameType(Class<?> clsType) { 108 for (XPathResultType type : XPathResultType.values()) { 109 if (type.equalsClassType(clsType)) { 110 return type.qnameType; 111 } 112 } 113 return null; 114 } 115 } 116 117 /** 118 * Return the result type as an enum specified by {@code XPathResultType} 119 * @return the result type 120 */ 121 public XPathResultType type(); 122 123 /** 124 * Returns the value of the result as the type <T> specified for the class. 125 * 126 * @return The value of the result. 127 */ 128 public T value(); 129 130 }