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 Summary

Modifier and Type	Method and Description
ContentVariation	createVariation(VariationTemplate template) Creates a new variation of the element from the specified template.
java.lang.String	getContent() Gets the content of the content element in a suitable text representation.
java.lang.String	getContentType() Gets the MIME type of the content element.
java.lang.String	getName() Gets the (technical) name of the content element.
ContentVariation	getResolvedVariation(java.lang.String variationName) Gets the resolved variation for the given name.
java.lang.String	getTitle() Gets the (human-readable) title of the content element.
FragmentData	getValue() Gets the current value of the element in a suitable object representation.
ContentVariation	getVariation(java.lang.String variationName) Gets the variation of the given name.
java.util.Iterator<ContentVariation>	getVariations() Gets an iterator on the currently available variations of the element.
void	removeVariation(ContentVariation variation) Removes the specified variation.
void	setContent(java.lang.String content, java.lang.String contentType) Sets the content of the content element from the provided text value.
void	setValue(FragmentData object) Sets the current value of the element in the provided object representation.

Methods inherited from interface org.apache.sling.api.adapter.Adaptable

adaptTo

Methods inherited from interface com.adobe.cq.dam.cfm.Versionable

createVersion, getVersionedContent, listVersions

Method Detail

getVariations

java.util.Iterator<ContentVariation> getVariations()

Gets an iterator on the currently available variations of the element.

Returns:

iterator on variations

getVariation

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