Package org.opencms.xml

Class A_CmsXmlDocument

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Modifier Constructor Description
      protected A_CmsXmlDocument()
      Default constructor for a XML document that initializes some internal values.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      java.util.Locale getBestMatchingLocale​(java.util.Locale locale)
      Returns the first matching locale (eventually simplified) from the available locales.
      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.
      java.util.List<I_CmsXmlContentValue> getSubValues​(java.lang.String path, java.util.Locale locale)
      Returns all content values (of type I_CmsXmlContentValue) directly below the given path available in this document for the given locale.
      java.util.Map<java.lang.String,​java.lang.Object> getTempDataCache()
      Gets the temporary data cache.
      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.
      protected I_CmsXmlContentValue getValueInternal​(java.lang.String path, java.util.Locale locale)
      Internal method to look up a value, requires that the name already has been "normalized" for the bookmark lookup.
      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.
      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.
      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()  
      protected void updateLocaleNodeSorting()
      Updates the order of the locale nodes if required.
      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

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

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

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

      • getTempDataCache

        public java.util.Map<java.lang.String,​java.lang.Object> getTempDataCache()
        Gets the temporary data cache.
        Returns:
        the temporary data cache

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

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

      • 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

      • 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

      • getValueInternal

        protected I_CmsXmlContentValue getValueInternal​(java.lang.String path,
                                                java.util.Locale locale)
        Internal method to look up a value, requires that the name already has been "normalized" for the bookmark lookup. This is required to find names like "title/subtitle" which are stored internally as "title[0]/subtitle[0]" in the bookmarks.
        Parameters:
        path - the path to look up
        locale - the locale to look up
        Returns:
        the value found in the bookmarks

      • 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

      • updateLocaleNodeSorting

        protected void updateLocaleNodeSorting()
        Updates the order of the locale nodes if required.