1 /* 2 * Copyright (c) 2012-2022, jcabi.com 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 1) Redistributions of source code must retain the above 8 * copyright notice, this list of conditions and the following 9 * disclaimer. 2) Redistributions in binary form must reproduce the above 10 * copyright notice, this list of conditions and the following 11 * disclaimer in the documentation and/or other materials provided 12 * with the distribution. 3) Neither the name of the jcabi.com nor 13 * the names of its contributors may be used to endorse or promote 14 * products derived from this software without specific prior written 15 * permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 28 * OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 package com.jcabi.xml; 31 32 import java.util.List; 33 import javax.xml.namespace.NamespaceContext; 34 import org.w3c.dom.Node; 35 36 /** 37 * XML document. 38 * 39 * <p>Set of convenient XML manipulations: 40 * 41 * <pre> XML xml = new XMLDocument(content); 42 * for (XML employee : xml.nodes("//Employee")) { 43 * String name = employee.xpath("name/text()").get(0); 44 * // ... 45 * }</pre> 46 * 47 * <p>You can always get DOM node out of this abstraction using {@link #node()} 48 * method. 49 * 50 * <p>{@code toString()} must produce a full XML. 51 * 52 * <p>Implementation of this interface must be immutable and thread-safe. 53 * 54 * @see XMLDocument 55 * @since 0.1 56 * @checkstyle AbbreviationAsWordInNameCheck (5 lines) 57 */ 58 public interface XML { 59 60 /** 61 * Find and return text elements or attributes matched by XPath address. 62 * 63 * <p>The XPath query should point to text elements or attributes in the 64 * XML document. If any nodes of different types (elements, comments, etc.) 65 * are found in result node list - 66 * a {@link RuntimeException} will be thrown. 67 * 68 * <p>Alternatively, the XPath query can be a function or expression that 69 * returns a single value instead of pointing to a set of nodes. In this 70 * case, the result will be a List containing a single String, the content 71 * of which is the result of the evaluation. If the expression result is not 72 * a String, it will be converted to a String representation and returned as 73 * such. For example, a document containing three <a> elements, 74 * the input query "count(//a)", will return a singleton List with a single 75 * string value "3". 76 * 77 * <p>This is a convenient method, which is used (according to our 78 * experience) in 95% of all cases. Usually you don't need to get anything 79 * else but a text value of some node or an attribute. And in most cases 80 * you are interested to get just the first value 81 * (use {@code xpath(..).get(0)}). But when/if you need to get more than 82 * just a plain text - use {@link #nodes(String)}. 83 * 84 * <p>The {@link List} returned will throw {@link IndexOutOfBoundsException} 85 * if you try to access a node which wasn't found by this XPath query. 86 * 87 * <p>An {@link IllegalArgumentException} is thrown if the parameter 88 * passed is not a valid XPath expression. 89 * 90 * @param query The XPath query 91 * @return The list of string values (texts) or single function result 92 */ 93 List<String> xpath(String query); 94 95 /** 96 * Retrieve DOM nodes from the XML response. 97 * 98 * <p>The {@link List} returned will throw {@link IndexOutOfBoundsException} 99 * if you try to access a node which wasn't found by this XPath query. 100 * 101 * <p>An {@link IllegalArgumentException} is thrown if the parameter 102 * passed is not a valid XPath expression. 103 * 104 * @param query The XPath query 105 * @return Collection of DOM nodes 106 */ 107 List<XML> nodes(String query); 108 109 /** 110 * Register additional namespace prefix for XPath. 111 * 112 * <p>For example: 113 * 114 * <pre> 115 * String name = new XMLDocument("...") 116 * .registerNs("ns1", "http://example.com") 117 * .registerNs("foo", "http://example.com/foo") 118 * .xpath("/ns1:root/foo:name/text()") 119 * .get(0); 120 * </pre> 121 * 122 * <p>A number of standard namespaces are registered by default in 123 * instances of XML. Their 124 * full list is in {@link XMLDocument#XMLDocument(String)}. 125 * 126 * <p>If a namespace prefix is already registered an 127 * {@link IllegalArgumentException} will be thrown. 128 * 129 * @param prefix The XPath prefix to register 130 * @param uri Namespace URI 131 * @return A new XML document, with this additional namespace registered 132 */ 133 XML registerNs(String prefix, Object uri); 134 135 /** 136 * Append this namespace context to the existing one. 137 * 138 * <p>The existing context (inside this object) and the new one provided 139 * will be merged together. The existing context will be have higher 140 * priority. 141 * 142 * @param context The context to append 143 * @return A new XML document, with a merged context on board 144 */ 145 XML merge(NamespaceContext context); 146 147 /** 148 * Retrieve DOM node, represented by this wrapper. 149 * @return DOM node 150 */ 151 Node node(); 152 153 }