org.opencms.xml
Class CmsXmlUtils

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

Version:

$Revision: 1.31 $

Author:

Alexander Kandzior

Method Summary

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 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	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 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 them empty String

title[1] returns [1]

title/subtitle returns them empty String

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

Parameters:

path - the path to remove the Xpath index from

Returns:

the path with the last Xpath from the given path

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

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

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