Package com.adobe.cq.dam.cfm

Interface ContentElement

  • All Superinterfaces:
    Adaptable, Versionable
    public interface ContentElement
extends Adaptable, Versionable

    Implementations of this interface allow accessing elements of a content fragment in a way agnostic to the underlying data structures.

    Each content element consists of a set of 0..n variations, the element's content being kind of a "master" variation all other variations derive from.

    A content element is defined to consist of textual content. The ContentFragment interface is agnostic to a specific MIME type, so it's up to the implementation to decide when and how to transform the text to a format that's suitable for output.

    Transactional behavior: The caller is responsible for committing the respective ResourceResolver after calling one or more methods that change a content element unless specified otherwise.

    • Method Detail

      • getVariations

        java.util.Iterator<ContentVariation> getVariations()
        Gets an iterator on the currently available variations of the element.
        Returns:
        iterator on variations

      • getVariation

        @Nullable
@Nullable ContentVariation getVariation​(java.lang.String variationName)
        Gets the variation of the given name.
        Parameters:
        variationName - The name of the variation
        Returns:
        The variation; null if no variation of the given name exists

      • createVariation

        ContentVariation createVariation​(VariationTemplate template)
                          throws ContentFragmentException
        Creates a new variation of the element from the specified template.

        The initial content of the new variation must be a copy of the current element content.

        If the method is called multiple times with the same template, two different variations have to created (with different names/identifiers).

        The specified template should be part of a FragmentTemplate.

        Parameters:
        template - The template
        Returns:
        The variation created
        Throws:
        ContentFragmentException - if the variation could not be created

      • removeVariation

        void removeVariation​(ContentVariation variation)
              throws ContentFragmentException
        Removes the specified variation.

        If the specified variation is not a member of the element, a IllegalArgumentException has to be thrown.

        Parameters:
        variation - The variation to remove
        Throws:
        ContentFragmentException - if the variation could not be removed on the persistence level
        java.lang.IllegalArgumentException - if the specified variation is not part of this element

      • getResolvedVariation

        ContentVariation getResolvedVariation​(java.lang.String variationName)
        Gets the resolved variation for the given name.

        The method must be able to handle names that do not refer to actually existing variations. Instead, it has to handle this case in a well defined manner - usually by falling back to another, actually existing variation or to the element's default content.

        From a client's perspective, this method should be used to determine content in any kind of "publishing context" - be it in the page authoring context or some other context that prepares the final content to be presented to the user.

        How the resolution is eventually done is an implementation detail.

        Parameters:
        variationName - The name of the variation; may be null (which will return null to signal that default content has to be used)
        Returns:
        The resolved variation; null if there's no suitable variation and the element's default content has to be used

      • getName

        java.lang.String getName()

        Gets the (technical) name of the content element.

        Returns:
        The name of the content element

      • getTitle

        java.lang.String getTitle()
        Gets the (human-readable) title of the content element.
        Returns:
        The title of the content element

      • getValue

        FragmentData getValue()
        Gets the current value of the element in a suitable object representation.

        Note that if you change the returned FragmentData, you will have to call setValue(FragmentData) explicitly after manipulating the value.

        DataType provides additional information about how values are handled by the system.

        Returns:
        The value
        Since:
        1.1

      • setValue

        void setValue​(FragmentData object)
       throws ContentFragmentException

        Sets the current value of the element in the provided object representation.

        Please see DataType for more information about what "object representation" means.

        Parameters:
        object - The value
        Throws:
        ContentFragmentException - if the provided value couldn't be persisted or doesn't match the data type of the element
        Since:
        1.1

      • getContent

        java.lang.String getContent()

        Gets the content of the content element in a suitable text representation.

        Returns:
        The content of the content element in a text representation

      • getContentType

        java.lang.String getContentType()
        Gets the MIME type of the content element.
        Returns:
        The MIME type; refers to some text format

      • setContent

        void setContent​(java.lang.String content,
                java.lang.String contentType)
         throws ContentFragmentException

        Sets the content of the content element from the provided text value.

        The specified content & its MIME type must be textual. What MIME types are eventually supported is left to the implementation.

        For non-textual data types (added in 1.1), a MIME type of text/plain should be specified. The implementation is then responsible for translating the provided text value into a suitable object representation (or throw a ContentFragmentException if this is not possible). How the text value is converted into a suitable object value is left to the implementation. But it is required that a value returned by getContent() can successfully be converted by setContent(String, String). In other words, el.setContent(el.getContent(), el.getContentType() must not throw a ContentFragmentException because of type conversion problems.

        Parameters:
        content - The new content of the content element
        contentType - The new content type
        Throws:
        ContentFragmentException - if the content could not be written or the provided text could not be converted to the data type of the element correctly
        java.lang.IllegalArgumentException - if the specified MIME type is not supported or not a textual MIME type