Package org.opencms.xml

Class 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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CmsXmlContentDefinition.SequenceType
      Enumeration of possible sequence types in a content definition.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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)  
      boolean findSchemaTypesForPath​(java.lang.String path, java.util.function.BiConsumer<I_CmsXmlSchemaType,​java.lang.String> consumer)
      Iterates over all schema types along a given xpath, starting from a root content definition.
      void freeze()
      Freezes this content definition, making all internal data structures unmodifiable.
      int getChoiceMaxOccurs()
      Returns the maxOccurs value for the choice in case this is a xsd:choice content definition.
      static CmsXmlContentDefinition getContentDefinitionForResource​(CmsObject cms, CmsResource resource)
      Factory method that returns the XML content definition instance for a given resource.
      static CmsXmlContentDefinition getContentDefinitionForType​(CmsObject cms, java.lang.String typeName)
      Reads the content definition which is configured for a resource type.
      I_CmsXmlContentHandler getContentHandler()
      Returns the selected XML content handler for this XML content definition.
      static I_CmsXmlContentHandler getContentHandlerForResource​(CmsObject cms, CmsResource resource)
      Returns a content handler instance for the given resource.
      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 schema 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.
      CmsXmlContentDefinition.SequenceType getSequenceType()
      Returns the sequence type of this content definition.
      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.
      java.lang.String toString()  
      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​(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.
      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​(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​(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.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.
      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, wait, wait, wait

    • 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)

    • 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 entity 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

      • 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)

      • findSchemaTypesForPath

        public boolean findSchemaTypesForPath​(java.lang.String path,
                                      java.util.function.BiConsumer<I_CmsXmlSchemaType,​java.lang.String> consumer)
        Iterates over all schema types along a given xpath, starting from a root content definition.

        Parameters:
        path - the path
        consumer - a handler that consumes both the schema type and the remaining suffix of the path, relative to the schema type
        Returns:
        true if for all path components a schema type could be found

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

      • getChoiceMaxOccurs

        public int getChoiceMaxOccurs()
        Returns the maxOccurs value for the choice in case this is a xsd:choice content definition.

        This content definition is a xsd:choice sequence if the returned value is larger then 0.

        Returns:
        the maxOccurs value for the choice in case this is a xsd:choice 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 schema type for the given element name, or null if no node is defined with this name.

        Parameters:
        elementPath - the element xpath 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
        See Also:
        Object.toString()

      • 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