Package org.opencms.xml

Class CmsXmlUtils

  • public final class CmsXmlUtils
extends java.lang.Object
    Provides some basic XML handling utilities.

    Since:
    6.0.0

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String concatXpath​(java.lang.String prefix, java.lang.String suffix)
      Concatenates two Xpath expressions, ensuring that exactly one slash "/" is between them.
      static org.w3c.dom.Document convertDocumentFromDom4jToW3C​(org.dom4j.Document doc)
      Converts an org.dom4j.Document to a org.w3c.dom.Document.
      static org.dom4j.Document convertDocumentFromW3CToDom4j​(org.w3c.dom.Document doc)
      Converts an org.w3c.dom.Document to an org.dom4j.Document.
      static java.lang.String createXpath​(java.lang.String path, int index)
      Translates a simple lookup path to the simplified Xpath format used for the internal bookmarks.
      static java.lang.String createXpathElement​(java.lang.String path, int index)
      Appends the provided index parameter in square brackets to the given name, like path[index].
      static java.lang.String createXpathElementCheck​(java.lang.String path, int index)
      Ensures that a provided simplified Xpath has the format title[1].
      static java.lang.String getFirstXpathElement​(java.lang.String path)
      Returns the first Xpath element from the provided path, without the index value.
      static java.lang.String getLastXpathElement​(java.lang.String path)
      Returns the last Xpath element from the provided path, without the index value.
      static java.lang.String getLastXpathElementWithIndex​(java.lang.String path)
      Returns the last Xpath element from the provided path.
      static int getSchemaVersion​(org.dom4j.Document doc)
      Helper method to get the version number from a schema's/content's XML document.
      static java.lang.String getXpathIndex​(java.lang.String path)
      Returns the last Xpath index from the given path.
      static int getXpathIndexInt​(java.lang.String path)
      Returns the last Xpath index from the given path as integer.
      static void initSystemProperties()
      Initializes XML processing system properties to avoid evaluating the XML parser and reader implementation each time an XML document is read.
      static boolean isDeepXpath​(java.lang.String path)
      Returns true if the given path is a Xpath with at least 2 elements.
      static java.io.OutputStream marshal​(org.dom4j.Document document, java.io.OutputStream out, java.lang.String encoding)
      Marshals (writes) an XML document into an output stream using XML pretty-print formatting.
      static java.lang.String marshal​(org.dom4j.Document document, java.lang.String encoding)
      Marshals (writes) an XML document to a String using XML pretty-print formatting.
      static java.lang.String marshal​(org.dom4j.Node node, java.lang.String encoding)
      Marshals (writes) an XML node into an output stream using XML pretty-print formatting.
      static java.lang.String removeAllXpathIndices​(java.lang.String path)
      Removes all Xpath indices from the given path.
      static java.lang.String removeFirstXpathElement​(java.lang.String path)
      Removes the first Xpath element from the path.
      static java.lang.String removeLastComplexXpathElement​(java.lang.String path)
      Removes the last complex Xpath element from the path.
      static java.lang.String removeLastXpathElement​(java.lang.String path)
      Removes the last Xpath element from the path.
      static java.lang.String removeXpath​(java.lang.String path)
      Removes all Xpath index information from the given input path.
      static java.lang.String removeXpathIndex​(java.lang.String path)
      Removes the last Xpath index from the given path.
      static java.lang.String simplifyXpath​(java.lang.String path)
      Simplifies an Xpath by removing a leading and a trailing slash from the given path.
      static java.util.List<java.lang.String> splitXpath​(java.lang.String xpath)
      Splits a content value path into its components, ignoring leading or trailing slashes.
      static org.dom4j.Document unmarshalHelper​(byte[] xmlData, org.xml.sax.EntityResolver resolver)
      Helper to unmarshal (read) xml contents from a byte array into a document.
      static org.dom4j.Document unmarshalHelper​(byte[] xmlData, org.xml.sax.EntityResolver resolver, boolean validate)
      Helper to unmarshal (read) xml contents from a byte array into a document.
      static org.dom4j.Document unmarshalHelper​(java.lang.String xmlData, org.xml.sax.EntityResolver resolver)
      Helper to unmarshal (read) xml contents from a String into a document.
      static org.dom4j.Document unmarshalHelper​(org.xml.sax.InputSource source, org.xml.sax.EntityResolver resolver)
      Helper to unmarshal (read) xml contents from an input source into a document.
      static org.dom4j.Document unmarshalHelper​(org.xml.sax.InputSource source, org.xml.sax.EntityResolver resolver, boolean validate)
      Helper to unmarshal (read) xml contents from an input source into a document.
      static void validateXmlStructure​(byte[] xmlData, org.xml.sax.EntityResolver resolver)
      Validates the structure of a XML document contained in a byte array with the DTD or XML schema used by the document.
      static void validateXmlStructure​(java.io.InputStream xmlStream, org.xml.sax.EntityResolver resolver)
      Validates the structure of a XML document contained in a byte array with the DTD or XML schema used by the document.
      static void validateXmlStructure​(org.dom4j.Document document, java.lang.String encoding, org.xml.sax.EntityResolver resolver)
      Validates the structure of a XML document with the DTD or XML schema used by the document.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • concatXpath

        public static java.lang.String concatXpath​(java.lang.String prefix,
                                           java.lang.String suffix)
        Concatenates two Xpath expressions, ensuring that exactly one slash "/" is between them.

        Use this method if it's uncertain if the given arguments are starting or ending with a slash "/".

        Examples:
        "title", "subtitle" becomes title/subtitle
        "title[1]/", "subtitle" becomes title[1]/subtitle
        "title[1]/", "/subtitle[1]" becomes title[1]/subtitle[1]

        Parameters:
        prefix - the prefix Xpath
        suffix - the suffix Xpath
        Returns:
        the concatenated Xpath build from prefix and suffix

      • convertDocumentFromDom4jToW3C

        public static org.w3c.dom.Document convertDocumentFromDom4jToW3C​(org.dom4j.Document doc)
                                                          throws org.dom4j.DocumentException
        Converts an org.dom4j.Document to a org.w3c.dom.Document.
        Parameters:
        doc - the document to convert
        Returns:
        the converted document
        Throws:
        org.dom4j.DocumentException

      • convertDocumentFromW3CToDom4j

        public static org.dom4j.Document convertDocumentFromW3CToDom4j​(org.w3c.dom.Document doc)
        Converts an org.w3c.dom.Document to an org.dom4j.Document.
        Parameters:
        doc - the document to convert
        Returns:
        the converted document

      • createXpath

        public static java.lang.String createXpath​(java.lang.String path,
                                           int index)
        Translates a simple lookup path to the simplified Xpath format used for the internal bookmarks.

        Examples:
        title becomes title[1]
        title[1] is left untouched
        title/subtitle becomes title[1]/subtitle[1]
        title/subtitle[1] becomes title[1]/subtitle[1]

        Note: If the name already has the format title[1] then provided index parameter is ignored.

        Parameters:
        path - the path to get the simplified Xpath for
        index - the index to append (if required)
        Returns:
        the simplified Xpath for the given name

      • createXpathElement

        public static java.lang.String createXpathElement​(java.lang.String path,
                                                  int index)
        Appends the provided index parameter in square brackets to the given name, like path[index].

        This method is used if it's clear that some path does not have a square bracket already appended.

        Parameters:
        path - the path append the index to
        index - the index to append
        Returns:
        the simplified Xpath for the given name

      • createXpathElementCheck

        public static java.lang.String createXpathElementCheck​(java.lang.String path,
                                                       int index)
        Ensures that a provided simplified Xpath has the format title[1].

        This method is used if it's uncertain if some path does have a square bracket already appended or not.

        Note: If the name already has the format title[1], then provided index parameter is ignored.

        Parameters:
        path - the path to get the simplified Xpath for
        index - the index to append (if required)
        Returns:
        the simplified Xpath for the given name

      • getFirstXpathElement

        public static java.lang.String getFirstXpathElement​(java.lang.String path)
        Returns the first Xpath element from the provided path, without the index value.

        Examples:
        title is left untouched
        title[1] becomes title
        title/subtitle becomes title
        title[1]/subtitle[1] becomes title

        Parameters:
        path - the path to get the first Xpath element from
        Returns:
        the first Xpath element from the provided path

      • getLastXpathElement

        public static java.lang.String getLastXpathElement​(java.lang.String path)
        Returns the last Xpath element from the provided path, without the index value.

        Examples:
        title is left untouched
        title[1] becomes title
        title/subtitle becomes subtitle
        title[1]/subtitle[1] becomes subtitle

        Parameters:
        path - the path to get the last Xpath element from
        Returns:
        the last Xpath element from the provided path

      • getLastXpathElementWithIndex

        public static java.lang.String getLastXpathElementWithIndex​(java.lang.String path)
        Returns the last Xpath element from the provided path. Examples:
        title is left untouched
        title[1]/subtitle[1] becomes subtitle[1]

        Parameters:
        path - the path to get the last Xpath element from
        Returns:
        the last Xpath element from the provided path

      • getSchemaVersion

        public static int getSchemaVersion​(org.dom4j.Document doc)
        Helper method to get the version number from a schema's/content's XML document.
        Parameters:
        doc - the document
        Returns:
        the version (returns 0 if no version is set)

      • getXpathIndex

        public static java.lang.String getXpathIndex​(java.lang.String path)
        Returns the last Xpath index from the given path.

        Examples:
        title returns the empty String

        title[1] returns [1]

        title/subtitle returns them empty String

        title[1]/subtitle[1] returns [1]

        Parameters:
        path - the path to extract the Xpath index from
        Returns:
        the last Xpath index from the given path

      • getXpathIndexInt

        public static int getXpathIndexInt​(java.lang.String path)
        Returns the last Xpath index from the given path as integer.

        Examples:
        title returns 1

        title[1] returns 1

        title/subtitle returns 1

        title[1]/subtitle[2] returns 2

        Parameters:
        path - the path to extract the Xpath index from
        Returns:
        the last Xpath index from the given path as integer

      • initSystemProperties

        public static void initSystemProperties()
        Initializes XML processing system properties to avoid evaluating the XML parser and reader implementation each time an XML document is read.

        This is done for performance improvements only.

      • isDeepXpath

        public static boolean isDeepXpath​(java.lang.String path)
        Returns true if the given path is a Xpath with at least 2 elements.

        Examples:
        title returns false
        title[1] returns false
        title/subtitle returns true
        title[1]/subtitle[1] returns true

        Parameters:
        path - the path to check
        Returns:
        true if the given path is a Xpath with at least 2 elements

      • marshal

        public static java.io.OutputStream marshal​(org.dom4j.Document document,
                                           java.io.OutputStream out,
                                           java.lang.String encoding)
                                    throws CmsXmlException
        Marshals (writes) an XML document into an output stream using XML pretty-print formatting.

        Parameters:
        document - the XML document to marshal
        out - the output stream to write to
        encoding - the encoding to use
        Returns:
        the output stream with the xml content
        Throws:
        CmsXmlException - if something goes wrong

      • marshal

        public static java.lang.String marshal​(org.dom4j.Document document,
                                       java.lang.String encoding)
                                throws CmsXmlException
        Marshals (writes) an XML document to a String using XML pretty-print formatting.

        Parameters:
        document - the XML document to marshal
        encoding - the encoding to use
        Returns:
        the marshalled XML document
        Throws:
        CmsXmlException - if something goes wrong

      • marshal

        public static java.lang.String marshal​(org.dom4j.Node node,
                                       java.lang.String encoding)
                                throws CmsXmlException
        Marshals (writes) an XML node into an output stream using XML pretty-print formatting.

        Parameters:
        node - the XML node to marshal
        encoding - the encoding to use
        Returns:
        the string with the xml content
        Throws:
        CmsXmlException - if something goes wrong

      • removeAllXpathIndices

        public static java.lang.String removeAllXpathIndices​(java.lang.String path)
        Removes all Xpath indices from the given path.

        Example:
        title is left untouched
        title[1] becomes title
        title/subtitle is left untouched
        title[1]/subtitle[1] becomes title/subtitle

        Parameters:
        path - the path to remove the Xpath index from
        Returns:
        the path with all Xpath indices removed

      • removeFirstXpathElement

        public static java.lang.String removeFirstXpathElement​(java.lang.String path)
        Removes the first Xpath element from the path.

        If the provided path does not contain a "/" character, it is returned unchanged.

        Examples:
        title is left untouched
        title[1] is left untouched
        title/subtitle becomes subtitle
        title[1]/subtitle[1] becomes subtitle[1]

        Parameters:
        path - the Xpath to remove the first element from
        Returns:
        the path with the first element removed

      • removeLastComplexXpathElement

        public static java.lang.String removeLastComplexXpathElement​(java.lang.String path)
        Removes the last complex Xpath element from the path.

        The same as removeLastXpathElement(String) both it works with more complex xpaths.

        Example:
        system/backup[@date='23/10/2003']/resource[path='/a/b/c'] becomes system/backup[@date='23/10/2003']

        Parameters:
        path - the Xpath to remove the last element from
        Returns:
        the path with the last element removed

      • removeLastXpathElement

        public static java.lang.String removeLastXpathElement​(java.lang.String path)
        Removes the last Xpath element from the path.

        If the provided path does not contain a "/" character, it is returned unchanged.

        Examples:
        title is left untouched
        title[1] is left untouched
        title/subtitle becomes title
        title[1]/subtitle[1] becomes title[1]

        Parameters:
        path - the Xpath to remove the last element from
        Returns:
        the path with the last element removed

      • removeXpath

        public static java.lang.String removeXpath​(java.lang.String path)
        Removes all Xpath index information from the given input path.

        Examples:
        title is left untouched
        title[1] becomes title
        title/subtitle is left untouched
        title[1]/subtitle[1] becomes title/subtitle

        Parameters:
        path - the path to remove the Xpath index information from
        Returns:
        the simplified Xpath for the given name

      • removeXpathIndex

        public static java.lang.String removeXpathIndex​(java.lang.String path)
        Removes the last Xpath index from the given path.

        Examples:
        title is left untouched
        title[1] becomes title
        title/subtitle is left untouched
        title[1]/subtitle[1] becomes title[1]/subtitle

        Parameters:
        path - the path to remove the Xpath index from
        Returns:
        the path with the last Xpath index removed

      • simplifyXpath

        public static java.lang.String simplifyXpath​(java.lang.String path)
        Simplifies an Xpath by removing a leading and a trailing slash from the given path.

        Examples:
        title/ becomes title
        /title[1]/ becomes title[1]
        /title/subtitle/ becomes title/subtitle
        /title/subtitle[1]/ becomes title/subtitle[1]

        Parameters:
        path - the path to process
        Returns:
        the input with a leading and a trailing slash removed

      • splitXpath

        public static java.util.List<java.lang.String> splitXpath​(java.lang.String xpath)
        Splits a content value path into its components, ignoring leading or trailing slashes.

        Note: this does not work for XPaths in general, only for the paths used to identify values in OpenCms contents.

        Parameters:
        xpath - the xpath
        Returns:
        the path components

      • unmarshalHelper

        public static org.dom4j.Document unmarshalHelper​(byte[] xmlData,
                                                 org.xml.sax.EntityResolver resolver)
                                          throws CmsXmlException
        Helper to unmarshal (read) xml contents from a byte array into a document.

        Using this method ensures that the OpenCms XML entity resolver is used.

        Parameters:
        xmlData - the XML data in a byte array
        resolver - the XML entity resolver to use
        Returns:
        the base object initialized with the unmarshalled XML document
        Throws:
        CmsXmlException - if something goes wrong
        See Also:
        unmarshalHelper(InputSource, EntityResolver)

      • unmarshalHelper

        public static org.dom4j.Document unmarshalHelper​(byte[] xmlData,
                                                 org.xml.sax.EntityResolver resolver,
                                                 boolean validate)
                                          throws CmsXmlException
        Helper to unmarshal (read) xml contents from a byte array into a document.

        Using this method ensures that the OpenCms XML entity resolver is used.

        Parameters:
        xmlData - the XML data in a byte array
        resolver - the XML entity resolver to use
        validate - if the reader should try to validate the xml code
        Returns:
        the base object initialized with the unmarshalled XML document
        Throws:
        CmsXmlException - if something goes wrong
        See Also:
        unmarshalHelper(InputSource, EntityResolver)

      • unmarshalHelper

        public static org.dom4j.Document unmarshalHelper​(org.xml.sax.InputSource source,
                                                 org.xml.sax.EntityResolver resolver)
                                          throws CmsXmlException
        Helper to unmarshal (read) xml contents from an input source into a document.

        Using this method ensures that the OpenCms XML entity resolver is used.

        Important: The encoding provided will NOT be used during unmarshalling, the XML parser will do this on the base of the information in the source String. The encoding is used for initializing the created instance of the document, which means it will be used when marshalling the document again later.

        Parameters:
        source - the XML input source to use
        resolver - the XML entity resolver to use
        Returns:
        the unmarshalled XML document
        Throws:
        CmsXmlException - if something goes wrong

      • unmarshalHelper

        public static org.dom4j.Document unmarshalHelper​(org.xml.sax.InputSource source,
                                                 org.xml.sax.EntityResolver resolver,
                                                 boolean validate)
                                          throws CmsXmlException
        Helper to unmarshal (read) xml contents from an input source into a document.

        Using this method ensures that the OpenCms XML entity resolver is used.

        Important: The encoding provided will NOT be used during unmarshalling, the XML parser will do this on the base of the information in the source String. The encoding is used for initializing the created instance of the document, which means it will be used when marshalling the document again later.

        Parameters:
        source - the XML input source to use
        resolver - the XML entity resolver to use
        validate - if the reader should try to validate the xml code
        Returns:
        the unmarshalled XML document
        Throws:
        CmsXmlException - if something goes wrong

      • unmarshalHelper

        public static org.dom4j.Document unmarshalHelper​(java.lang.String xmlData,
                                                 org.xml.sax.EntityResolver resolver)
                                          throws CmsXmlException
        Helper to unmarshal (read) xml contents from a String into a document.

        Using this method ensures that the OpenCms XML entitiy resolver is used.

        Parameters:
        xmlData - the xml data in a String
        resolver - the XML entity resolver to use
        Returns:
        the base object initialized with the unmarshalled XML document
        Throws:
        CmsXmlException - if something goes wrong
        See Also:
        unmarshalHelper(InputSource, EntityResolver)

      • validateXmlStructure

        public static void validateXmlStructure​(byte[] xmlData,
                                        org.xml.sax.EntityResolver resolver)
                                 throws CmsXmlException
        Validates the structure of a XML document contained in a byte array with the DTD or XML schema used by the document.

        Parameters:
        xmlData - a byte array containing a XML document that should be validated
        resolver - the XML entity resolver to use
        Throws:
        CmsXmlException - if the validation fails

      • validateXmlStructure

        public static void validateXmlStructure​(org.dom4j.Document document,
                                        java.lang.String encoding,
                                        org.xml.sax.EntityResolver resolver)
                                 throws CmsXmlException
        Validates the structure of a XML document with the DTD or XML schema used by the document.

        Parameters:
        document - a XML document that should be validated
        encoding - the encoding to use when marshalling the XML document (required)
        resolver - the XML entity resolver to use
        Throws:
        CmsXmlException - if the validation fails

      • validateXmlStructure

        public static void validateXmlStructure​(java.io.InputStream xmlStream,
                                        org.xml.sax.EntityResolver resolver)
                                 throws CmsXmlException
        Validates the structure of a XML document contained in a byte array with the DTD or XML schema used by the document.

        Parameters:
        xmlStream - a source providing a XML document that should be validated
        resolver - the XML entity resolver to use
        Throws:
        CmsXmlException - if the validation fails