java.lang.Object
- com.jcabi.xml.XMLDocument

All Implemented Interfaces:

XML
```
public final class XMLDocument
extends Object
implements XML
```
Implementation of XML.
Objects of this class are immutable and thread-safe.

Since:

0.1

Suppressed Checkstyle violations:

ClassFanOutComplexity (500 lines), AbbreviationAsWordInNameCheck (10 lines)

Constructor Summary

Constructors
Constructor	Description
`XMLDocument(byte[] data)`	Public ctor, from XML as a text.
`XMLDocument(File file)`	Public ctor, from XML in a file.
`XMLDocument(InputStream stream)`	Public ctor, from input stream.
`XMLDocument(String text)`	Public ctor, from XML as a text.
`XMLDocument(URI uri)`	Public ctor, from XML in the URI.
`XMLDocument(URL url)`	Public ctor, from XML in the URL.
`XMLDocument(Path file)`	Public ctor, from XML in a file.
`XMLDocument(Source source)`	Public ctor, from a source.
`XMLDocument(Node node)`	Public ctor, from a DOM node.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`boolean`	`equals(Object another)`
`int`	`hashCode()`
`XML`	`merge(NamespaceContext ctx)`	Append this namespace context to the existing one.
`Node`	`node()`	Retrieve DOM node, represented by this wrapper.
`List<XML>`	`nodes(String query)`	Retrieve DOM nodes from the XML response.
`XML`	`registerNs(String prefix, Object uri)`	Register additional namespace prefix for XPath.
`String`	`toString()`
`List<String>`	`xpath(String query)`	Find and return text elements or attributes matched by XPath address.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - XMLDocument
```
public XMLDocument(String text)
```
    Public ctor, from XML as a text.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, for convenience, including:
    xhtml: http://www.w3.org/1999/xhtml xs: http://www.w3.org/2001/XMLSchema xsi: http://www.w3.org/2001/XMLSchema-instance xsl: http://www.w3.org/1999/XSL/Transform svg: http://www.w3.org/2000/svg
    
    In future versions we will add more namespaces (submit a ticket if you need more of them defined here).
    Parameters:
    
    text - XML document body
  - XMLDocument
```
public XMLDocument(byte[] data)
```
    Public ctor, from XML as a text.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, for convenience, including:
    xhtml: http://www.w3.org/1999/xhtml xs: http://www.w3.org/2001/XMLSchema xsi: http://www.w3.org/2001/XMLSchema-instance xsl: http://www.w3.org/1999/XSL/Transform svg: http://www.w3.org/2000/svg
    
    In future versions we will add more namespaces (submit a ticket if you need more of them defined here).
    Parameters:
    
    data - The XML body
  - XMLDocument
```
public XMLDocument(Node node)
```
    Public ctor, from a DOM node.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    
    Parameters:
    
    node - DOM source
    
    Since:
    
    0.2
  - XMLDocument
```
public XMLDocument(Source source)
```
    Public ctor, from a source.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    
    Parameters:
    
    source - Source of XML document
  - XMLDocument
```
public XMLDocument(File file)
            throws FileNotFoundException
```
    Public ctor, from XML in a file.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    
    Parameters:
    
    file - XML file
    
    Throws:
    
    FileNotFoundException - In case of I/O problems
  - XMLDocument
```
public XMLDocument(Path file)
            throws FileNotFoundException
```
    Public ctor, from XML in a file.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    
    Parameters:
    
    file - XML file
    
    Throws:
    
    FileNotFoundException - In case of I/O problems
  - XMLDocument
```
public XMLDocument(URL url)
            throws IOException
```
    Public ctor, from XML in the URL.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    
    Parameters:
    
    url - The URL to load from
    
    Throws:
    
    IOException - In case of I/O problems
  - XMLDocument
```
public XMLDocument(URI uri)
            throws IOException
```
    Public ctor, from XML in the URI.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    
    Parameters:
    
    uri - The URI to load from
    
    Throws:
    
    IOException - In case of I/O problems
  - XMLDocument
```
public XMLDocument(InputStream stream)
            throws IOException
```
    Public ctor, from input stream.
    The object is created with a default implementation of NamespaceContext, which already defines a number of namespaces, see XMLDocument(String).
    An IllegalArgumentException is thrown if the parameter passed is not in XML format.
    The provided input stream will be closed automatically after getting data from it.
    
    Parameters:
    
    stream - The input stream, which will be closed automatically
    
    Throws:
    
    IOException - In case of I/O problem
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
public boolean equals(Object another)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - node
```
public Node node()
```
    Description copied from interface: XML
    
    Retrieve DOM node, represented by this wrapper.
    
    Specified by:
    
    node in interface XML
    
    Returns:
    
    DOM node
  - xpath
```
public List<String> xpath(String query)
```
    Description copied from interface: XML
    
    Find and return text elements or attributes matched by XPath address.
    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 RuntimeException will be thrown.
    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 <a> elements, the input query "count(//a)", will return a singleton List with a single string value "3".
    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 xpath(..).get(0)). But when/if you need to get more than just a plain text - use XML.nodes(String).
    The List returned will throw IndexOutOfBoundsException if you try to access a node which wasn't found by this XPath query.
    An IllegalArgumentException is thrown if the parameter passed is not a valid XPath expression.
    
    Specified by:
    
    xpath in interface XML
    
    Parameters:
    
    query - The XPath query
    
    Returns:
    
    The list of string values (texts) or single function result
  - registerNs
```
public XML registerNs(String prefix,
                      Object uri)
```
    Description copied from interface: XML
    Register additional namespace prefix for XPath.
    For example:
    String name = new XMLDocument("...") .registerNs("ns1", "http://example.com") .registerNs("foo", "http://example.com/foo") .xpath("/ns1:root/foo:name/text()") .get(0);
    
    A number of standard namespaces are registered by default in instances of XML. Their full list is in XMLDocument(String).
    If a namespace prefix is already registered an IllegalArgumentException will be thrown.
    Specified by:
    
    registerNs in interface XML
    
    Parameters:
    
    prefix - The XPath prefix to register
    
    uri - Namespace URI
    
    Returns:
    
    A new XML document, with this additional namespace registered
  - nodes
```
public List<XML> nodes(String query)
```
    Description copied from interface: XML
    
    Retrieve DOM nodes from the XML response.
    The List returned will throw IndexOutOfBoundsException if you try to access a node which wasn't found by this XPath query.
    An IllegalArgumentException is thrown if the parameter passed is not a valid XPath expression.
    
    Specified by:
    
    nodes in interface XML
    
    Parameters:
    
    query - The XPath query
    
    Returns:
    
    Collection of DOM nodes
  - merge
```
public XML merge(NamespaceContext ctx)
```
    Description copied from interface: XML
    
    Append this namespace context to the existing one.
    The existing context (inside this object) and the new one provided will be merged together. The existing context will be have higher priority.
    
    Specified by:
    
    merge in interface XML
    
    Parameters:
    
    ctx - The context to append
    
    Returns:
    
    A new XML document, with a merged context on board

Class XMLDocument

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XMLDocument

XMLDocument

XMLDocument

XMLDocument

XMLDocument

XMLDocument

XMLDocument

XMLDocument

XMLDocument

Method Detail

toString

equals

hashCode

node

xpath

registerNs

nodes

merge