org.opencms.xml
Interface I_CmsXmlDocument

All Known Implementing Classes:

A_CmsXmlDocument, CmsXmlContent, CmsXmlPage

public interface I_CmsXmlDocument

Describes the API to access the values of a XML content document.

Since:

6.0.0

Version:

$Revision: 1.24 $

Author:

Alexander Kandzior

Method Summary

void	addLocale(CmsObject cms, java.util.Locale locale) Adds the given locale to this XML document.
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.
CmsXmlContentDefinition	getContentDefinition() Returns the content definition object used for this XML document.
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.
CmsLinkProcessor	getLinkProcessor(CmsObject cms, CmsLinkTable linkTable) Returns a link processor for the values of this XML document.
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 at least one element with the given path in this XML 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.
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.
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.
void	removeLocale(java.util.Locale locale) Removes the given locale from this XML document.
CmsXmlContentErrorHandler	validate(CmsObject cms) Validates the content of this XML document.

Method Detail

addLocale

void addLocale(CmsObject cms,
               java.util.Locale locale)
               throws CmsXmlException

Adds the given locale to this XML document.

Parameters:

cms - the current users OpenCms context

locale - the locale to add

Throws:

CmsXmlException - in case the locale already existed, or if something else goes wrong

copyLocale

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

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.

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

copyLocale

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

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

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

getContentDefinition

CmsXmlContentDefinition getContentDefinition()

Returns the content definition object used for this XML document.

Returns:

the content definition object used for this XML document

getConversion

java.lang.String getConversion()

Returns the content conversion parameter used for this XML document.

Returns:

the content conversion parameter used for this XML document

getEncoding

java.lang.String getEncoding()

Returns the encoding used for this XML document.

Returns:

the encoding used for this XML document

getFile

CmsFile getFile()

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.

Returns:

the file this document was generated from

getIndexCount

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.

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

getLinkProcessor

CmsLinkProcessor getLinkProcessor(CmsObject cms,
                                  CmsLinkTable linkTable)

Returns a link processor for the values of this XML document.

Parameters:

cms - the current OpenCms user context that provides access to the link processor

linkTable - the table with the links to process

Returns:

a link processor for the values of this XML document

getLocales

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

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

Returns:

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

getLocales

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

Returns a List of all locales that have at least one element with the given path in this XML document.

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

Parameters:

path - the path to look up the locale List for

Returns:

a List of all locales that have at least one element with the given path in this XML document

getNames

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.

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

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:

getValues(Locale)

getStringValue

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

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

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

Throws:

CmsXmlException - if something goes wrong

getStringValue

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

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

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

Throws:

CmsXmlException - if something goes wrong

getValue

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.

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.

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

getValue

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.

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

getValues

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.

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

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:

getNames(Locale)

getValues

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.

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

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

hasLocale

boolean hasLocale(java.util.Locale locale)

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

Parameters:

locale - the locale to check

Returns:

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

hasValue

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.

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.

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

hasValue

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.

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

initDocument

void initDocument()

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.

isEnabled

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.

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

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

isEnabled

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.

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 hasValue(String, Locale, int).

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

moveLocale

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

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

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

removeLocale

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

Removes the given locale from this XML document.

Parameters:

locale - the locale to remove

Throws:

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

validate

CmsXmlContentErrorHandler validate(CmsObject cms)

Validates the content of this XML document.

To check for errors in a single document locale only, use CmsXmlContentErrorHandler.hasErrors(Locale) in the result object.

Parameters:

cms - the current OpenCms user context

Returns:

an error handler instance that provides information about the errors or warnings that have been found