com.adobe.granite.asset.api.RenditionHandler Maven / Gradle / Ivy

/*************************************************************************
 *
 * ADOBE CONFIDENTIAL
 * ___________________
 *
 *  Copyright 2012 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 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.granite.asset.api;

import org.apache.sling.api.resource.Resource;

import java.io.InputStream;
import java.util.Map;

/**
 * The RenditionHandler interface defines the API for rendition handlers. Each RenditionHandler
 * must be identifiable via a unique ID 'rendition.handler.id'.
 * 
 * RenditionHandler is used by the Asset API to delegate Access, Creation & Deletion of {@link Rendition}.
 * 

 * Implementations of this interface must be registered as OSGi services.
 * 
 */
public interface RenditionHandler {

    /**
     * PROPERTY_ID must be set by the implementation class as an OSGi service property
     * This is used by the Asset API to identify RenditionHandler
     * */
    public static final String PROPERTY_ID = "rendition.handler.id";

    /**
     * This property constant defines a property key for the mime type. This can be used by the
     * RenditionHandler or the API clients to define the mime type of the Rendition
     *      *    For example, if the rendition handler requires mime type:
     *      final Map<String, Object> map = new HashMap<String, Object>();
     *      map.put(RenditionHandler.PROPERTY_RENDITION_MIME_TYPE, "image/gif");
     *      ....
     *      asset.setRendition("image.gif", InputStream, map);
     *
     * 
     * */
    public static final String PROPERTY_RENDITION_MIME_TYPE = "rendition.mime";

    /**
     * Get Rendition. Implementations are expected to type the given {@link Resource} to Rendition.
     *
     * @param resource Rendition resource
     *
     * @return Rendition object of the given resource
     * */
    Rendition getRendition(Resource resource);

    /**
     * Set Rendition. Implementations are free to define Resource data structure.
     *
     * @param resource Rendition resource
     * @param is InputStream to create the rendition binary or null
     * @param map containing values needed by this handler.
     *
     * @return newly created or updated rendition
     *
     * @throws AssetException if Rendition cannot be set
     * */
    Rendition setRendition(Resource resource, InputStream is, Map map);


    /**
     * Delete the rendition resource. Implementations are free to decide the semantics of deletion.
     *
     * @param resource To be deleted
     *
     * @throws AssetException if Rendition cannot be deleted
     * */
    void deleteRendition(Resource resource);
}