com.day.cq.dam.api.handler.AssetHandler 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.handler;
import com.adobe.granite.asset.api.AssetRelation;
import com.day.cq.dam.api.Asset;
import com.day.cq.dam.api.AssetHandlerException;
import com.day.cq.dam.api.Rendition;
import com.day.cq.dam.api.metadata.ExtractedMetadata;
import com.day.cq.dam.api.thumbnail.ThumbnailConfig;
import javax.jcr.Node;
import javax.jcr.Session;
import java.awt.Dimension;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
/**
* The AssetHandler inteface specifies the handling of assets, specifically during importing or updating
* the binary of an asset.
*/
public interface AssetHandler {
/**
* Indicates if the handler supports processing of sub assets
*
* @return true if handler is able to process sub assets
*/
boolean canHandleSubAssets();
/**
* Thumbnails of an asset are created during import/update of an asset and it's original binary. Currently this
* method is used by the {@link com.day.cq.dam.core.process.CreateThumbnailProcess} and the {@link
* com.day.cq.dam.core.process.CommandLineProcess} as part of the DAM Update Asset workflow. Implementations
* may choose to create asset thumbnails for every entry in the thumbnailConfigs list argument, to not
* create any thumbnails at all, or to create a generic thumbnail independent of the given config. Thumbnails
* themselves are renditions of an asset and must be persisted as such (see {@link
* com.day.cq.dam.api.Asset#addRendition(String, java.io.InputStream, String)}).
*
* The thumbnail renditions are created depending on the given configuration list:
*
* {
* height:h1,
* width: w1,
* doCenter: true (or false)
* },
* {
* ...
* }
*
* Sample:
*
* ...
* final ArrayList<Map<String, Object>> config = new ArrayList<Map<String, Object>>();
*
* config.add(new HashMap<String, Object>() {{
* put("width", 140);
* put("height", 100);
* put("doCenter", true);
* }});
* config.add(new HashMap<String, Object>() {{
* put("width", 80);
* put("height", 80);
* put("doCenter", true);
* }});
*
* handler.createThumbnailsExt(
* getTiff(),
* asset.adaptTo(Node.class).getNode("jcr:content/renditions"),
* session,
* config);
* ...
*
*
* @param asset the asset/file for which the thumbnails are generated
* @param configs thumbnail configurations
* @throws IOException is thrown in case while an error occurred while fetching the image
* @see com.day.cq.dam.api.Asset#addRendition(String, java.io.InputStream, String)
* @see com.day.cq.dam.api.Asset#getRenditions()
* @see com.day.cq.dam.api.Asset#getRendition(String) )
* @see com.day.cq.dam.api.Asset#getRendition(com.day.cq.dam.api.RenditionPicker)
* @since 5.4.0
*/
void createThumbnails(Asset asset, Collection configs) throws IOException;
/**
* Creates thumbnails for this asset. Which thumbnails are created is automatically derived from the existing
* thumbnails (renditions with the cq5dam.thumbnail prefix). This essentially amounts to re-creating existing
* thumbnails.
*
* @param asset The asset for which to create thumbnails.
* @throws java.io.IOException If an error occurred while extracting the image.
*/
void createThumbnails(Asset asset) throws IOException;
/**
* Creates thumbnails for an {@link Asset}s particular {@link Rendition}.
*
* @param asset The asset for which to created thumbnails.
* @param rendition The rendition serving as the thumbnail basis.
* @param configs The thumbnail configurations.
* @throws IOException If an error occurred extracting an image from the rendition.
*/
void createThumbnails(Asset asset, Rendition rendition, Collection configs) throws IOException;
/**
* This method exports the asset into the given OutputStream. The {@link Asset}s original binary is
* served.
*
* @param asset The asset to export.
* @param stream The output stream to export into.
* @throws AssetHandlerException If an error occurred during export.
* @since 5.4.0
*/
void exportAsset(Asset asset, OutputStream stream) throws AssetHandlerException;
/**
* This method is used by the {@link com.day.cq.dam.core.process.ExtractMetadataProcess} as part of the DAM
* Update Asset workflow during import or update of an asset. Implementations must return an {@link
* com.day.cq.dam.api.metadata.ExtractedMetadata} object, which may be empty if no metadata is extracted, or
* contains the metadata values extracted from the binary being imported/updated at the time. The
* ExtractMetadataProcess will later save the metadata contained in ExtractedMetadata to
* the asset's metadata node (e.g. /content/dam/geometrixx/banners/banner-mono.png/jcr:content/metadata).
* Implementations are free to decide which and how many metadata values are extracted.
*
* The method argument represents the {@link javax.jcr.Node} of type nt:file holding the binary content or
* the DAM Asset node (type dam:Asset), for which its original rendition would be retrieved.
*
* @param asset The {@link Asset}, from whose original binary metadata will extracted.
* @return The extracted metadata.
* @since 5.4.0
*/
ExtractedMetadata extractMetadata(Asset asset);
/**
* This method retrieves the graphical representation of an {@link Asset}s given {@link Rendition}. For images the
* BufferedImage of the original image is returned, for other formats the first page is retrieved as
* BufferedImage
*
* @param rendition The rendition for which to retrieve its graphical representation.
* @return BufferedImage if a graphical representation exists, otherwise null
* @throws java.io.IOException in case an error is thrown while fetching the buffered image
* @since 5.4.0
*/
BufferedImage getImage(Rendition rendition) throws IOException;
/**
* This method retrieves the graphical representation of an {@link Asset}s given {@link Rendition}. For images the
* BufferedImage of the original image is returned, for other formats the first page is retrieved as
* BufferedImage.
*
* If maxDimension is given, the handler should return an
* image where no dimension extends the given value. This can be used to reduce
* the memory footprint of large buffered images if the full resolution is not needed.
*
* @param rendition The rendition for which to retrieve its graphical representation.
* @param maxDimension optional constraint for the maximal dimension of the image.
* @return BufferedImage if a graphical representation exists, otherwise null
* @throws java.io.IOException in case an error is thrown while fetching the buffered image
* @since 5.4.0
*/
BufferedImage getImage(Rendition rendition, Dimension maxDimension) throws IOException;
/**
* This method returns the mime types a particular AssetHandler supports.
*
* @return mime type, e.g. image/jpg
*/
String[] getMimeTypes();
/**
* Handler implementations may choose to support sub asset creation for the file types it handles. The method is
* called by the {@link com.day.cq.dam.core.process.CreateSubAssetsProcess} during import/update of an asset and its
* binary, as part of the DAM Update Asset workflow. Sub assets represent fragments of the original asset,
* for example every page of a multi-page PDF document are sub assets. Sub assets are stored as assets themselves
* under the parent asset. Sub assets are stored in the subassets folder of the main asset, e.g. at
* /content/dam/geometrixx/documents/ECM Artikel.pdf/subassets.
*
* The asset argument represents the {@link javax.jcr.Node} of type nt:file holding the binary
* content or the DAM Asset node (type dam:Asset), for which its original rendition would be retrieved.
*
* @param asset asset to extract sub assets
* @return List constaining all paths to the newly created assets
* @see #canHandleSubAssets()
* @see com.day.cq.dam.api.Asset#isSubAsset()
*/
List processSubAssets(Asset asset);
/**
* extracts and stores the links to the assets related with provided asset.
*
* @param asset asset to process
*
* @return Iterator of {@link AssetRelation} or an empty iterator if no related assets are available
* */
Iterator processRelated(Asset asset);
}