com.adobe.cq.dam.cfm.ContentVariation Maven / Gradle / Ivy

/*
 * ADOBE CONFIDENTIAL
 *
 * Copyright 2015 Adobe Systems Incorporated
 * All Rights Reserved.
 *
 * NOTICE:  All information contained herein is, and remains
 * the property of Adobe Systems Incorporated and its suppliers,
 * if any.  The intellectual and technical concepts contained
 * herein are proprietary to Adobe Systems Incorporated and its
 * suppliers and may be covered by U.S. and Foreign Patents,
 * patents in process, and are protected by trade secret or copyright law.
 * Dissemination of this information or reproduction of this material
 * is strictly forbidden unless prior written permission is obtained
 * from Adobe Systems Incorporated.
 */

package com.adobe.cq.dam.cfm;

import aQute.bnd.annotation.ProviderType;

import javax.annotation.Nullable;

/**
 * Implementations of this interface allow to access a variation of a content element
 * through a stable API, agnostic to the underlying content structure.
 *
 * Variations can be synchronized with some other element. If the implementation does
 * not provide enhances synchronization capabilities (which it is free to do), it should
 * synchronize with the element content.
 *
 * The synchronization works by using the synchronization source, taking their content,
 * optionally applying some rules and then updating the variation with that content.
 *
 * How the synchronization source is defined and how the source content is processed is
 * implementation specific. This API only provides means to manage the synchronization
 * state and triggering the synchronization.
 *
 * The synchronization state is represented by the {@link SyncStatus} enumeration.
 *
 * Transactional behavior: The caller is responsible for committing the respective
 * {@link org.apache.sling.api.resource.ResourceResolver} after calling one or more
 * methods that change a content fragment unless specified otherwise.
 */
@ProviderType
public interface ContentVariation extends Versionable {

    /**
     * Gets the (technical) name of the variation.
     *
     * @return The name of the variation
     */
    String getName();

    /**
     * Gets the (human-readable) title of the variation.
     *
     * @return The title of the variation
     */
    String getTitle();

    /**
     * Sets the current title of the variation in the provided object representation.
     *
     * @param title The new title of the variation
     * @throws ContentFragmentException if the provided value couldn't be persisted
     */
    void setTitle(String title) throws ContentFragmentException;

    /**
     * Gets a description for the variation.
     *
     * @return The description
     */
    String getDescription();

    /**
     * Sets the current description of the variation in the provided object representation.
     *
     * @param description The new description of the variation
     * @throws ContentFragmentException if the provided value couldn't be persisted
     */
    void setDescription(String description) throws ContentFragmentException;

    /**
     * Gets the current value of the variation in a suitable object representation.
     *
     * Note that if you change the returned {@link FragmentData}, you will have to
     * call {@link #setValue(FragmentData)} explicitly after manipulating the value.
     *
     * {@link DataType} provides additional information about how values are handled
     * by the system.
     *
     * @return The value
     * @since 1.1
     */
    FragmentData getValue();

    /**
     * Sets the current value of the variation in the provided object representation.
     *
     * Please see {@link DataType} for more information about what "object
     * representation" means.
     *
     * @param object The value
     * @throws ContentFragmentException if the provided value couldn't be persisted or
     *                                  doesn't match the data type of the variation
     * @since 1.1
     */
    void setValue(FragmentData object) throws ContentFragmentException;

    /**
     * Gets the MIME type of the variation.
     *
     * @return The MIME type; refers to some text format
     */
    String getContentType();

    /**
     * Gets the content of the variation in a suitable text representation.
     *
     * @return The content of the variation (in a text representation)
     */
    String getContent();

    /**
     * Sets the content of the variation 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
     * {@link 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 {@link #getContent()} can successfully be
     * converted by {@link #setContent(String, String)}. In other words,
     * {@code el.setContent(el.getContent(), el.getContentType()} must not throw a
     * {@code ContentFragmentException} because of type conversion problems.
     *
     * @param content The content
     * @param contentType The MIME type of the content
     * @throws ContentFragmentException if the content could not be written or the provided
     *                                  text could not be converted to the data type of the
     *                                  underlying element correctly
     * @throws IllegalArgumentException if the specified MIME type is not supported or not
     *                                  a textual MIME type
     */
    void setContent(String content, String contentType) throws ContentFragmentException;

    /**
     * Gets the synchronization status of the variation.
     *
     * @return The synchronization state of the provided variation
     */
    SyncStatus getSyncStatus();

    /**
     * Synchronizes the variation.
     *
     * @throws ContentFragmentException if the synchronization failed
     */
    void synchronize() throws ContentFragmentException;
}