com.adobe.cq.dam.cfm.ContentFragment 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 org.apache.sling.api.adapter.Adaptable;
import org.apache.sling.api.adapter.AdapterFactory;
import org.apache.sling.api.resource.Resource;

import java.util.Iterator;
import java.util.Map;

/**
 * Implementations of this interface allow to access content fragments through a stable
 * API, independently from the actual content structure.
 *
 * Content fragments consist of one or more elements, which in turn may contain
 * variations of their content - for example, a short variation for publishing the
 * fragment on Twitter or maybe an on-the-fly variation when the fragment is reused
 * on a different page than the original one.
 *
 * One element (the "main" or "master" element) is considered to define the
 * content fragment. This means, it has a special position within the content element and
 * usually contains the "most important" or "most distinctive" content.
 *
 * Each variation can be synchronized with the original element content, which in the
 * simplest way means that the current content of the element is copied to the variation.
 * Depending on the implementation, there might be more sophisticated ways that change
 * the original content in some way.
 *
 * Additionally, each content fragment has a collection of associated content, which
 * may contain references to assets, collections or other content fragments.
 *
 * Each content fragment has a set of meta data, which can be used for determining
 * associated content.
 *
 * Usage pattern: To obtain a ContentFragment, simply adapt a {@link Resource} to
 * ContentFragment.class. This means that each implementing module has to
 * provide a {@link AdapterFactory} that adapts Resources to
 * ContentFragment.
 *
 * 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 ContentFragment extends Adaptable, Versionable {

    /**
     * Gets an iterator on the templates of predefined content elements of the fragment.
     *
     * @return The iterator on the content elements
     */
    Iterator getElements();

    /**
     * Determines if the content fragment has an element of the specified name.
     *
     * @param elementName The name of the element to check
     * @return True if there is an element of the provided name
     */
    boolean hasElement(String elementName);

    /**
     * Creates a new element from the specified template.
     *
     * @param template The element template
     * @return The newly created content element
     * @throws ContentFragmentException if the change could not be persisted
     */
    ContentElement createElement(ElementTemplate template)
            throws ContentFragmentException;

    /**
     * Gets the content element of the specified name.
     *
     * @param elementName The name of the element; null or empty string
     *                    for the "main" or "master" element
     * @return The element; null
     */
    ContentElement getElement(String elementName);

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

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

    /**
     * Sets the (human-readable) title of the content fragment.
     *
     * @param title The new title
     * @throws ContentFragmentException if the change could not be persisted
     */
    void setTitle(String title) throws ContentFragmentException;

    /**
     * Gets the description of the content element.
     *
     * @return The description of the content element
     */
    String getDescription();

    /**
     * Sets the description of the content fragment.
     *
     * @param description The new description
     * @throws ContentFragmentException if the change could not be persisted
     */
    void setDescription(String description) throws ContentFragmentException;

    /**
     * Gets a map of the fragment's meta data.
     *
     * @return The map of meta data
     */
    Map getMetaData();

    /**
     * Sets a single meta data property.
     *
     * As meta data is not limited to the meta data provided through the template,
     * this method is generic.
     *
     * @param name Name of the meta data property
     * @param value Value of the meta data property
     * @throws ContentFragmentException if the property could not be set/persisted
     */
    void setMetaData(String name, Object value) throws ContentFragmentException;

    /**
     * Gets an iterator on all available variations that are available for the entire
     * fragment.
     *
     * This is used to get a "plain view" on variations, as not all elements may have
     * all variations.
     *
     * The list does not include the "master" or base variation!
     *
     * @return Iterator on available variations
     */
    Iterator listAllVariations();

    /**
     * Gets the fragment template assigned to this content element.
     *
     * @return The fragment template
     */
    FragmentTemplate getTemplate();

    /**
     * Creates a new variation.
     *
     * The variation is added to all elements of the fragment.
     *
     * The content of each fragment must be initialized with a copy of the element
     * content.
     *
     * @param name The (technical) name of the variation to be created
     * @param title The (human-readable) title of the variation to be created
     * @param description The description of the variation
     * @return The intermediate template that represents the newly created variation
     * @throws ContentFragmentException if the change could not be persisted
     */
    VariationTemplate createVariation(String name, String title, String description)
            throws ContentFragmentException;

    /**
     * Removes the specified global variation from the fragment.
     *
     * @param name The name of the global variation to remove
     * @throws ContentFragmentException if the variation could not be removed properly or
     *                                  there is no such variation available
     */
    void removeVariation(String name) throws ContentFragmentException;

    /**
     * Gets an iterator on associated content.
     *
     * @return Iterator on associated content
     */
    Iterator getAssociatedContent();

    /**
     * Adds the provided {@link Resource} as associated content.
     *
     * @param content The new associated content
     * @throws ContentFragmentException if the resource could not be added
     */
    void addAssociatedContent(Resource content) throws ContentFragmentException;

    /**
     * Removes the provided {@link Resource} as associated content.
     *
     * @param content The associated content to remove
     * @throws ContentFragmentException if the resource could not be removed
     */
    void removeAssociatedContent(Resource content) throws ContentFragmentException;

}