@Immutable public interface XML
Set of convenient XML manipulations:
XML xml = new XMLDocument(content); for (XML employee : xml.nodes("//Employee")) { String name = employee.xpath("name/text()").get(0); // ... }
You can always get DOM node out of this abstraction using node()
method.
toString()
must produce a full XML.
Implementation of this interface must be immutable and thread-safe.
XMLDocument
Modifier and Type | Method and Description |
---|---|
XML |
merge(NamespaceContext context)
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.
|
List<String> |
xpath(String query)
Find and return text elements or attributes matched by XPath address.
|
@NotNull(message="list of texts is never NULL") List<String> xpath(@NotNull(message="query can\'t be NULL") String query)
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 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.
query
- The XPath query@NotNull(message="list of nodes is never NULL") List<XML> nodes(@NotNull(message="query can\'t be NULL") String query)
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.
query
- The XPath query@NotNull(message="XML is never NULL") XML registerNs(@NotNull(message="prefix can\'t be NULL") String prefix, @NotNull(message="URI can\'t be NULL") Object uri)
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.XMLDocument(String)
.
If a namespace prefix is already registered an
IllegalArgumentException
will be thrown.
prefix
- The XPath prefix to registeruri
- Namespace URI@NotNull(message="XML is never NULL") XML merge(@NotNull(message="context can\'t be NULL") NamespaceContext context)
The existing context (inside this object) and the new one provided will be merged together. The existing context will be have higher priority.
context
- The context to appendCopyright © 2012–2015 jcabi.com. All rights reserved.