org.opencms.xml
Class A_CmsXmlDocument

java.lang.Object
  org.opencms.xml.A_CmsXmlDocument

All Implemented Interfaces:

I_CmsXmlDocument

Direct Known Subclasses:

CmsXmlContent, CmsXmlPage

public abstract class A_CmsXmlDocument
extends java.lang.Object
implements I_CmsXmlDocument

Provides basic XML document handling functions useful when dealing with XML documents that are stored in the OpenCms VFS.

Since:

6.0.0

Version:

$Revision: 1.44 $

Author:

Alexander Kandzior

Field Summary

protected java.lang.String	m_conversion The content conversion to use for this XML document.
protected org.dom4j.Document	m_document The document object of the document.
protected java.util.Map<java.lang.String,java.util.Set<java.util.Locale>>	m_elementLocales Maps element names to available locales.
protected java.util.Map<java.util.Locale,java.util.Set<java.lang.String>>	m_elementNames Maps locales to available element names.
protected java.lang.String	m_encoding The encoding to use for this XML document.
protected CmsFile	m_file The file that contains the document data (note: is not set when creating an empty or document based document).
protected java.util.Set<java.util.Locale>	m_locales Set of locales contained in this document.

Constructor Summary

protected

A_CmsXmlDocument() Default constructor for a XML document that initializes some internal values.

Method Summary

protected void	addBookmark(java.lang.String path, java.util.Locale locale, boolean enabled, I_CmsXmlContentValue value) Adds a bookmark for the given value.
protected void	addLocale(java.util.Locale locale) Adds a locale to the set of locales of the XML document.
protected void	clearBookmarks() Clears the XML document bookmarks.
void	copyLocale(java.util.List<java.util.Locale> possibleSources, java.util.Locale destination) Copies the content from the first matching source locale that exists in this XML document to the given destination locale in this XML document.
void	copyLocale(java.util.Locale source, java.util.Locale destination) Copies the content of the given source locale to the given destination locale in this XML document.
CmsFile	correctXmlStructure(CmsObject cms) Corrects the structure of this XML document.
protected org.dom4j.Element	createDeepElementCopy(org.dom4j.Element element, java.util.Set<java.lang.String> copyElements) Creates a partial deep element copy according to the set of element paths.
protected I_CmsXmlContentValue	getBookmark(java.lang.String bookmark) Returns the bookmarked value for the given bookmark, which must be a valid bookmark name.
protected I_CmsXmlContentValue	getBookmark(java.lang.String path, java.util.Locale locale) Returns the bookmarked value for the given name.
protected static java.lang.String	getBookmarkName(java.lang.String name, java.util.Locale locale) Creates the bookmark name for a localized element to be used in the bookmark lookup table.
protected java.util.Set<java.lang.String>	getBookmarks() Returns the names of all bookmarked elements.
java.lang.String	getConversion() Returns the content conversion parameter used for this XML document.
java.lang.String	getEncoding() Returns the encoding used for this XML document.
CmsFile	getFile() Returns the file this document was generated from, may be null if the file not available.
int	getIndexCount(java.lang.String path, java.util.Locale locale) Returns the index count of existing values for the given path, or -1 if no such path exists.
java.util.List<java.util.Locale>	getLocales() Returns a List of all locales that have at last one value in this XML document.
java.util.List<java.util.Locale>	getLocales(java.lang.String path) Returns a List of all locales that have the named element set in this document.
java.util.List<java.lang.String>	getNames(java.util.Locale locale) Returns a List of all available elements paths (Strings) used in this document for the given locale.
java.lang.String	getStringValue(CmsObject cms, java.lang.String path, java.util.Locale locale) Returns the first content value for the given path as a String, or null if no such value exists.
java.lang.String	getStringValue(CmsObject cms, java.lang.String path, java.util.Locale locale, int index) Returns the content value for the given path and the selected index as a String, or null if no such value exists.
I_CmsXmlContentValue	getValue(java.lang.String path, java.util.Locale locale) Returns the content value Object for the given path, or null if no such value exists.
I_CmsXmlContentValue	getValue(java.lang.String path, java.util.Locale locale, int index) Returns the content value Object for the given path and the selected index, or null if no such value exists.
java.util.List<I_CmsXmlContentValue>	getValues(java.util.Locale locale) Returns all available content values (of type I_CmsXmlContentValue) in this document for the given locale.
java.util.List<I_CmsXmlContentValue>	getValues(java.lang.String path, java.util.Locale locale) Returns all content values (of type I_CmsXmlContentValue) with the given path available in this document for the given locale.
boolean	hasLocale(java.util.Locale locale) Returns true if the given locale exists in this XML document.
boolean	hasValue(java.lang.String path, java.util.Locale locale) Returns true if a value with the given path exists for the selected locale in this XML document, or false otherwise.
boolean	hasValue(java.lang.String path, java.util.Locale locale, int index) Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, or false otherwise.
void	initDocument() Initializes this XML document, required after structural changes to the internal XML.
protected abstract void	initDocument(org.dom4j.Document document, java.lang.String encoding, CmsXmlContentDefinition contentDefinition) Initializes an XML document based on the provided document, encoding and content definition.
protected boolean	isAutoCorrectionEnabled() Returns true if the auto correction feature is enabled for saving this XML content.
boolean	isEnabled(java.lang.String path, java.util.Locale locale) Returns true if a value with the given path exists for the selected locale in this XML document, and that value is enabled, or false otherwise.
boolean	isEnabled(java.lang.String path, java.util.Locale locale, int index) Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled, or false otherwise.
byte[]	marshal() Marshals (writes) the content of the current XML document into a byte array using the selected encoding.
protected java.io.OutputStream	marshal(java.io.OutputStream out, java.lang.String encoding) Marshals (writes) the content of the current XML document into an output stream.
void	moveLocale(java.util.Locale source, java.util.Locale destination) Moves the content of the given source locale to the given destination locale in this XML document.
protected I_CmsXmlContentValue	removeBookmark(java.lang.String path, java.util.Locale locale) Removes the bookmark for an element with the given name and locale.
void	removeLocale(java.util.Locale locale) Removes the given locale from this XML document.
void	setConversion(java.lang.String conversion) Sets the content conversion mode for this document.
java.lang.String	toString()
void	validateXmlStructure(org.xml.sax.EntityResolver resolver) Validates the XML structure of the 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, wait, wait, wait

Methods inherited from interface org.opencms.xml.I_CmsXmlDocument

addLocale, getContentDefinition, getLinkProcessor, validate

Field Detail

m_conversion

protected java.lang.String m_conversion

The content conversion to use for this XML document.

m_document

protected org.dom4j.Document m_document

The document object of the document.

m_elementLocales

protected java.util.Map<java.lang.String,java.util.Set<java.util.Locale>> m_elementLocales

Maps element names to available locales.

m_elementNames

protected java.util.Map<java.util.Locale,java.util.Set<java.lang.String>> m_elementNames

Maps locales to available element names.

m_encoding

protected java.lang.String m_encoding

The encoding to use for this XML document.

m_file

protected CmsFile m_file

The file that contains the document data (note: is not set when creating an empty or document based document).

m_locales

protected java.util.Set<java.util.Locale> m_locales

Set of locales contained in this document.

Constructor Detail

A_CmsXmlDocument

protected A_CmsXmlDocument()

Default constructor for a XML document that initializes some internal values.

Method Detail

getBookmarkName

protected static final java.lang.String getBookmarkName(java.lang.String name,
                                                        java.util.Locale locale)

Creates the bookmark name for a localized element to be used in the bookmark lookup table.

Parameters:

name - the element name

locale - the element locale

Returns:

the bookmark name for a localized element

copyLocale

public void copyLocale(java.util.List<java.util.Locale> possibleSources,
                       java.util.Locale destination)
                throws CmsXmlException

Description copied from interface: I_CmsXmlDocument

Copies the content from the first matching source locale that exists in this XML document to the given destination locale in this XML document.

The list of possible sources, has to be sorted in order of preference. The first match that exists in this XML document is used as source for the destination locale. No "locale simplification" ("en_EN" to "en" etc.) is performed for the match.

Specified by:

copyLocale in interface I_CmsXmlDocument

Parameters:

possibleSources - the possible source locales in order of preference, must contain objects of type Locale

destination - the destination locale

Throws:

CmsXmlException - in case non of the source locales did not exist, or the destination locale already exists in the document, or if something else goes wrong

See Also:

I_CmsXmlDocument.copyLocale(java.util.List, java.util.Locale)

copyLocale

public void copyLocale(java.util.Locale source,
                       java.util.Locale destination)
                throws CmsXmlException

Description copied from interface: I_CmsXmlDocument

Copies the content of the given source locale to the given destination locale in this XML document.

Specified by:

copyLocale in interface I_CmsXmlDocument

Parameters:

source - the source locale

destination - the destination locale

Throws:

CmsXmlException - in case either the source locale did not exist, or the destination locale already exists in the document, or if something else goes wrong

See Also:

I_CmsXmlDocument.copyLocale(java.util.Locale, java.util.Locale)

correctXmlStructure

public CmsFile correctXmlStructure(CmsObject cms)
                            throws CmsXmlException

Corrects the structure of this XML document.

Parameters:

cms - the current OpenCms user context

Returns:

the file that contains the corrected XML structure

Throws:

CmsXmlException - if something goes wrong

getConversion

public java.lang.String getConversion()

Description copied from interface: I_CmsXmlDocument

Returns the content conversion parameter used for this XML document.

Specified by:

getConversion in interface I_CmsXmlDocument

Returns:

the content conversion parameter used for this XML document

See Also:

I_CmsXmlDocument.getConversion()

getEncoding

public java.lang.String getEncoding()

Description copied from interface: I_CmsXmlDocument

Returns the encoding used for this XML document.

Specified by:

getEncoding in interface I_CmsXmlDocument

Returns:

the encoding used for this XML document

See Also:

I_CmsXmlDocument.getEncoding()

getFile

public CmsFile getFile()

Description copied from interface: I_CmsXmlDocument

Returns the file this document was generated from, may be null if the file not available.

The file may not be available if the document was generated from a String or a pure XML document.

Specified by:

getFile in interface I_CmsXmlDocument

Returns:

the file this document was generated from

See Also:

I_CmsXmlDocument.getFile()

getIndexCount

public int getIndexCount(java.lang.String path,
                         java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns the index count of existing values for the given path, or -1 if no such path exists.

Specified by:

getIndexCount in interface I_CmsXmlDocument

Parameters:

path - the path to get the index count for

locale - the locale to get the index count for

Returns:

the index count for the given key name

See Also:

I_CmsXmlDocument.getIndexCount(java.lang.String, java.util.Locale)

getLocales

public java.util.List<java.util.Locale> getLocales()

Description copied from interface: I_CmsXmlDocument

Returns a List of all locales that have at last one value in this XML document.

Specified by:

getLocales in interface I_CmsXmlDocument

Returns:

a List of all locales that have at last one value in this XML document

See Also:

I_CmsXmlDocument.getLocales()

getLocales

public java.util.List<java.util.Locale> getLocales(java.lang.String path)

Returns a List of all locales that have the named element set in this document.

If no locale for the given element name is available, an empty list is returned.

Specified by:

getLocales in interface I_CmsXmlDocument

Parameters:

path - the element to look up the locale List for

Returns:

a List of all Locales that have the named element set in this document

getNames

public java.util.List<java.lang.String> getNames(java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns a List of all available elements paths (Strings) used in this document for the given locale.

If no element for the given locale is available, an empty list is returned.

Specified by:

getNames in interface I_CmsXmlDocument

Parameters:

locale - the locale to look up the elements paths for

Returns:

a List of all available elements paths (Strings) used in this document for the given locale

See Also:

I_CmsXmlDocument.getNames(java.util.Locale)

getStringValue

public java.lang.String getStringValue(CmsObject cms,
                                       java.lang.String path,
                                       java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns the first content value for the given path as a String, or null if no such value exists.

Specified by:

getStringValue in interface I_CmsXmlDocument

Parameters:

cms - the current OpenCms user context

path - the path to get the content value for

locale - the locale to get the content value for

Returns:

the first content value for the given path as a String

See Also:

I_CmsXmlDocument.getStringValue(org.opencms.file.CmsObject, java.lang.String, java.util.Locale)

getStringValue

public java.lang.String getStringValue(CmsObject cms,
                                       java.lang.String path,
                                       java.util.Locale locale,
                                       int index)

Description copied from interface: I_CmsXmlDocument

Returns the content value for the given path and the selected index as a String, or null if no such value exists.

Specified by:

getStringValue in interface I_CmsXmlDocument

Parameters:

cms - the current OpenCms user context

path - the path to get the content value for

locale - the locale to get the content value for

index - the index position to get the value from

Returns:

the content value for the given path and the selected index as a String

See Also:

I_CmsXmlDocument.getStringValue(CmsObject, java.lang.String, Locale, int)

getValue

public I_CmsXmlContentValue getValue(java.lang.String path,
                                     java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns the content value Object for the given path, or null if no such value exists.

You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

Specified by:

getValue in interface I_CmsXmlDocument

Parameters:

path - the path to get the content value for

locale - the locale to get the content value for

Returns:

the content value Object for the given path

See Also:

I_CmsXmlDocument.getValue(java.lang.String, java.util.Locale)

getValue

public I_CmsXmlContentValue getValue(java.lang.String path,
                                     java.util.Locale locale,
                                     int index)

Description copied from interface: I_CmsXmlDocument

Returns the content value Object for the given path and the selected index, or null if no such value exists.

Specified by:

getValue in interface I_CmsXmlDocument

Parameters:

path - the path to get the content value for

locale - the locale to get the content value for

index - the index position to get the value from

Returns:

the content value Object for the given path and the selected index

See Also:

I_CmsXmlDocument.getValue(java.lang.String, java.util.Locale, int)

getValues

public java.util.List<I_CmsXmlContentValue> getValues(java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns all available content values (of type I_CmsXmlContentValue) in this document for the given locale.

If no content value for the given locale is available, an empty list is returned.

Specified by:

getValues in interface I_CmsXmlDocument

Parameters:

locale - the locale to get the content values for

Returns:

all available content values (of type I_CmsXmlContentValue) in this document for the given locale

See Also:

I_CmsXmlDocument.getValues(java.util.Locale)

getValues

public java.util.List<I_CmsXmlContentValue> getValues(java.lang.String path,
                                                      java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns all content values (of type I_CmsXmlContentValue) with the given path available in this document for the given locale.

If no content value for the given path is available with this locale, an empty list is returned.

Specified by:

getValues in interface I_CmsXmlDocument

Parameters:

path - the path to get the content values for

locale - the locale to get the content values for

Returns:

all content values (of type I_CmsXmlContentValue) with the given path available in this document for the given locale

See Also:

I_CmsXmlDocument.getValues(java.lang.String, java.util.Locale)

hasLocale

public boolean hasLocale(java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns true if the given locale exists in this XML document.

Specified by:

hasLocale in interface I_CmsXmlDocument

Parameters:

locale - the locale to check

Returns:

true if the given locale exists in this XML document, false otherwise

See Also:

I_CmsXmlDocument.hasLocale(java.util.Locale)

hasValue

public boolean hasValue(java.lang.String path,
                        java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns true if a value with the given path exists for the selected locale in this XML document, or false otherwise.

You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

Specified by:

hasValue in interface I_CmsXmlDocument

Parameters:

path - the path to check

locale - the locale to check

Returns:

true if a value with the given path exists for the selected locale in this XML document

See Also:

I_CmsXmlDocument.hasValue(java.lang.String, java.util.Locale)

hasValue

public boolean hasValue(java.lang.String path,
                        java.util.Locale locale,
                        int index)

Description copied from interface: I_CmsXmlDocument

Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, or false otherwise.

Specified by:

hasValue in interface I_CmsXmlDocument

Parameters:

path - the path to check

locale - the locale to check

index - the index position to check

Returns:

true if a value with the given path and the provided index exists for the selected locale in this XML document

See Also:

I_CmsXmlDocument.hasValue(java.lang.String, java.util.Locale, int)

initDocument

public void initDocument()

Description copied from interface: I_CmsXmlDocument

Initializes this XML document, required after structural changes to the internal XML.

If nodes in the XML are added, removed or moved, the document needs to be initialized in order to update the internal data structures.

Specified by:

initDocument in interface I_CmsXmlDocument

See Also:

I_CmsXmlDocument.initDocument()

isEnabled

public boolean isEnabled(java.lang.String path,
                         java.util.Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns true if a value with the given path exists for the selected locale in this XML document, and that value is enabled, or false otherwise.

This is only used with implementations that support enabling and disabling individual values, such as CmsXmlPage. If enabling / disabling values is not supported, this is identical to I_CmsXmlDocument.hasValue(String, Locale).

You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

Specified by:

isEnabled in interface I_CmsXmlDocument

Parameters:

path - the path to check

locale - the locale to check

Returns:

true if a value with the given path exists for the selected locale in this XML document, and that value is enabled

See Also:

I_CmsXmlDocument.isEnabled(java.lang.String, java.util.Locale)

isEnabled

public boolean isEnabled(java.lang.String path,
                         java.util.Locale locale,
                         int index)

Description copied from interface: I_CmsXmlDocument

Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled, or false otherwise.

This is only used with implementations that support enabling and disabling individual values, such as CmsXmlPage. If enabling / disabling values is not supported, this is identical to I_CmsXmlDocument.hasValue(String, Locale, int).

Specified by:

isEnabled in interface I_CmsXmlDocument

Parameters:

path - the path to check

locale - the locale to check

index - the index position to check

Returns:

true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled

See Also:

I_CmsXmlDocument.isEnabled(java.lang.String, java.util.Locale, int)

marshal

public byte[] marshal()
               throws CmsXmlException

Marshals (writes) the content of the current XML document into a byte array using the selected encoding.

Returns:

the content of the current XML document written into a byte array

Throws:

CmsXmlException - if something goes wrong

moveLocale

public void moveLocale(java.util.Locale source,
                       java.util.Locale destination)
                throws CmsXmlException

Description copied from interface: I_CmsXmlDocument

Moves the content of the given source locale to the given destination locale in this XML document.

Specified by:

moveLocale in interface I_CmsXmlDocument

Parameters:

source - the source locale

destination - the destination locale

Throws:

CmsXmlException - in case either the source locale does not exist, or the destination locale already exists in the document, or if something else goes wrong

See Also:

I_CmsXmlDocument.moveLocale(java.util.Locale, java.util.Locale)

removeLocale

public void removeLocale(java.util.Locale locale)
                  throws CmsXmlException

Description copied from interface: I_CmsXmlDocument

Removes the given locale from this XML document.

Specified by:

removeLocale in interface I_CmsXmlDocument

Parameters:

locale - the locale to remove

Throws:

CmsXmlException - in case the locale did not exist in the document, or if something else goes wrong

See Also:

I_CmsXmlDocument.removeLocale(java.util.Locale)

setConversion

public void setConversion(java.lang.String conversion)

Sets the content conversion mode for this document.

Parameters:

conversion - the conversion mode to set for this document

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

validateXmlStructure

public void validateXmlStructure(org.xml.sax.EntityResolver resolver)
                          throws CmsXmlException

Validates the XML structure of the document with the DTD or XML schema used by the document.

This is required in case someone modifies the XML structure of a document using the "edit control code" option.

Parameters:

resolver - the XML entity resolver to use

Throws:

CmsXmlException - if the validation fails

addBookmark

protected void addBookmark(java.lang.String path,
                           java.util.Locale locale,
                           boolean enabled,
                           I_CmsXmlContentValue value)

Adds a bookmark for the given value.

Parameters:

path - the lookup path to use for the bookmark

locale - the locale to use for the bookmark

enabled - if true, the value is enabled, if false it is disabled

value - the value to bookmark

addLocale

protected void addLocale(java.util.Locale locale)

Adds a locale to the set of locales of the XML document.

Parameters:

locale - the locale to add

clearBookmarks

protected void clearBookmarks()

Clears the XML document bookmarks.

createDeepElementCopy

protected org.dom4j.Element createDeepElementCopy(org.dom4j.Element element,
                                                  java.util.Set<java.lang.String> copyElements)

Creates a partial deep element copy according to the set of element paths.

Only elements contained in that set will be copied.

Parameters:

element - the element to copy

copyElements - the set of paths for elements to copy

Returns:

a partial deep copy of element

getBookmark

protected I_CmsXmlContentValue getBookmark(java.lang.String bookmark)

Returns the bookmarked value for the given bookmark, which must be a valid bookmark name. Use getBookmarks() to get the list of all valid bookmark names.

Parameters:

bookmark - the bookmark name to look up

Returns:

the bookmarked value for the given bookmark

getBookmark

protected I_CmsXmlContentValue getBookmark(java.lang.String path,
                                           java.util.Locale locale)

Returns the bookmarked value for the given name.

Parameters:

path - the lookup path to use for the bookmark

locale - the locale to get the bookmark for

Returns:

the bookmarked value

getBookmarks

protected java.util.Set<java.lang.String> getBookmarks()

Returns the names of all bookmarked elements.

Returns:

the names of all bookmarked elements

initDocument

protected abstract void initDocument(org.dom4j.Document document,
                                     java.lang.String encoding,
                                     CmsXmlContentDefinition contentDefinition)

Initializes an XML document based on the provided document, encoding and content definition.

Parameters:

document - the base XML document to use for initializing

encoding - the encoding to use when marshalling the document later

contentDefinition - the content definition to use

isAutoCorrectionEnabled

protected boolean isAutoCorrectionEnabled()

Returns true if the auto correction feature is enabled for saving this XML content.

Returns:

true if the auto correction feature is enabled for saving this XML content

marshal

protected java.io.OutputStream marshal(java.io.OutputStream out,
                                       java.lang.String encoding)
                                throws CmsXmlException

Marshals (writes) the content of the current XML document into an output stream.

Parameters:

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

removeBookmark

protected I_CmsXmlContentValue removeBookmark(java.lang.String path,
                                              java.util.Locale locale)

Removes the bookmark for an element with the given name and locale.

Parameters:

path - the lookup path to use for the bookmark

locale - the locale of the element

Returns:

the element removed from the bookmarks or null