com.adobe.cq.dam.cfm.FragmentData 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.Nonnull;
import javax.annotation.Nullable;

/**
 * Represents a piece of content (or data) provided by a content fragment.
 *
 * In general, {@code FragmentData} works as a wrapper around a (generic) Java object
 * that represents the actual value. This avoids using {@code Object} in the API and also
 * allows to provide helper functionality to access the generic value in a controlled way.
 * 
 *
 * Values are typed. For more information about data types, see {@link DataType}.
 *
 * Values of a given type - represented by an {@code Object} wrapped by
 * {@link FragmentData} - may need to be converted to the needs of the client. Basically,
 * {@link FragmentData#getValue(Class)} supports to convert each value to a {@code String}
 * (and back).
 *
 * For the conversion to a {@code String} the following rules are followed:
 *
 * 
 *     
 *         The conversion of numbers is technical, i.e. based on
 *         {@code Xxxx.toString()}/{@code Xxx.parseXxx} rather than {@code NumberFormat}
 *     
 *     
 *         The conversion of {@code Calendar} is based on ISO-8601.
 *     
 * 
 *
 * @since 1.1
 */
@ProviderType
public interface FragmentData {

    /**
     * Gets the data type of the value.
     *
     * @return The data type
     */
    @Nonnull
    DataType getDataType();

    /**
     * Gets the value, converted to the provided type.
     *
     * For information about supported type conversions: see {@link DataType}.
     *
     * Note that this method is supposed to return a suitably converted value for all
     * types where {@link #isTypeSupported(Class)} returns {@code true}
     *
     * @param  Describes the type parameter
     * @param type The type the value should be converted to
     * @return The value; {@code null} if the value could not be converted to the provided
     *         type
     */
    @Nullable
     T getValue(Class type);

    /**
     * Checks if the specified Java data type is supported for calls to
     * {@link #getValue(Class)} and {@link #setValue(Object)}.
     *
     * @param type The class object representing the type
     * @return {@code true} if the type is supported
     */
    boolean isTypeSupported(Class type);

    /**
     * Gets the original value as a generic Java object.
     *
     * @return The value
     */
    @Nullable
    Object getValue();

    /**
     * Sets the value.
     *
     * The general rule is that a non-null value that was retrieved using
     * {@link #getValue(Class)} needs to be accepted and converted to a suitable original
     * value. Also, every value of a type where {@link #isTypeSupported(Class)} returns
     * {@code true} needs to be accepted and converted accordingly.
     *
     * Note that for the value to be persisted,
     * {@link ContentElement#setValue(FragmentData)} or
     * {@link ContentVariation#setValue(FragmentData)} have to be called explicitly.
     * This allows for manipulating the value multiple times before actually persisting it.
     * 
     *
     * @param value The value
     * @throws ContentFragmentException if the type of the value provided is unsupported
     */
    void setValue(@Nullable Object value) throws ContentFragmentException;

    /**
     * Returns the content type for textbased data types.
     *
     * This will return a MIME type only when applicable. For numbers, dates, booleans,
     * it will typically be {@code null}.
     *
     * @return The content type; {@code null} if not applicable
     */
    @Nullable
    String getContentType();

    /**
     * Sets the content type for text-based data types.
     *
     * For data other than text-based types {@code null} should be provided.
     *
     * @param contentType The content type; {@code null} if not applicable
     */
    void setContentType(@Nullable String contentType);

}