Coverage Report

Coverage Report - com.jcabi.xml.XML

Classes in this File

 /**
  * Copyright (c) 2012-2017, jcabi.com
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met: 1) Redistributions of source code must retain the above
  * copyright notice, this list of conditions and the following
  * disclaimer. 2) Redistributions in binary form must reproduce the above
  * copyright notice, this list of conditions and the following
  * disclaimer in the documentation and/or other materials provided
  * with the distribution. 3) Neither the name of the jcabi.com nor
  * the names of its contributors may be used to endorse or promote
  * products derived from this software without specific prior written
  * permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 package com.jcabi.xml;
 
 import java.util.List;
 import javax.xml.namespace.NamespaceContext;
 import org.w3c.dom.Node;
 
 /**
  * XML document.
  *
  * <p>Set of convenient XML manipulations:
  *
  * <pre> XML xml = new XMLDocument(content);
  * for (XML employee : xml.nodes("//Employee")) {
  *   String name = employee.xpath("name/text()").get(0);
  *   // ...
  * }</pre>
  *
  * <p>You can always get DOM node out of this abstraction using {@link #node()}
  * method.
  *
  * <p>{@code toString()} must produce a full XML.
  *
  * <p>Implementation of this interface must be immutable and thread-safe.
  *
  * @author Yegor Bugayenko (yegor@teamed.io)
  * @version $Id: 9c5cd6f62a238f8950351c045fa42b34a93044e0 $
  * @since 0.1
  * @see XMLDocument
  */
 public interface XML {
 
     /**
      * Find and return text elements or attributes matched by XPath address.
      *
      * <p>The XPath query should point to text elements or attributes in the
      * XML document. If any nodes of different types (elements, comments, etc.)
      * are found in result node list -
      * a {@link RuntimeException} will be thrown.
      *
      * <p>Alternatively, the XPath query can be a function or expression that
      * returns a single value instead of pointing to a set of nodes. In this
      * case, the result will be a List containing a single String, the content
      * of which is the result of the evaluation. If the expression result is not
      * a String, it will be converted to a String representation and returned as
      * such. For example, a document containing three &lt;a&gt; elements,
      * the input query "count(//a)", will return a singleton List with a single
      * string value "3".
      *
      * <p>This is a convenient method, which is used (according to our
      * experience) in 95% of all cases. Usually you don't need to get anything
      * else but a text value of some node or an attribute. And in most cases
      * you are interested to get just the first value
      * (use {@code xpath(..).get(0)}). But when/if you need to get more than
      * just a plain text - use {@link #nodes(String)}.
      *
      * <p>The {@link List} returned will throw {@link IndexOutOfBoundsException}
      * if you try to access a node which wasn't found by this XPath query.
      *
      * <p>An {@link IllegalArgumentException} is thrown if the parameter
      * passed is not a valid XPath expression.
      *
      * @param query The XPath query
      * @return The list of string values (texts) or single function result
      */
     List<String> xpath(String query);
 
     /**
      * Retrieve DOM nodes from the XML response.
      *
      * <p>The {@link List} returned will throw {@link IndexOutOfBoundsException}
      * if you try to access a node which wasn't found by this XPath query.
      *
      * <p>An {@link IllegalArgumentException} is thrown if the parameter
      * passed is not a valid XPath expression.
      *
      * @param query The XPath query
      * @return Collection of DOM nodes
      */
     List<XML> nodes(String query);
 
     /**
      * Register additional namespace prefix for XPath.
      *
      * <p>For example:
      *
      * <pre>
      * String name = new XMLDocument("...")
      *   .registerNs("ns1", "http://example.com")
      *   .registerNs("foo", "http://example.com/foo")
      *   .xpath("/ns1:root/foo:name/text()")
      *   .get(0);
      * </pre>
      *
      * <p>A number of standard namespaces are registered by default in
      * instances of XML. Their
      * full list is in {@link XMLDocument#XMLDocument(String)}.
      *
      * <p>If a namespace prefix is already registered an
      * {@link IllegalArgumentException} will be thrown.
      *
      * @param prefix The XPath prefix to register
      * @param uri Namespace URI
      * @return A new XML document, with this additional namespace registered
      */
     XML registerNs(String prefix, Object uri);
 
     /**
      * Append this namespace context to the existing one.
      *
      * <p>The existing context (inside this object) and the new one provided
      * will be merged together. The existing context will be have higher
      * priority.
      *
      * @param context The context to append
      * @return A new XML document, with a merged context on board
      */
     XML merge(NamespaceContext context);
 
     /**
      * Retrieve DOM node, represented by this wrapper.
      * @return DOM node
      */
     Node node();
 
 }

1		/**
2		* Copyright (c) 2012-2017, 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		* @author Yegor Bugayenko (yegor@teamed.io)
55		* @version $Id: 9c5cd6f62a238f8950351c045fa42b34a93044e0 $
56		* @since 0.1
57		* @see XMLDocument
58		*/
59		public interface XML {
60
61		/**
62		* Find and return text elements or attributes matched by XPath address.
63		*
64		* <p>The XPath query should point to text elements or attributes in the
65		* XML document. If any nodes of different types (elements, comments, etc.)
66		* are found in result node list -
67		* a {@link RuntimeException} will be thrown.
68		*
69		* <p>Alternatively, the XPath query can be a function or expression that
70		* returns a single value instead of pointing to a set of nodes. In this
71		* case, the result will be a List containing a single String, the content
72		* of which is the result of the evaluation. If the expression result is not
73		* a String, it will be converted to a String representation and returned as
74		* such. For example, a document containing three <a> elements,
75		* the input query "count(//a)", will return a singleton List with a single
76		* string value "3".
77		*
78		* <p>This is a convenient method, which is used (according to our
79		* experience) in 95% of all cases. Usually you don't need to get anything
80		* else but a text value of some node or an attribute. And in most cases
81		* you are interested to get just the first value
82		* (use {@code xpath(..).get(0)}). But when/if you need to get more than
83		* just a plain text - use {@link #nodes(String)}.
84		*
85		* <p>The {@link List} returned will throw {@link IndexOutOfBoundsException}
86		* if you try to access a node which wasn't found by this XPath query.
87		*
88		* <p>An {@link IllegalArgumentException} is thrown if the parameter
89		* passed is not a valid XPath expression.
90		*
91		* @param query The XPath query
92		* @return The list of string values (texts) or single function result
93		*/
94		List<String> xpath(String query);
95
96		/**
97		* Retrieve DOM nodes from the XML response.
98		*
99		* <p>The {@link List} returned will throw {@link IndexOutOfBoundsException}
100		* if you try to access a node which wasn't found by this XPath query.
101		*
102		* <p>An {@link IllegalArgumentException} is thrown if the parameter
103		* passed is not a valid XPath expression.
104		*
105		* @param query The XPath query
106		* @return Collection of DOM nodes
107		*/
108		List<XML> nodes(String query);
109
110		/**
111		* Register additional namespace prefix for XPath.
112		*
113		* <p>For example:
114		*
115		* <pre>
116		* String name = new XMLDocument("...")
117		* .registerNs("ns1", "http://example.com")
118		* .registerNs("foo", "http://example.com/foo")
119		* .xpath("/ns1:root/foo:name/text()")
120		* .get(0);
121		* </pre>
122		*
123		* <p>A number of standard namespaces are registered by default in
124		* instances of XML. Their
125		* full list is in {@link XMLDocument#XMLDocument(String)}.
126		*
127		* <p>If a namespace prefix is already registered an
128		* {@link IllegalArgumentException} will be thrown.
129		*
130		* @param prefix The XPath prefix to register
131		* @param uri Namespace URI
132		* @return A new XML document, with this additional namespace registered
133		*/
134		XML registerNs(String prefix, Object uri);
135
136		/**
137		* Append this namespace context to the existing one.
138		*
139		* <p>The existing context (inside this object) and the new one provided
140		* will be merged together. The existing context will be have higher
141		* priority.
142		*
143		* @param context The context to append
144		* @return A new XML document, with a merged context on board
145		*/
146		XML merge(NamespaceContext context);
147
148		/**
149		* Retrieve DOM node, represented by this wrapper.
150		* @return DOM node
151		*/
152		Node node();
153
154		}