Package 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
Suppressed Checkstyle violations:
AbbreviationAsWordInNameCheck (5 lines)

  • Constructor Details

    • StrictXML

      public StrictXML(XML xml)
      Public ctor.
      Parameters:
      xml - XML document

    • StrictXML

      public StrictXML(XML xml, LSResourceResolver resolver)
      Public ctor.
      Parameters:
      xml - XML document
      resolver - Custom resolver
      Since:
      0.19

    • StrictXML

      public StrictXML(XML xml, Validator val)
      Public ctor.
      Parameters:
      xml - XML document
      val - Custom validator

    • StrictXML

      public StrictXML(XML xml, XML schema)
      Public ctor.
      Parameters:
      xml - XML document
      schema - XSD schema

  • Method Details

    • 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(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 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

      @Deprecated public Node node()
      Deprecated.
      Use inner() or deepCopy() instead.
      Retrieve DOM node, represented by this wrapper. This method works exactly the same as deepCopy().
      Specified by:
      node in interface XML
      Returns:
      Deep copy of the inner DOM node.

    • inner

      public Node inner()
      Description copied from interface: XML
      Retrieve DOM node, represented by this wrapper. Pay attention that this method returns inner node, not a deep copy. It means that any changes to the returned node will affect the original XML.
      Specified by:
      inner in interface XML
      Returns:
      Inner node.

    • deepCopy

      public Node deepCopy()
      Description copied from interface: XML
      Retrieve a deep copy of the DOM node, represented by this wrapper. Might be expensive in terms of performance.
      Specified by:
      deepCopy in interface XML
      Returns:
      Deep copy of the node.

    • validate

      public Collection<SAXParseException> validate()
      Description copied from interface: XML
      Validate this XML against the XSD schema inside it.
      Specified by:
      validate in interface XML
      Returns:
      List of errors found

    • validate

      public Collection<SAXParseException> validate(XML xsd)
      Description copied from interface: XML
      Validate this XML against the provided XSD schema.
      Specified by:
      validate in interface XML
      Parameters:
      xsd - The Schema
      Returns:
      List of errors found