org.opencms.xml
Class CmsXmlContentDefinition

java.lang.Object
  org.opencms.xml.CmsXmlContentDefinition

All Implemented Interfaces:

java.lang.Cloneable

public class CmsXmlContentDefinition
extends java.lang.Object
implements java.lang.Cloneable

Describes the structure definition of an XML content object.

Since:

6.0.0

Version:

$Revision: 1.48 $

Author:

Alexander Kandzior

Field Summary

static java.lang.String	XSD_ATTRIBUTE_DEFAULT Constant for the XML schema attribute "mapto".
static java.lang.String	XSD_ATTRIBUTE_ELEMENT_FORM_DEFAULT Constant for the XML schema attribute "elementFormDefault".
static java.lang.String	XSD_ATTRIBUTE_MAX_OCCURS Constant for the XML schema attribute "maxOccurs".
static java.lang.String	XSD_ATTRIBUTE_MIN_OCCURS Constant for the XML schema attribute "minOccurs".
static java.lang.String	XSD_ATTRIBUTE_NAME Constant for the XML schema attribute "name".
static java.lang.String	XSD_ATTRIBUTE_SCHEMA_LOCATION Constant for the XML schema attribute "schemaLocation".
static java.lang.String	XSD_ATTRIBUTE_TYPE Constant for the XML schema attribute "type".
static java.lang.String	XSD_ATTRIBUTE_USE Constant for the XML schema attribute "use".
static java.lang.String	XSD_ATTRIBUTE_VALUE_LANGUAGE Constant for the XML schema attribute value "language".
static java.lang.String	XSD_ATTRIBUTE_VALUE_OPTIONAL Constant for the XML schema attribute value "optional".
static java.lang.String	XSD_ATTRIBUTE_VALUE_QUALIFIED Constant for the XML schema attribute value "qualified".
static java.lang.String	XSD_ATTRIBUTE_VALUE_REQUIRED Constant for the XML schema attribute value "required".
static java.lang.String	XSD_ATTRIBUTE_VALUE_UNBOUNDED Constant for the XML schema attribute value "unbounded".
static java.lang.String	XSD_ATTRIBUTE_VALUE_ZERO Constant for the XML schema attribute value "0".
static java.lang.String	XSD_INCLUDE_OPENCMS The opencms default type definition include.
static org.dom4j.Namespace	XSD_NAMESPACE The schema definition namespace.
static org.dom4j.QName	XSD_NODE_ANNOTATION Constant for the "annotation" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_APPINFO Constant for the "appinfo" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_ATTRIBUTE Constant for the "attribute" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_COMPLEXTYPE Constant for the "complexType" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_ELEMENT Constant for the "element" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_INCLUDE Constant for the "include" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_SCHEMA Constant for the "schema" node in the XML schema namespace.
static org.dom4j.QName	XSD_NODE_SEQUENCE Constant for the "sequence" node in the XML schema namespace.

Constructor Summary

protected	CmsXmlContentDefinition() Required empty constructor for clone operation.
	CmsXmlContentDefinition(java.lang.String innerName, java.lang.String schemaLocation) Creates a new XML content definition.
	CmsXmlContentDefinition(java.lang.String outerName, java.lang.String innerName, java.lang.String schemaLocation) Creates a new XML content definition.

Method Summary

org.dom4j.Element	addDefaultXml(CmsObject cms, I_CmsXmlDocument document, org.dom4j.Element root, java.util.Locale locale) Adds the missing default XML according to this content definition to the given document element.
void	addInclude(CmsXmlContentDefinition nestedSchema) Adds a nested (included) XML content definition.
void	addType(I_CmsXmlSchemaType type) Adds the given content type.
java.lang.Object	clone() Creates a clone of this XML content definition.
org.dom4j.Element	createDefaultXml(CmsObject cms, I_CmsXmlDocument document, org.dom4j.Element root, java.util.Locale locale) Generates the default XML content for this content definition, and append it to the given root element.
org.dom4j.Document	createDocument(CmsObject cms, I_CmsXmlDocument document, java.util.Locale locale) Generates a valid XML document according to the XML schema of this content definition.
org.dom4j.Element	createLocale(CmsObject cms, I_CmsXmlDocument document, org.dom4j.Element root, java.util.Locale locale) Generates a valid locale (language) element for the XML schema of this content definition.
protected static java.lang.String	createTypeName(java.lang.String name) Creates the name of the type attribute from the given content name.
boolean	equals(java.lang.Object obj)
void	freeze() Freezes this content definition, making all internal data structures unmodifiable.
I_CmsXmlContentHandler	getContentHandler() Returns the selected XML content handler for this XML content definition.
java.util.Set<CmsXmlContentDefinition>	getIncludes() Returns the set of nested (included) XML content definitions.
java.lang.String	getInnerName() Returns the inner element name of this content definition.
java.lang.String	getOuterName() Returns the outer element name of this content definition.
org.dom4j.Document	getSchema() Generates an XML schema for the content definition.
java.lang.String	getSchemaLocation() Returns the location from which the XML schema was read (XML system id).
I_CmsXmlSchemaType	getSchemaType(java.lang.String elementPath) Returns the scheme type for the given element name, or null if no node is defined with this name.
java.util.Set<java.lang.String>	getSchemaTypes() Returns the internal set of schema type names.
java.lang.String	getTypeName() Returns the main type name of this XML content definition.
java.util.List<I_CmsXmlSchemaType>	getTypeSequence() Returns the type sequence, contains instances of I_CmsXmlSchemaType.
int	hashCode()
protected void	setInnerName(java.lang.String innerName) Sets the inner element name to use for the content definition.
protected void	setOuterName(java.lang.String outerName) Sets the outer element name to use for the content definition.
static CmsXmlContentDefinition	unmarshal(byte[] xmlData, java.lang.String schemaLocation, org.xml.sax.EntityResolver resolver) Factory method to unmarshal (read) a XML content definition instance from a byte array that contains XML data.
static CmsXmlContentDefinition	unmarshal(CmsObject cms, java.lang.String resourcename) Factory method to unmarshal (read) a XML content definition instance from the OpenCms VFS resource name.
static CmsXmlContentDefinition	unmarshal(org.dom4j.Document document, java.lang.String schemaLocation) Factory method to unmarshal (read) a XML content definition instance from a XML document.
static CmsXmlContentDefinition	unmarshal(org.xml.sax.InputSource source, java.lang.String schemaLocation, org.xml.sax.EntityResolver resolver) Factory method to unmarshal (read) a XML content definition instance from a XML InputSource.
static CmsXmlContentDefinition	unmarshal(java.lang.String schemaLocation, org.xml.sax.EntityResolver resolver) Factory method to unmarshal (read) a XML content definition instance from a given XML schema location.
static CmsXmlContentDefinition	unmarshal(java.lang.String xmlData, java.lang.String schemaLocation, org.xml.sax.EntityResolver resolver) Factory method to unmarshal (read) a XML content definition instance from a String that contains XML data.
protected static java.lang.String	validateAttribute(org.dom4j.Element element, java.lang.String attributeName, java.lang.String requiredValue) Validates if a given attribute exists at the given element with an (optional) specified value.
protected static void	validateAttributesExists(org.dom4j.Element element, java.lang.String[] requiredAttributes, java.lang.String[] optionalAttributes) Validates if a given element has exactly the required attributes set.
protected static org.opencms.xml.CmsXmlComplexTypeSequence	validateComplexTypeSequence(org.dom4j.Element element, java.util.Set<CmsXmlContentDefinition> includes) Validates the given element as a complex type sequence.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

XSD_ATTRIBUTE_DEFAULT

public static final java.lang.String XSD_ATTRIBUTE_DEFAULT

Constant for the XML schema attribute "mapto".

See Also:

Constant Field Values

XSD_ATTRIBUTE_ELEMENT_FORM_DEFAULT

public static final java.lang.String XSD_ATTRIBUTE_ELEMENT_FORM_DEFAULT

Constant for the XML schema attribute "elementFormDefault".

See Also:

Constant Field Values

XSD_ATTRIBUTE_MAX_OCCURS

public static final java.lang.String XSD_ATTRIBUTE_MAX_OCCURS

Constant for the XML schema attribute "maxOccurs".

See Also:

Constant Field Values

XSD_ATTRIBUTE_MIN_OCCURS

public static final java.lang.String XSD_ATTRIBUTE_MIN_OCCURS

Constant for the XML schema attribute "minOccurs".

See Also:

Constant Field Values

XSD_ATTRIBUTE_NAME

public static final java.lang.String XSD_ATTRIBUTE_NAME

Constant for the XML schema attribute "name".

See Also:

Constant Field Values

XSD_ATTRIBUTE_SCHEMA_LOCATION

public static final java.lang.String XSD_ATTRIBUTE_SCHEMA_LOCATION

Constant for the XML schema attribute "schemaLocation".

See Also:

Constant Field Values

XSD_ATTRIBUTE_TYPE

public static final java.lang.String XSD_ATTRIBUTE_TYPE

Constant for the XML schema attribute "type".

See Also:

Constant Field Values

XSD_ATTRIBUTE_USE

public static final java.lang.String XSD_ATTRIBUTE_USE

Constant for the XML schema attribute "use".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_LANGUAGE

public static final java.lang.String XSD_ATTRIBUTE_VALUE_LANGUAGE

Constant for the XML schema attribute value "language".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_OPTIONAL

public static final java.lang.String XSD_ATTRIBUTE_VALUE_OPTIONAL

Constant for the XML schema attribute value "optional".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_QUALIFIED

public static final java.lang.String XSD_ATTRIBUTE_VALUE_QUALIFIED

Constant for the XML schema attribute value "qualified".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_REQUIRED

public static final java.lang.String XSD_ATTRIBUTE_VALUE_REQUIRED

Constant for the XML schema attribute value "required".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_UNBOUNDED

public static final java.lang.String XSD_ATTRIBUTE_VALUE_UNBOUNDED

Constant for the XML schema attribute value "unbounded".

See Also:

Constant Field Values

XSD_ATTRIBUTE_VALUE_ZERO

public static final java.lang.String XSD_ATTRIBUTE_VALUE_ZERO

Constant for the XML schema attribute value "0".

See Also:

Constant Field Values

XSD_INCLUDE_OPENCMS

public static final java.lang.String XSD_INCLUDE_OPENCMS

The opencms default type definition include.

See Also:

Constant Field Values

XSD_NAMESPACE

public static final org.dom4j.Namespace XSD_NAMESPACE

The schema definition namespace.

XSD_NODE_ANNOTATION

public static final org.dom4j.QName XSD_NODE_ANNOTATION

Constant for the "annotation" node in the XML schema namespace.

XSD_NODE_APPINFO

public static final org.dom4j.QName XSD_NODE_APPINFO

Constant for the "appinfo" node in the XML schema namespace.

XSD_NODE_ATTRIBUTE

public static final org.dom4j.QName XSD_NODE_ATTRIBUTE

Constant for the "attribute" node in the XML schema namespace.

XSD_NODE_COMPLEXTYPE

public static final org.dom4j.QName XSD_NODE_COMPLEXTYPE

Constant for the "complexType" node in the XML schema namespace.

XSD_NODE_ELEMENT

public static final org.dom4j.QName XSD_NODE_ELEMENT

Constant for the "element" node in the XML schema namespace.

XSD_NODE_INCLUDE

public static final org.dom4j.QName XSD_NODE_INCLUDE

Constant for the "include" node in the XML schema namespace.

XSD_NODE_SCHEMA

public static final org.dom4j.QName XSD_NODE_SCHEMA

Constant for the "schema" node in the XML schema namespace.

XSD_NODE_SEQUENCE

public static final org.dom4j.QName XSD_NODE_SEQUENCE

Constant for the "sequence" node in the XML schema namespace.

Constructor Detail

CmsXmlContentDefinition

public CmsXmlContentDefinition(java.lang.String innerName,
                               java.lang.String schemaLocation)

Creates a new XML content definition.

Parameters:

innerName - the inner element name to use for the content definiton

schemaLocation - the location from which the XML schema was read (system id)

CmsXmlContentDefinition

public CmsXmlContentDefinition(java.lang.String outerName,
                               java.lang.String innerName,
                               java.lang.String schemaLocation)

Creates a new XML content definition.

Parameters:

outerName - the outer element name to use for the content definition

innerName - the inner element name to use for the content definition

schemaLocation - the location from which the XML schema was read (system id)

CmsXmlContentDefinition

protected CmsXmlContentDefinition()

Required empty constructor for clone operation.

Method Detail

unmarshal

public static CmsXmlContentDefinition unmarshal(byte[] xmlData,
                                                java.lang.String schemaLocation,
                                                org.xml.sax.EntityResolver resolver)
                                         throws CmsXmlException

Factory method to unmarshal (read) a XML content definition instance from a byte array that contains XML data.

Parameters:

xmlData - the XML data in a byte array

schemaLocation - the location from which the XML schema was read (system id)

resolver - the XML entity resolver to use

Returns:

a XML content definition instance unmarshalled from the byte array

Throws:

CmsXmlException - if something goes wrong

unmarshal

public static CmsXmlContentDefinition unmarshal(CmsObject cms,
                                                java.lang.String resourcename)
                                         throws CmsXmlException

Factory method to unmarshal (read) a XML content definition instance from the OpenCms VFS resource name.

Parameters:

cms - the current users CmsObject

resourcename - the resource name to unmarshal the XML content definition from

Returns:

a XML content definition instance unmarshalled from the VFS resource

Throws:

CmsXmlException - if something goes wrong

unmarshal

public static CmsXmlContentDefinition unmarshal(org.dom4j.Document document,
                                                java.lang.String schemaLocation)
                                         throws CmsXmlException

Factory method to unmarshal (read) a XML content definition instance from a XML document.

This method does additional validation to ensure the document has the required XML structure for a OpenCms content definition schema.

Parameters:

document - the XML document to generate a XML content definition from

schemaLocation - the location from which the XML schema was read (system id)

Returns:

a XML content definition instance unmarshalled from the XML document

Throws:

CmsXmlException - if something goes wrong

unmarshal

public static CmsXmlContentDefinition unmarshal(org.xml.sax.InputSource source,
                                                java.lang.String schemaLocation,
                                                org.xml.sax.EntityResolver resolver)
                                         throws CmsXmlException

Factory method to unmarshal (read) a XML content definition instance from a XML InputSource.

Parameters:

source - the XML InputSource to use

schemaLocation - the location from which the XML schema was read (system id)

resolver - the XML entity resolver to use

Returns:

a XML content definition instance unmarshalled from the InputSource

Throws:

CmsXmlException - if something goes wrong

unmarshal

public static CmsXmlContentDefinition unmarshal(java.lang.String schemaLocation,
                                                org.xml.sax.EntityResolver resolver)
                                         throws CmsXmlException,
                                                org.xml.sax.SAXException,
                                                java.io.IOException

Factory method to unmarshal (read) a XML content definition instance from a given XML schema location.

The XML content definition data to unmarshal will be read from the provided schema location using an XML InputSource.

Parameters:

schemaLocation - the location from which to read the XML schema (system id)

resolver - the XML entity resolver to use

Returns:

a XML content definition instance unmarshalled from the InputSource

Throws:

CmsXmlException - if something goes wrong

org.xml.sax.SAXException - if the XML schema location could not be converted to an XML InputSource

java.io.IOException - if the XML schema location could not be converted to an XML InputSource

unmarshal

public static CmsXmlContentDefinition unmarshal(java.lang.String xmlData,
                                                java.lang.String schemaLocation,
                                                org.xml.sax.EntityResolver resolver)
                                         throws CmsXmlException

Factory method to unmarshal (read) a XML content definition instance from a String that contains XML data.

Parameters:

xmlData - the XML data in a String

schemaLocation - the location from which the XML schema was read (system id)

resolver - the XML entitiy resolver to use

Returns:

a XML content definition instance unmarshalled from the byte array

Throws:

CmsXmlException - if something goes wrong

createTypeName

protected static java.lang.String createTypeName(java.lang.String name)

Creates the name of the type attribute from the given content name.

Parameters:

name - the name to use

Returns:

the name of the type attribute

validateAttribute

protected static java.lang.String validateAttribute(org.dom4j.Element element,
                                                    java.lang.String attributeName,
                                                    java.lang.String requiredValue)
                                             throws CmsXmlException

Validates if a given attribute exists at the given element with an (optional) specified value.

If the required value is not null, the attribute must have exactly this value set.

If no value is required, some simple validation is performed on the attribute value, like a check that the value does not have leading or trailing white spaces.

Parameters:

element - the element to validate

attributeName - the attribute to check for

requiredValue - the required value of the attribute, or null if any value is allowed

Returns:

the value of the attribute

Throws:

CmsXmlException - if the element does not have the required attribute set, or if the validation fails

validateAttributesExists

protected static void validateAttributesExists(org.dom4j.Element element,
                                               java.lang.String[] requiredAttributes,
                                               java.lang.String[] optionalAttributes)
                                        throws CmsXmlException

Validates if a given element has exactly the required attributes set.

Parameters:

element - the element to validate

requiredAttributes - the list of required attributes

optionalAttributes - the list of optional attributes

Throws:

CmsXmlException - if the validation fails

validateComplexTypeSequence

protected static org.opencms.xml.CmsXmlComplexTypeSequence validateComplexTypeSequence(org.dom4j.Element element,
                                                                                       java.util.Set<CmsXmlContentDefinition> includes)
                                                                                throws CmsXmlException

Validates the given element as a complex type sequence.

Parameters:

element - the element to validate

includes - the XML schema includes

Returns:

a data structure containing the validated complex type sequence data

Throws:

CmsXmlException - if the validation fails

addDefaultXml

public org.dom4j.Element addDefaultXml(CmsObject cms,
                                       I_CmsXmlDocument document,
                                       org.dom4j.Element root,
                                       java.util.Locale locale)

Adds the missing default XML according to this content definition to the given document element.

In case the root element already contains sub nodes, only missing sub nodes are added.

Parameters:

cms - the current users OpenCms context

document - the document where the XML is added in (required for default XML generation)

root - the root node to add the missing XML for

locale - the locale to add the XML for

Returns:

the given root element with the missing content added

addInclude

public void addInclude(CmsXmlContentDefinition nestedSchema)

Adds a nested (included) XML content definition.

Parameters:

nestedSchema - the nested (included) XML content definition to add

addType

public void addType(I_CmsXmlSchemaType type)
             throws CmsXmlException

Adds the given content type.

Parameters:

type - the content type to add

Throws:

CmsXmlException - in case an unregistered type is added

clone

public java.lang.Object clone()

Creates a clone of this XML content definition.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this XML content definition

createDefaultXml

public org.dom4j.Element createDefaultXml(CmsObject cms,
                                          I_CmsXmlDocument document,
                                          org.dom4j.Element root,
                                          java.util.Locale locale)

Generates the default XML content for this content definition, and append it to the given root element.

Please note: The default values for the annotations are read from the content definition of the given document. For a nested content definitions, this means that all defaults are set in the annotations of the "outer" or "main" content definition.

Parameters:

cms - the current users OpenCms context

document - the OpenCms XML document the XML is created for

root - the node of the document where to append the generated XML to

locale - the locale to create the default element in the document with

Returns:

the default XML content for this content definition, and append it to the given root element

createDocument

public org.dom4j.Document createDocument(CmsObject cms,
                                         I_CmsXmlDocument document,
                                         java.util.Locale locale)

Generates a valid XML document according to the XML schema of this content definition.

Parameters:

cms - the current users OpenCms context

document - the OpenCms XML document the XML is created for

locale - the locale to create the default element in the document with

Returns:

a valid XML document according to the XML schema of this content definition

createLocale

public org.dom4j.Element createLocale(CmsObject cms,
                                      I_CmsXmlDocument document,
                                      org.dom4j.Element root,
                                      java.util.Locale locale)

Generates a valid locale (language) element for the XML schema of this content definition.

Parameters:

cms - the current users OpenCms context

document - the OpenCms XML document the XML is created for

root - the root node of the document where to append the locale to

locale - the locale to create the default element in the document with

Returns:

a valid XML element for the locale according to the XML schema of this content definition

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(java.lang.Object)

freeze

public void freeze()

Freezes this content definition, making all internal data structures unmodifiable.

This is required to prevent modification of a cached content definition.

getContentHandler

public I_CmsXmlContentHandler getContentHandler()

Returns the selected XML content handler for this XML content definition.

If no specific XML content handler was provided in the "appinfo" node of the XML schema, the default XML content handler CmsDefaultXmlContentHandler is used.

Returns:

the contentHandler

getIncludes

public java.util.Set<CmsXmlContentDefinition> getIncludes()

Returns the set of nested (included) XML content definitions.

Returns:

the set of nested (included) XML content definitions

getInnerName

public java.lang.String getInnerName()

Returns the inner element name of this content definition.

Returns:

the inner element name of this content definition

getOuterName

public java.lang.String getOuterName()

Returns the outer element name of this content definition.

Returns:

the outer element name of this content definition

getSchema

public org.dom4j.Document getSchema()

Generates an XML schema for the content definition.

Returns:

the generated XML schema

getSchemaLocation

public java.lang.String getSchemaLocation()

Returns the location from which the XML schema was read (XML system id).

Returns:

the location from which the XML schema was read (XML system id)

getSchemaType

public I_CmsXmlSchemaType getSchemaType(java.lang.String elementPath)

Returns the scheme type for the given element name, or null if no node is defined with this name.

Parameters:

elementPath - the element path to look up the type for

Returns:

the type for the given element name, or null if no node is defined with this name

getSchemaTypes

public java.util.Set<java.lang.String> getSchemaTypes()

Returns the internal set of schema type names.

Returns:

the internal set of schema type names

getTypeName

public java.lang.String getTypeName()

Returns the main type name of this XML content definition.

Returns:

the main type name of this XML content definition

getTypeSequence

public java.util.List<I_CmsXmlSchemaType> getTypeSequence()

Returns the type sequence, contains instances of I_CmsXmlSchemaType.

Returns:

the type sequence, contains instances of I_CmsXmlSchemaType

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

setInnerName

protected void setInnerName(java.lang.String innerName)

Sets the inner element name to use for the content definition.

Parameters:

innerName - the inner element name to set

setOuterName

protected void setOuterName(java.lang.String outerName)

Sets the outer element name to use for the content definition.

Parameters:

outerName - the outer element name to set