CmsXmlUtils (OpenCms Core API, version 11.0.0)

java.lang.Object
- org.opencms.xml.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 and 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 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`	`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(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 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 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(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.
`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.

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

Class CmsXmlUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

concatXpath

createXpath

createXpathElement

createXpathElementCheck

getFirstXpathElement

getLastXpathElement

getXpathIndex

getXpathIndexInt

initSystemProperties

isDeepXpath

marshal

marshal

marshal

removeAllXpathIndices

removeFirstXpathElement

removeLastComplexXpathElement

removeLastXpathElement

removeXpath

removeXpathIndex

simplifyXpath

splitXpath

unmarshalHelper

unmarshalHelper

unmarshalHelper

unmarshalHelper

unmarshalHelper

validateXmlStructure

validateXmlStructure

validateXmlStructure