com.jcabi.xml

Class StrictXML

java.lang.Object

com.jcabi.xml.StrictXML

All Implemented Interfaces:

XML

public final class StrictXML
extends Object
implements XML

Strict XML that fails if encapsulated XML document doesn't validate against externally provided XSD schema or internally specified schema locations.

Objects of this class are immutable and thread-safe.

Since:

0.7

Version:

$Id$

Author:

Yegor Bugayenko (yegor@tpc2.com)

Constructor Summary

Constructors

Constructor and Description
StrictXML(XML xml) Public ctor.
StrictXML(XML xml, XSD schema) Public ctor.

Method Summary

Methods

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.
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, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StrictXML

public StrictXML(@NotNull(message="XML can\'t be NULL")
         XML xml)

Public ctor.

Parameters:

xml - XML document

StrictXML

public StrictXML(@NotNull(message="XML can\'t be NULL")
         XML xml,
         @NotNull(message="XSD schema can\'t be NULL")
         XSD schema)

Public ctor.

Parameters:

xml - XML document

schema - XSD schema

Method Detail

toString

public String toString()

Overrides:

toString in class Object

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

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

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.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

merge

public XML merge(NamespaceContext context)

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:

context - The context to append

Returns:

A new XML document, with a merged context on board

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