com.day.cq.dam.api.AssetManager Maven / Gradle / Ivy

/*
 * Copyright 1997-2009 Day Management AG
 * Barfuesserplatz 6, 4001 Basel, Switzerland
 * All Rights Reserved.
 *
 * This software is the confidential and proprietary information of
 * Day Management AG, ("Confidential Information"). You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Day.
 */
package com.day.cq.dam.api;

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

import aQute.bnd.annotation.ProviderType;

import java.io.InputStream;
import java.util.Calendar;
import java.util.Collection;

import javax.jcr.PathNotFoundException;
import javax.jcr.RepositoryException;

/**
 * The AssetManager provides utility methods for assets.
 * 
 * The asset manager can be retrieved as follows:
 *  *   ...
 *   AssetManager manager = resourceResolver.adaptTo(AssetManager.class);
 *   ...
 * 
 */

@ProviderType
public interface AssetManager {

    /**
     * Restores an {@code Asset}.
     *
     * @param revisionId revision id
     *
     * @return the restored {@link Asset}
     *
     * @throws Exception Upon encountering an error while restoring an asset.
     */
    Asset restore(String revisionId) throws Exception;

    /**
     * Lists all available {@link Revision}s.
     *
     * @param path path of asset
     * @param cal  starting date to search revisions or {@code null} in order to fetch all
     *
     * @return all available {@link Revision}s
     *
     * @throws Exception Upon encountering an error while getting the revisions for an asset.
     */
    Collection getRevisions(String path, Calendar cal) throws Exception;

    /**
     * This method creates the complete asset structure in /content/dam. The following structure is created:
     * <xmp> + file.jpg (dam:Asset) + jcr:content )(dam:AssetContent) + renditions (sling:OrderedFolder) + metadata
     * (nt:unstructured)
     * 
     * </xmp>
     * 
     * The given binaryPath is translated into the final asset location (see {@link
     * com.day.cq.dam.commons.util.DamUtil#binaryToAssetPath(String)}).
     * 
     *
     * @param binaryPath The path of the asset's binary in /var/dam.
     * @param doSave     Whether the repository changes are saved or not.
     *
     * @return The newly created asset or {@code null} if the binaryPath cannot be handled
     */
    Asset createAssetForBinary(String binaryPath, boolean doSave);

    /**
     * Returns the {@link Resource} of the {@link Asset} corresponding to the binary given with the path
     * parameter.
     *      *   DamUtil.getAssetNode("/var/dam/myfolder/test.jpg", session)    =  Resource("/content/dam/myfolder/test.jpg")
     * 
     *
     * @param binaryPath The path of the binary.
     *
     * @return The resource representing the binary's asset, or null if it couldn't be found.
     */
    Asset getAssetForBinary(String binaryPath);

    /**
     * Removes the {@link javax.jcr.Node} of the {@link Asset} corresponding to the binary given with the
     * path parameter.
     *      *   DamUtil.removeAssetNode("/var/dam/myfolder/test.jpg", session) =i> Delete Node("/content/dam/myfolder/test.jpg")
     * 
     *
     * @param binaryPath The path of the binary.
     *
     * @return true if the asset was successfully removed.
     */
    boolean removeAssetForBinary(String binaryPath);

    /**
     * Creates a new {@link Asset} at the given path. If an asset
     * already exists at the given path, its original rendition is
     * updated instead of creating a new asset. If inputStream is null new
     * {@link Asset} is created without original rendition. If an asset already
     * exists at given path and inputstream is null, original rendition is not
     * updated.
     *
     * @param path The path of the asset to be created.
     * @param is The input stream of the new asset's original binary.
     * @param mimeType The mime type of the new asset's original binary.
     * @param doSave Whether the repository changes are saved or not.
     * @return The newly created asset or {@code null} if something exists at the given path already
     *         or there was an unexpected error
     */
    Asset createAsset(String path, InputStream is, String mimeType, boolean doSave);

    /**
     * Create a new {@link Revision} of the asset. The revision will be created as a standard JCR version of the
     * underlying asset node.
     *
     * @param asset   The asset to version
     * @param label   version label
     * @param comment version comment
     *
     * @return The created revision
     *
     * @throws Exception Thrown when an error during version creation occurred.
     */
    Revision createRevision(Asset asset, String label, String comment) throws Exception;

    /**
     * Ask Asset ID Provider (associated with Asset Manager) to assign ID
     * (if needed) to an asset and establish its parentage (dam:parentAssetID)
     *
     * @param asset   The asset to update
     *
     * @throws RepositoryException
     * @throws PathNotFoundException
     */
    String assignAssetID(Asset asset) throws PathNotFoundException, RepositoryException;
}