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 */ 25package javax.xml.xpath; 26 27import java.util.Objects; 28import javax.xml.namespace.QName; 29import 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 * 36 * @param <T> the object type returned by the XPath evaluation. 37 * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 38 * 1.0</a> 39 * 40 * @since 9 41 */ 42public interface XPathEvaluationResult<T> { 43 44 /** 45 * XPathResultType represents possible return types of an XPath evaluation. 46 * Provided as an enum type, it allows the use of switch statement. At the 47 * same time, a mapping is provided between the original QName types in 48 * {@link XPathConstants} and class types used in the generic methods. 49 */ 50 public static enum XPathResultType { 51 /** 52 * Any type that represents any of the 5 other types listed below. 53 * Maps to {@link XPathEvaluationResult}. 54 */ 55 ANY(new QName("http://www.w3.org/1999/XSL/Transform", "any"), XPathEvaluationResult.class), 56 /** 57 * The XPath 1.0 boolean data type. Maps to Java {@link Boolean}. 58 */ 59 BOOLEAN(XPathConstants.BOOLEAN, Boolean.class), 60 /** 61 * The XPath 1.0 Number data type. Maps to Java {@link Number}. Of the 62 * subtypes of Number, only Double, Integer and Long are required. 63 */ 64 NUMBER(XPathConstants.NUMBER, Number.class), 65 /** 66 * The XPath 1.0 String data type. Maps to Java {@link String}. 67 */ 68 STRING(XPathConstants.STRING, String.class), 69 /** 70 * The XPath 1.0 NodeSet data type. Maps to {@link org.w3c.dom.NodeList}. 71 */ 72 NODESET(XPathConstants.NODESET, XPathNodes.class), 73 /** 74 * The XPath 1.0 NodeSet data type. Maps to {@link org.w3c.dom.Node}. 75 */ 76 NODE(XPathConstants.NODE, Node.class); 77 78 final QName qnameType; 79 final Class<?> clsType; 80 XPathResultType(QName qnameType, Class<?> clsType) { 81 this.qnameType = qnameType; 82 this.clsType = clsType; 83 } 84 85 /** 86 * Compares this type to the specified class type. 87 * @param clsType class type 88 * @return true if the argument is not null and is a class type that 89 * matches that this type represents, false otherwise. 90 */ 91 private boolean equalsClassType(Class<?> clsType) { 92 Objects.nonNull(clsType); 93 if (clsType.isAssignableFrom(this.clsType)) { 94 return true; 95 } 96 return false; 97 } 98 99 /** 100 * Returns the QName type as specified in {@link XPathConstants} that 101 * corresponds to the specified class type. 102 * @param clsType a class type that the enum type supports 103 * @return the QName type that matches with the specified class type, 104 * null if there is no match 105 */ 106 static public QName getQNameType(Class<?> clsType) { 107 for (XPathResultType type : XPathResultType.values()) { 108 if (type.equalsClassType(clsType)) { 109 return type.qnameType; 110 } 111 } 112 return null; 113 } 114 } 115 116 /** 117 * Return the result type as an enum specified by {@code XPathResultType} 118 * @return the result type 119 */ 120 public XPathResultType type(); 121 122 /** 123 * Returns the value of the result as the type {@code <T>} specified for the class. 124 * 125 * @return The value of the result. 126 */ 127 public T value(); 128 129} 130