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

Author:

Alexander Kandzior

Field Summary

protected String	m_conversion The content conversion to use for this xml document.
protected Document	m_document The document object of the document.
protected Map	m_elementLocales Maps element names to available locales.
protected Map	m_elementNames Maps locales to avaliable element names.
protected 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 Set	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(String name, Locale locale, boolean enabled, Object value) Adds a bookmark for the given value.
protected void	addLocale(Locale locale) Adds a locale to the set of locales of the XML document.
protected void	clearBookmarks() Clears the XML document bookmarks.
void	copyLocale(Locale source, 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 content.
protected Object	getBookmark(String bookmark) Returns the bookmarked value for the given bookmark, which must be a valid bookmark name.
protected Object	getBookmark(String name, Locale locale) Returns the bookmarked value for the given name.
protected static String	getBookmarkName(String name, Locale locale) Creates the bookmark name for a localized element to be used in the bookmark lookup table.
protected Set	getBookmarks() Returns the names of all bookmarked elements.
String	getConversion() Returns the content converison used for the page content.
String	getEncoding() Returns the encoding used for this XML document.
CmsFile	getFile() Returns the file with the xml page content or null if not set.
int	getIndexCount(String name, Locale locale) Returns the index count of existing values for the given key name, or -1 if no such value exists.
List	getLocales() Returns a List of all locales that have at last one element in this XML document.
List	getLocales(String name) Returns a List of all locales that have the named element set in this document.
List	getNames(Locale locale) Returns all available elements names used in this document for the given locale.
String	getStringValue(CmsObject cms, String name, Locale locale) Returns the first content value for the given key name as a String, or null if no such value exists.
String	getStringValue(CmsObject cms, String name, Locale locale, int index) Returns the content value for the given key name from the selected index as a String, or null if no such value exists.
I_CmsXmlContentValue	getValue(String name, Locale locale) Returns the content value Object for the given key name, or null if no such value exists.
I_CmsXmlContentValue	getValue(String name, Locale locale, int index) Returns the content value Object for the given key name from the selected index, or null if no such value exists.
List	getValues(Locale locale) Returns all available elements values used in this document for the given locale.
List	getValues(String name, Locale locale) Returns all content value Objects for the given key name in a List, or null if no such value exists.
boolean	hasLocale(Locale locale) Checks if the given locale exists in this XML document.
boolean	hasValue(String name, Locale locale) Returns true if a value exists with the given key name, false otherwise.
boolean	hasValue(String name, Locale locale, int index) Returns true if a value exists with the given key name at the selected index, false otherwise.
void	initDocument() Initializes this XML document, required after structural changes to the XML.
protected abstract void	initDocument(Document document, String encoding, CmsXmlContentDefinition contentDefinition) Initializes an XML document based on the provided document, encoding and content definition.
boolean	isEnabled(String name, Locale locale) Returns true if a value exists with the given key name, and that value is enabled, false otherwise.
boolean	isEnabled(String name, Locale locale, int index) Returns true if a value exists with the given key name at the selected index, and that value is enabled, false otherwise.
byte[]	marshal() Marshals (writes) the content of the current XML document into a byte array using the selected encoding.
protected OutputStream	marshal(OutputStream out, String encoding) Marshals (writes) the content of the current XML document into an output stream.
void	moveLocale(Locale source, Locale destination) Moves the content of the given source locale to the given destination locale in this XML document.
protected I_CmsXmlContentValue	removeBookmark(String name, Locale locale) Removes the bookmark for an element with the given name and locale.
void	removeLocale(Locale locale) Removes the given locale from this XML document.
void	setConversion(String conversion) Sets the content conversion mode for this document.
String	toString()
void	validateXmlStructure(EntityResolver resolver) Validates the xml structure of the document with the DTD ot 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 String m_conversion

The content conversion to use for this xml document.

m_document

protected Document m_document

The document object of the document.

m_elementLocales

protected Map m_elementLocales

Maps element names to available locales.

m_elementNames

protected Map m_elementNames

Maps locales to avaliable element names.

m_encoding

protected 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 Set 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 String getBookmarkName(String name,
                                              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(Locale source,
                       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 content.

Parameters:

cms - the current cms object

Returns:

the file that contains the corrected XML structure

Throws:

CmsXmlException - if something goes wrong

getConversion

public String getConversion()

Returns the content converison used for the page content.

Specified by:

getConversion in interface I_CmsXmlDocument

Returns:

the content converison used for the page content

getEncoding

public 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()

Returns the file with the xml page content or null if not set.

Specified by:

getFile in interface I_CmsXmlDocument

Returns:

the file with the xml page content

getIndexCount

public int getIndexCount(String name,
                         Locale locale)

Description copied from interface: I_CmsXmlDocument

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

Specified by:

getIndexCount in interface I_CmsXmlDocument

Parameters:

name - the key 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 List getLocales()

Description copied from interface: I_CmsXmlDocument

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

Specified by:

getLocales in interface I_CmsXmlDocument

Returns:

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

See Also:

I_CmsXmlDocument.getLocales()

getLocales

public List getLocales(String name)

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:

name - 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 List getNames(Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns all available elements names 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

Returns:

list of available element names (Strings)

See Also:

I_CmsXmlDocument.getNames(java.util.Locale)

getStringValue

public String getStringValue(CmsObject cms,
                             String name,
                             Locale locale)

Description copied from interface: I_CmsXmlDocument

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

.

Specified by:

getStringValue in interface I_CmsXmlDocument

Parameters:

cms - the current OpenCms user context

name - the key to get the content value for

locale - the locale to get the content value for

Returns:

the content value for the given key name

See Also:

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

getStringValue

public String getStringValue(CmsObject cms,
                             String name,
                             Locale locale,
                             int index)

Description copied from interface: I_CmsXmlDocument

Returns the content value for the given key name from 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

name - the key 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 key name

See Also:

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

getValue

public I_CmsXmlContentValue getValue(String name,
                                     Locale locale)

Description copied from interface: I_CmsXmlDocument

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

.

You can provide an index for the value by appending a numer in aquare brackets to the name parameter like this "Title[1]". If no index is provided, 0 is used for the index position.

Specified by:

getValue in interface I_CmsXmlDocument

Parameters:

name - the key to get the content value for

locale - the locale to get the content value for

Returns:

the content value for the given key name

See Also:

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

getValue

public I_CmsXmlContentValue getValue(String name,
                                     Locale locale,
                                     int index)

Description copied from interface: I_CmsXmlDocument

Returns the content value Object for the given key name from the selected index, or null if no such value exists.

Specified by:

getValue in interface I_CmsXmlDocument

Parameters:

name - the key 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 key name

See Also:

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

getValues

public List getValues(Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns all available elements values used in this document for the given locale.

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

Specified by:

getValues in interface I_CmsXmlDocument

Parameters:

locale - the locale

Returns:

list of available element valies (type I_CmsXmlContentValue)

See Also:

I_CmsXmlDocument.getValues(java.util.Locale)

getValues

public List getValues(String name,
                      Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns all content value Objects for the given key name in a List, or null if no such value exists.

Specified by:

getValues in interface I_CmsXmlDocument

Parameters:

name - the key to get the content values for

locale - the locale to get the content values for

Returns:

the content value for the given key name

See Also:

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

hasLocale

public boolean hasLocale(Locale locale)

Description copied from interface: I_CmsXmlDocument

Checks 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(String name,
                        Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns true if a value exists with the given key name, false otherwise.

You can provide an index for the value by appending a numer in aquare brackets to the name parameter like this "Title[1]". If no index is provided, 0 is used for the index position.

Specified by:

hasValue in interface I_CmsXmlDocument

Parameters:

name - the key to check

locale - the locale to check

Returns:

true if a value exists with the given key name, false otherwise

See Also:

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

hasValue

public boolean hasValue(String name,
                        Locale locale,
                        int index)

Description copied from interface: I_CmsXmlDocument

Returns true if a value exists with the given key name at the selected index, false otherwise.

Specified by:

hasValue in interface I_CmsXmlDocument

Parameters:

name - the key to check

locale - the locale to check

index - the index position to check

Returns:

true if a value exists with the given key name at the selected index, false otherwise

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 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(String name,
                         Locale locale)

Description copied from interface: I_CmsXmlDocument

Returns true if a value exists with the given key name, and that value is enabled, false otherwise.

You can provide an index for the value by appending a numer in aquare brackets to the name parameter like this "Title[1]". If no index is provided, 0 is used for the index position.

Specified by:

isEnabled in interface I_CmsXmlDocument

Parameters:

name - the key to check

locale - the locale to check

Returns:

true if a value exists with the given key name, and that value is enabled, false otherwise

See Also:

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

isEnabled

public boolean isEnabled(String name,
                         Locale locale,
                         int index)

Description copied from interface: I_CmsXmlDocument

Returns true if a value exists with the given key name at the selected index, and that value is enabled, false otherwise.

Specified by:

isEnabled in interface I_CmsXmlDocument

Parameters:

name - the key to check

locale - the locale to check

index - the index position to check

Returns:

true if a value exists with the given key name at the selected index, and that value is enabled, false otherwise

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(Locale source,
                       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 did 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(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(String conversion)

Sets the content conversion mode for this document.

Parameters:

conversion - the conversion mode to set for this document

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

validateXmlStructure

public void validateXmlStructure(EntityResolver resolver)
                          throws CmsXmlException

Validates the xml structure of the document with the DTD ot 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 entitiy resolver to use

Throws:

CmsXmlException - if the validation fails

addBookmark

protected void addBookmark(String name,
                           Locale locale,
                           boolean enabled,
                           Object value)

Adds a bookmark for the given value.

Parameters:

name - the name 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(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.

getBookmark

protected Object getBookmark(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 Object getBookmark(String name,
                             Locale locale)

Returns the bookmarked value for the given name.

Parameters:

name - the name to get the bookmark for

locale - the locale to get the bookmark for

Returns:

the bookmarked value

getBookmarks

protected Set getBookmarks()

Returns the names of all bookmarked elements.

Returns:

the names of all bookmarked elements

initDocument

protected abstract void initDocument(Document document,
                                     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

marshal

protected OutputStream marshal(OutputStream out,
                               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(String name,
                                              Locale locale)

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

Parameters:

name - the name of the element

locale - the locale of the element

Returns:

the element removed from the bookmarks or null