Package org.opencms.xml

Interface I_CmsXmlDocument

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addLocale​(CmsObject cms, java.util.Locale locale)
      Adds the given locale to this XML document.
      void copyLocale​(java.util.List<java.util.Locale> possibleSources, java.util.Locale destination)
      Copies the content from the first matching source locale that exists in this XML document to the given destination locale in this XML document.
      void copyLocale​(java.util.Locale source, java.util.Locale destination)
      Copies the content of the given source locale to the given destination locale in this XML document.
      java.util.Locale getBestMatchingLocale​(java.util.Locale locale)
      Returns the first matching locale (eventually simplified) from the available locales.
      CmsXmlContentDefinition getContentDefinition()
      Returns the content definition object used for this XML document.
      java.lang.String getConversion()
      Returns the content conversion parameter used for this XML document.
      java.lang.String getEncoding()
      Returns the encoding used for this XML document.
      CmsFile getFile()
      Returns the file this document was generated from, may be null if the file not available.
      I_CmsXmlContentHandler getHandler()
      Returns the content handler associated with the content definition of this XML document.
      int getIndexCount​(java.lang.String path, java.util.Locale locale)
      Returns the index count of existing values for the given path, or -1 if no such path exists.
      CmsLinkProcessor getLinkProcessor​(CmsObject cms, CmsLinkTable linkTable)
      Returns a link processor for the values of this XML document.
      java.util.List<java.util.Locale> getLocales()
      Returns a List of all locales that have at last one value in this XML document.
      java.util.List<java.util.Locale> getLocales​(java.lang.String path)
      Returns a List of all locales that have at least one element with the given path in this XML document.
      java.util.List<java.lang.String> getNames​(java.util.Locale locale)
      Returns a List of all available elements paths (Strings) used in this document for the given locale.
      java.lang.String getStringValue​(CmsObject cms, java.lang.String path, java.util.Locale locale)
      Returns the first content value for the given path as a String, or null if no such value exists.
      java.lang.String getStringValue​(CmsObject cms, java.lang.String path, java.util.Locale locale, int index)
      Returns the content value for the given path and the selected index as a String, or null if no such value exists.
      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.
      I_CmsXmlContentValue getValue​(java.lang.String path, java.util.Locale locale)
      Returns the content value Object for the given path, or null if no such value exists.
      I_CmsXmlContentValue getValue​(java.lang.String path, java.util.Locale locale, int index)
      Returns the content value Object for the given path and the selected index, or null if no such value exists.
      java.util.List<I_CmsXmlContentValue> getValues​(java.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.
      boolean isEnabled​(java.lang.String path, java.util.Locale locale)
      Returns true if a value with the given path exists for the selected locale in this XML document, and that value is enabled, or false otherwise.
      boolean isEnabled​(java.lang.String path, java.util.Locale locale, int index)
      Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled, or false otherwise.
      void moveLocale​(java.util.Locale source, java.util.Locale destination)
      Moves the content of the given source locale to the given destination locale in this XML document.
      void removeLocale​(java.util.Locale locale)
      Removes the given locale from this XML document.
      CmsXmlContentErrorHandler validate​(CmsObject cms)
      Validates the content of this XML document.

    • Method Detail

      • addLocale

        void addLocale​(CmsObject cms,
               java.util.Locale locale)
        throws CmsXmlException
        Adds the given locale to this XML document.

        Parameters:
        cms - the current users OpenCms context
        locale - the locale to add
        Throws:
        CmsXmlException - in case the locale already existed, or if something else goes wrong

      • copyLocale

        void copyLocale​(java.util.List<java.util.Locale> possibleSources,
                java.util.Locale destination)
         throws CmsXmlException
        Copies the content from the first matching source locale that exists in this XML document to the given destination locale in this XML document.

        The list of possible sources, has to be sorted in order of preference. The first match that exists in this XML document is used as source for the destination locale. No "locale simplification" ("en_EN" to "en" etc.) is performed for the match.

        Parameters:
        possibleSources - the possible source locales in order of preference, must contain objects of type Locale
        destination - the destination locale
        Throws:
        CmsXmlException - in case non of the source locales did not exist, or the destination locale already exists in the document, or if something else goes wrong

      • copyLocale

        void copyLocale​(java.util.Locale source,
                java.util.Locale destination)
         throws CmsXmlException
        Copies the content of the given source locale to the given destination locale in this XML document.

        Parameters:
        source - the source locale
        destination - the destination locale
        Throws:
        CmsXmlException - in case either the source locale did not exist, or the destination locale already exists in the document, or if something else goes wrong

      • getBestMatchingLocale

        java.util.Locale getBestMatchingLocale​(java.util.Locale locale)
        Returns the first matching locale (eventually simplified) from the available locales.

        In case no match is found, code null is returned.

        Parameters:
        locale - the requested locale
        Returns:
        the matching locale available within the document

      • getConversion

        java.lang.String getConversion()
        Returns the content conversion parameter used for this XML document.

        Returns:
        the content conversion parameter used for this XML document

      • getEncoding

        java.lang.String getEncoding()
        Returns the encoding used for this XML document.

        Returns:
        the encoding used for this XML document

      • getFile

        CmsFile getFile()
        Returns the file this document was generated from, may be null if the file not available.

        The file may not be available if the document was generated from a String or a pure XML document.

        Returns:
        the file this document was generated from

      • getHandler

        I_CmsXmlContentHandler getHandler()
        Returns the content handler associated with the content definition of this XML document.

        This is a shortcut for getContentDefinition().getContentHandler().

        Returns:
        the content handler associated with the content definition of this XML document

      • getIndexCount

        int getIndexCount​(java.lang.String path,
                  java.util.Locale locale)
        Returns the index count of existing values for the given path, or -1 if no such path exists.

        Parameters:
        path - the path to get the index count for
        locale - the locale to get the index count for
        Returns:
        the index count for the given key name

      • getLinkProcessor

        CmsLinkProcessor getLinkProcessor​(CmsObject cms,
                                  CmsLinkTable linkTable)
        Returns a link processor for the values of this XML document.

        Parameters:
        cms - the current OpenCms user context that provides access to the link processor
        linkTable - the table with the links to process
        Returns:
        a link processor for the values of this XML document

      • getLocales

        java.util.List<java.util.Locale> getLocales()
        Returns a List of all locales that have at last one value in this XML document.

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

      • getLocales

        java.util.List<java.util.Locale> getLocales​(java.lang.String path)
        Returns a List of all locales that have at least one element with the given path in this XML document.

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

        Parameters:
        path - the path to look up the locale List for
        Returns:
        a List of all locales that have at least one element with the given path in this XML document

      • getNames

        java.util.List<java.lang.String> getNames​(java.util.Locale locale)
        Returns a List of all available elements paths (Strings) used in this document for the given locale.

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

        Parameters:
        locale - the locale to look up the elements paths for
        Returns:
        a List of all available elements paths (Strings) used in this document for the given locale
        See Also:
        getValues(Locale)

      • getStringValue

        java.lang.String getStringValue​(CmsObject cms,
                                java.lang.String path,
                                java.util.Locale locale)
                         throws CmsXmlException
        Returns the first content value for the given path as a String, or null if no such value exists.

        Parameters:
        cms - the current OpenCms user context
        path - the path to get the content value for
        locale - the locale to get the content value for
        Returns:
        the first content value for the given path as a String
        Throws:
        CmsXmlException - if something goes wrong

      • getStringValue

        java.lang.String getStringValue​(CmsObject cms,
                                java.lang.String path,
                                java.util.Locale locale,
                                int index)
                         throws CmsXmlException
        Returns the content value for the given path and the selected index as a String, or null if no such value exists.

        Parameters:
        cms - the current OpenCms user context
        path - the path to get the content value for
        locale - the locale to get the content value for
        index - the index position to get the value from
        Returns:
        the content value for the given path and the selected index as a String
        Throws:
        CmsXmlException - if something goes wrong

      • getSubValues

        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.

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

        Parameters:
        path - the path to get the sub content values for
        locale - the locale to get the sub content values for
        Returns:
        all content values (of type I_CmsXmlContentValue) directly below the given path available in this document for the given locale

      • getValue

        I_CmsXmlContentValue getValue​(java.lang.String path,
                              java.util.Locale locale)
        Returns the content value Object for the given path, or null if no such value exists.

        You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

        Parameters:
        path - the path to get the content value for
        locale - the locale to get the content value for
        Returns:
        the content value Object for the given path

      • getValue

        I_CmsXmlContentValue getValue​(java.lang.String path,
                              java.util.Locale locale,
                              int index)
        Returns the content value Object for the given path and the selected index, or null if no such value exists.

        Parameters:
        path - the path to get the content value for
        locale - the locale to get the content value for
        index - the index position to get the value from
        Returns:
        the content value Object for the given path and the selected index

      • getValues

        java.util.List<I_CmsXmlContentValue> getValues​(java.util.Locale locale)
        Returns all available content values (of type I_CmsXmlContentValue) in this document for the given locale.

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

        Parameters:
        locale - the locale to get the content values for
        Returns:
        all available content values (of type I_CmsXmlContentValue) in this document for the given locale
        See Also:
        getNames(Locale)

      • getValues

        java.util.List<I_CmsXmlContentValue> getValues​(java.lang.String path,
                                               java.util.Locale locale)
        Returns all content values (of type I_CmsXmlContentValue) with the given path available in this document for the given locale.

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

        Parameters:
        path - the path to get the content values for
        locale - the locale to get the content values for
        Returns:
        all content values (of type I_CmsXmlContentValue) with the given path available in this document for the given locale

      • hasLocale

        boolean hasLocale​(java.util.Locale locale)
        Returns true if the given locale exists in this XML document.

        Parameters:
        locale - the locale to check
        Returns:
        true if the given locale exists in this XML document, false otherwise

      • hasValue

        boolean hasValue​(java.lang.String path,
                 java.util.Locale locale)
        Returns true if a value with the given path exists for the selected locale in this XML document, or false otherwise.

        You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

        Parameters:
        path - the path to check
        locale - the locale to check
        Returns:
        true if a value with the given path exists for the selected locale in this XML document

      • hasValue

        boolean hasValue​(java.lang.String path,
                 java.util.Locale locale,
                 int index)
        Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, or false otherwise.

        Parameters:
        path - the path to check
        locale - the locale to check
        index - the index position to check
        Returns:
        true if a value with the given path and the provided index exists for the selected locale in this XML document

      • initDocument

        void initDocument()
        Initializes this XML document, required after structural changes to the internal XML.

        If nodes in the XML are added, removed or moved, the document needs to be initialized in order to update the internal data structures.

      • isEnabled

        boolean isEnabled​(java.lang.String path,
                  java.util.Locale locale)
        Returns true if a value with the given path exists for the selected locale in this XML document, and that value is enabled, or false otherwise.

        This is only used with implementations that support enabling and disabling individual values, such as CmsXmlPage. If enabling / disabling values is not supported, this is identical to hasValue(String, Locale).

        You can provide an index by appending a number in square brackets to the path parameter like this "Title[1]". If no index is provided, 1 is used for the index position.

        Parameters:
        path - the path to check
        locale - the locale to check
        Returns:
        true if a value with the given path exists for the selected locale in this XML document, and that value is enabled

      • isEnabled

        boolean isEnabled​(java.lang.String path,
                  java.util.Locale locale,
                  int index)
        Returns true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled, or false otherwise.

        This is only used with implementations that support enabling and disabling individual values, such as CmsXmlPage. If enabling / disabling values is not supported, this is identical to hasValue(String, Locale, int).

        Parameters:
        path - the path to check
        locale - the locale to check
        index - the index position to check
        Returns:
        true if a value with the given path and the provided index exists for the selected locale in this XML document, and that value is enabled

      • moveLocale

        void moveLocale​(java.util.Locale source,
                java.util.Locale destination)
         throws CmsXmlException
        Moves the content of the given source locale to the given destination locale in this XML document.

        Parameters:
        source - the source locale
        destination - the destination locale
        Throws:
        CmsXmlException - in case either the source locale does not exist, or the destination locale already exists in the document, or if something else goes wrong

      • removeLocale

        void removeLocale​(java.util.Locale locale)
           throws CmsXmlException
        Removes the given locale from this XML document.
        Parameters:
        locale - the locale to remove
        Throws:
        CmsXmlException - in case the locale did not exist in the document, or if something else goes wrong