Package org.opencms.xml

Class CmsXmlUtils

java.lang.Object
org.opencms.xml.CmsXmlUtils
public final class CmsXmlUtils extends Object
Provides some basic XML handling utilities.

Since:
6.0.0

  • Method Details

    • concatXpath

      public static String concatXpath(String prefix, 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 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(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 String createXpath(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 String createXpathElement(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 String createXpathElementCheck(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 String getFirstXpathElement(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 String getLastXpathElement(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 String getLastXpathElementWithIndex(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 String getXpathIndex(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(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(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 OutputStream marshal(org.dom4j.Document document, OutputStream out, 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 String marshal(org.dom4j.Document document, 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 String marshal(org.dom4j.Node node, 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 String removeAllXpathIndices(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 String removeFirstXpathElement(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 String removeLastComplexXpathElement(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 String removeLastXpathElement(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 String removeXpath(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 String removeXpathIndex(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 String simplifyXpath(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 List<String> splitXpath(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, 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

      public static org.dom4j.Document unmarshalHelper(byte[] xmlData, 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

      public static org.dom4j.Document unmarshalHelper(InputSource source, 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(InputSource source, 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(String xmlData, 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:

    • validateXmlStructure

      public static void validateXmlStructure(byte[] xmlData, 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, String encoding, 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(InputStream xmlStream, 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