@Immutable public final class XMLDocument extends Object implements XML
XML
.
Objects of this class are immutable and thread-safe.
Constructor and Description |
---|
XMLDocument(File file)
Public ctor, from XML in a file.
|
XMLDocument(InputStream stream)
Public ctor, from input stream.
|
XMLDocument(Node node)
Public ctor, from a DOM node.
|
XMLDocument(Source source)
Public ctor, from a source.
|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
public XMLDocument(@NotNull(message="XML text can\'t be NULL") String 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).
An IllegalArgumentException
is thrown if the parameter
passed is not in XML format.
text
- XML document bodypublic XMLDocument(@NotNull(message="node can\'t be NULL") Node node)
The object is created with a default implementation of
NamespaceContext
, which already defines a
number of namespaces, see XMLDocument(String)
.
node
- DOM sourcepublic XMLDocument(@NotNull(message="source can\'t be NULL") Source 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.
source
- Source of XML documentpublic XMLDocument(@NotNull(message="file can\'t be NULL") File file) throws IOException
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.
file
- XML fileIOException
- In case of I/O problemspublic XMLDocument(@NotNull(message="URL can\'t be NULL") URL url) throws IOException
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.
url
- The URL to load fromIOException
- In case of I/O problemspublic XMLDocument(@NotNull(message="URI can\'t be NULL") URI uri) throws IOException
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.
uri
- The URI to load fromIOException
- In case of I/O problemspublic XMLDocument(@NotNull(message="input stream can\'t be NULL") InputStream stream) throws IOException
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.
stream
- The input stream, which will be closed automaticallyIOException
- In case of I/O problem@NotNull(message="node is never NULL") public Node node()
XML
@NotNull(message="list of texts is never NULL") public List<String> xpath(@NotNull String query)
XML
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.
@NotNull(message="XML is never NULL") public XML registerNs(@NotNull String prefix, @NotNull Object uri)
XML
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.
registerNs
in interface XML
prefix
- The XPath prefix to registeruri
- Namespace URI@NotNull(message="XML is never NULL") public List<XML> nodes(@NotNull String query)
XML
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.
@NotNull(message="XML is never NULL") public XML merge(@NotNull(message="context can\'t be NULL") NamespaceContext ctx)
XML
The existing context (inside this object) and the new one provided will be merged together. The existing context will be have higher priority.
Copyright © 2012–2015 jcabi.com. All rights reserved.