Package org.opencms.xml

Interface I_CmsXmlDocument

All Known Implementing Classes:
A_CmsXmlDocument, CmsXmlContainerPage, CmsXmlContent, CmsXmlGroupContainer, CmsXmlPage
public interface I_CmsXmlDocument
Describes the API to access the values of a XML content document.

Since:
6.0.0

  • Method Details

    • addLocale

      void addLocale(CmsObject cms, 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(List<Locale> possibleSources, 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(Locale source, 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

      Locale getBestMatchingLocale(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

    • getContentDefinition

      CmsXmlContentDefinition getContentDefinition()
      Returns the content definition object used for this XML document.

      Returns:
      the content definition object used for this XML document

    • getConversion

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

      Returns:
      the content conversion parameter used for this XML document

    • getEncoding

      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(String path, 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

      List<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

      List<Locale> getLocales(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

      List<String> getNames(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:

    • getStringValue

      String getStringValue(CmsObject cms, String path, 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

      String getStringValue(CmsObject cms, String path, 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

      List<I_CmsXmlContentValue> getSubValues(String path, 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(String path, 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(String path, 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

      List<I_CmsXmlContentValue> getValues(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:

    • getValues

      List<I_CmsXmlContentValue> getValues(String path, 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(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(String path, 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(String path, 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(String path, 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(String path, 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(Locale source, 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(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

    • validate

      CmsXmlContentErrorHandler validate(CmsObject cms)
      Validates the content of this XML document.

      To check for errors in a single document locale only, use CmsXmlContentErrorHandler.hasErrors(Locale) in the result object.

      Parameters:
      cms - the current OpenCms user context
      Returns:
      an error handler instance that provides information about the errors or warnings that have been found