com.day.cq.dam.api

Interface Asset

All Superinterfaces:

Adaptable

@ProviderType
public interface Asset
extends Adaptable

The Asset interface describes the digital asset with its methods.

Method Summary

Modifier and Type	Method and Description
Rendition	addRendition(java.lang.String name, Binary binary, java.util.Map<java.lang.String,java.lang.Object> map) Adds/replaces a Rendition with given binary for supporting oak direct binary.
Rendition	addRendition(java.lang.String name, Binary binary, java.lang.String mimeType) Adds/replaces a Rendition with given binary for supporting oak direct binary.
Rendition	addRendition(java.lang.String name, java.io.InputStream is, java.util.Map<java.lang.String,java.lang.Object> map) Adds/replaces a Rendition.
Rendition	addRendition(java.lang.String name, java.io.InputStream is, java.lang.String mimeType) Adds/replaces a Rendition.
Asset	addSubAsset(java.lang.String name, java.lang.String mimeType, java.io.InputStream stream) Adds/replaces a sub-asset to this asset.
Revision	createRevision(java.lang.String label, java.lang.String comment) Create a new Revision of the asset.
Revision	createRevision(java.lang.String label, java.lang.String comment, User versionCreator) Create a new Revision of the asset.
Rendition	getCurrentOriginal() Deprecated. Will be removed without replacement. The concept of current originals will henceforth be managed through versioning the asset upon modifying the original. Use getOriginal() instead.
java.lang.String	getID() This method returns the ID associated with an Asset Returns the non-null String value of Asset's ID May return an empty (non-null) string
Rendition	getImagePreviewRendition() This method returns a suitable Rendition for rendering image rendition derivatives (thumbnails, previews, ptiff).
long	getLastModified() Returns the date of last modification of the asset's main content node (jcr:lastModified property).
java.util.Map<java.lang.String,java.lang.Object>	getMetadata() Returns all available metadata as map.
java.lang.Object	getMetadata(java.lang.String name) Returns the generic metadata value of an asset by the given property name.
java.lang.String	getMetadataValue(java.lang.String name) Returns the metadata String value of an asset by the given property name.
java.lang.String	getMetadataValueFromJcr(java.lang.String name) This method is different from getMetadataValue(java.lang.String) as it doesn't fallback to parse xmp in asset if property not found in JCR.
java.lang.String	getMimeType() Returns the mime type of the asset's original binary.
java.lang.String	getModifier() Returns the name of the modifier who modified the asset last
java.lang.String	getName() Returns the name of the asset.
Rendition	getOriginal() Returns the asset's original as a Rendition.
java.lang.String	getPath() Returns the repository path of the asset.
Rendition	getRendition(RenditionPicker picker) Returns the Rendition, based on a custom RenditionPicker implementation.
Rendition	getRendition(java.lang.String name) This method returns the Rendition specified by its name.
java.util.List<Rendition>	getRenditions() Returns a list of all Renditions of this asset.
java.util.Collection<Revision>	getRevisions(java.util.Calendar cal) Returns the revisions available for the current asset.
java.util.Collection<Asset>	getSubAssets() Returns all sub-assets that exist for this asset.
void	initAssetState() This method initializes DamConstants.DAM_ASSET_STATE property to DamConstants.DAM_ASSET_STATE_UNPROCESSED on the current asset.
boolean	isBatchMode() Indicates whether batch mode is enabled or not.
boolean	isSubAsset() Indicates if this asset is a Sub Asset.
java.util.Iterator<Rendition>	listRenditions() Returns an iterator for all Renditions of this asset.
void	removeRendition(java.lang.String name) Removes the rendition identified by name
Asset	restore(java.lang.String revisionId) Restores a revision of this asset as identified by the given revisionId.
void	setBatchMode(boolean mode) Mark this asset as being part of a batch-mode process.
void	setCurrentOriginal(java.lang.String name) Deprecated. Will be removed without replacement.
Resource	setRendition(java.lang.String name, java.io.InputStream is, java.lang.String mimeType) Deprecated. Use addRendition(String, java.io.InputStream, String) instead.

Methods inherited from interface org.apache.sling.api.adapter.Adaptable

adaptTo

Method Detail

getPath

java.lang.String getPath()

Returns the repository path of the asset.

Returns:

path of the asset.

getName

java.lang.String getName()

Returns the name of the asset.

Returns:

page name

getMetadataValue

java.lang.String getMetadataValue(java.lang.String name)

Returns the metadata String value of an asset by the given property name. Note: Falls back to parse xmp in asset if property not found in JCR. Use of getMetadataValueFromJcr(java.lang.String) is recommended over this method

Retrieving a metadata value works as follows:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      String assetTitle = asset.getMetadataValue("dc:title");
      ...
 

Parameters:

name - metadata property name

Returns:

the value or an empty string if the metadata property does not exist.

getMetadata

java.lang.Object getMetadata(java.lang.String name)

Returns the generic metadata value of an asset by the given property name. Falls back to parse xmp in asset if property not found in JCR.

As asset metadata values are JCR repository based, a value may be of any type supported by the repository. As such for example a Calendar type property may be retrieved:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      Calendar modified = (Calendar) asset.getMetadata(DamConstants.PN_MODIFIED);
      ...
 

Parameters:

name - metadata property name

Returns:

the Object or null if the property does not exist.

getLastModified

long getLastModified()

Returns the date of last modification of the asset's main content node (jcr:lastModified property).

Returns:

lastmodified date as long

getRendition

Rendition getRendition(java.lang.String name)

This method returns the Rendition specified by its name. Available renditions are configured as part of the DAM Asset Update Workflow (see: http://dev.day.com/docs/en/cq/current/dam/customizing_and_extendingcq5dam.html#Customizing%20Renditions).

Renditions are stored under the asset's main content node in the "renditions" folder, e.g. /content/dam/geometrixx/banners/banner-mono.png/jcr:content/renditions. The node name of a rendition in this folder is the name to be used as the method argument. For example the rendition path /content/dam/geometrixx/banners/banner-mono.png/jcr:content/renditions/cq5dam.thumbnail.140.100.png results in the rendition name "cq5dam.thumbnail.140.100.png". Sample:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      Resource rendition = asset.getRendition("cq5dam.thumbnail.140.100.png");
      ...
 

Parameters:

name - rendition name

Returns:

the rendition or null

See Also:

getRenditions(), getRendition(RenditionPicker)

getImagePreviewRendition

Rendition getImagePreviewRendition()

This method returns a suitable Rendition for rendering image rendition derivatives (thumbnails, previews, ptiff). If a suitable rendition can't be found, the method will return the original rendition as a fallback.

Returns:

Preview rendition, original rendition, or null if the original rendition doesn't exist.

getOriginal

Rendition getOriginal()

Returns the asset's original as a Rendition. The original represents the binary file that was initially uploaded as the asset. It is the unmodified version of the asset. The original also represents a rendition of the asset, as such its storage path is in the asset's rendition folder, e.g. /content/dam/geometrixx/banners/banner-mono.png/jcr:content/renditions/original. The original, as any rendition, is persisted as a node of type nt:file in the repository. Subsequently access to the original's file data works through accessing its jcr:content subnode via resource API, or using the Download or Image class. The Download and Image convenience classes automatically retrieve the rendition with the name original from the given asset resource.

Using the resource API:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      Resource original = asset.getOriginal();
      InputStream stream = original.adaptTo(InputStream.class);
      ...
 

Using the asset as a download via the Download class:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      Download download = new Download(resource);
      String title = download.getTitle();
      String mimeType = download.getMimeType();
      javax.jcr.Property p = download.getData();
      javax.jcr.Binary b = p.getBinary();
      long size = b.getSize();
      InputStream stream = b.getStream();
      ...
 

Using the asset's original as an image via the Image class:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      Image image = new Image(resource);
      Layer layer = image.getLayer(true, true, true);
      ...
 

Returns:

file resource of the original file, or null if the original resource doesn't exist.

getCurrentOriginal

@Deprecated
Rendition getCurrentOriginal()

Deprecated. Will be removed without replacement. The concept of current originals will henceforth be managed through versioning the asset upon modifying the original. Use getOriginal() instead.

Returns the Rendition representing the asset's rendition currently marked as the asset's unmodified, original version. A rendition is marked as the original of an asset via the existence of the property currentOriginal on the asset's content node. The property contains the path of the rendition to be considered the original. E.g. /content/dam/geometrixx/banners/banner-mono.png/jcr:content/currentOriginal with value /content/dam/geometrixx/banners/banner-mono.png/jcr:content/renditions/myOriginal.

Returns:

current original rendition

See Also:

getOriginal()

isSubAsset

boolean isSubAsset()

Indicates if this asset is a Sub Asset. Sub assets are assets stored under another asset, as a result of splitting up the asset in fragments during its import, e.g. the single pages of a multi-page PDF file.

Returns:

true if it is a Sub Asset

getMetadata

java.util.Map<java.lang.String,java.lang.Object> getMetadata()

Returns all available metadata as map.

Returns:

metadata

See Also:

getMetadataValue(String)

setRendition

@Deprecated
Resource setRendition(java.lang.String name,
                                  java.io.InputStream is,
                                  java.lang.String mimeType)

Deprecated. Use addRendition(String, java.io.InputStream, String) instead.

Saves a new rendition and returns the newly saved file Resource. The modification date of the asset will be set automatically.

Parameters:

name - rendition name

is - InputStream of rendition

mimeType - The mime type of the rendition

Returns:

rendition as resource

Since:

5.3

See Also:

getRendition(String), getRenditions()

setCurrentOriginal

@Deprecated
void setCurrentOriginal(java.lang.String name)

Deprecated. Will be removed without replacement.

Defines which rendition is marked as the asset's original version.

Parameters:

name - name of rendition

See Also:

getCurrentOriginal()

createRevision

Revision createRevision(java.lang.String label,
                        java.lang.String comment)
                 throws java.lang.Exception

Create a new Revision of the asset. The revision will be created as a standard JCR version of the underlying asset node. Owner of the session through which Asset was created is added as DamConstants.PN_VERSION_CREATOR of the asset.

Parameters:

label - version label. Note that the version label must be unique across all versions.

comment - version comment

Returns:

The created revision

Throws:

java.lang.Exception - Thrown when an error during version creation occurred.

createRevision

Revision createRevision(java.lang.String label,
                        java.lang.String comment,
                        User versionCreator)
                 throws java.lang.Exception

Create a new Revision of the asset. The revision will be created as a standard JCR version of the underlying asset node. This API allows specifying principal of an AEM User to be added a DamConstants.PN_VERSION_CREATOR of the asset being versioned.

Parameters:

label - version label. Note that the version label must be unique across all versions.

comment - version comment

versionCreator - version creator. If null, this API is equivalent to createRevision(String label, String comment)

Returns:

The created revision

Throws:

java.lang.Exception - Thrown when an error during version creation occurred.

getRenditions

java.util.List<Rendition> getRenditions()

Returns a list of all Renditions of this asset.

Returns:

The renditions.

listRenditions

java.util.Iterator<Rendition> listRenditions()

Returns an iterator for all Renditions of this asset.

Returns:

The renditions.

Since:

5.4

getRendition

Rendition getRendition(RenditionPicker picker)

Returns the Rendition, based on a custom RenditionPicker implementation. RenditionPicker implementations are free to choose which rendition is to be returned.

Parameters:

picker - The RenditionPicker implementation to use for selecting an asset's rendition.

Returns:

the desired rendition or null if not existing.

getModifier

java.lang.String getModifier()

Returns the name of the modifier who modified the asset last

Returns:

modifier userId

restore

Asset restore(java.lang.String revisionId)
       throws java.lang.Exception

Restores a revision of this asset as identified by the given revisionId. If the revision ID does not pertain to the current asset or does not exist, null is returned, otherwise the restored asset.

Parameters:

revisionId - The id of the revision to restore.

Returns:

The restored asset or null if the revision does not exist or doesn't pertain to the asset.

Throws:

java.lang.Exception - If an error is encountered during restoring the asset.

Since:

CQ 5.4.0

getRevisions

java.util.Collection<Revision> getRevisions(java.util.Calendar cal)
                                     throws java.lang.Exception

Returns the revisions available for the current asset. The revisions can be filtered by date. If cal is given, only revisions older or equal to the specified date are returned.

Parameters:

cal - The calendar object to filter the revisions by.

Returns:

The collection of revisions for this asset, or an empty collection if none were found.

Throws:

java.lang.Exception - If an error occurred upon retrieving the revisions.

Since:

CQ 5.4.0

getMimeType

java.lang.String getMimeType()

Returns the mime type of the asset's original binary. If a current original is marked, its mime type will be returned, otherwise the mime type of the asset's original rendition (./jcr:content/renditions/original). If no original could be found, or no mime type is set, null is returned.

Returns:

The mime type of the asset's original binary.

Since:

CQ 5.4.0

addRendition

Rendition addRendition(java.lang.String name,
                       java.io.InputStream is,
                       java.lang.String mimeType)

Adds/replaces a Rendition. The modification date of the asset will be set automatically. If a rendition with the given name already exists, it will be replaced.

Parameters:

name - rendition name

is - InputStream of rendition

mimeType - The mime type of the rendition

Returns:

rendition as resource

Since:

CQ 5.4.0

See Also:

getRendition(String), getRenditions()

addRendition

Rendition addRendition(java.lang.String name,
                       java.io.InputStream is,
                       java.util.Map<java.lang.String,java.lang.Object> map)

Adds/replaces a Rendition. The modification date of the asset will be set automatically. If a rendition with the given name already exists, it will be replaced. Actual creation of rendition is delegated to the RenditionHandler.

Parameters:

name - rendition name

is - InputStream to create this rendition or null if stream is not available

map - to be used by the rendition handler, it must contain RenditionHandler.PROPERTY_ID and optionally more properties as defined/required by the respective RenditionHandler

Returns:

rendition as resource

Since:

CQ 5.6.0

See Also:

getRendition(String), getRenditions(), RenditionHandler, RenditionHandler.PROPERTY_ID, Asset.setRendition(String, InputStream, Map)

addRendition

Rendition addRendition(java.lang.String name,
                       Binary binary,
                       java.lang.String mimeType)

Adds/replaces a Rendition with given binary for supporting oak direct binary. The modification date of the asset will be set automatically. If a rendition with the given name already exists, it will be replaced.

Parameters:

name - rendition name

binary - binary of rendition

mimeType - The mime type of the rendition

Returns:

rendition as resource

Since:

CQ 6.5.0

addRendition

Rendition addRendition(java.lang.String name,
                       Binary binary,
                       java.util.Map<java.lang.String,java.lang.Object> map)

Adds/replaces a Rendition with given binary for supporting oak direct binary. The modification date of the asset will be set automatically. If a rendition with the given name already exists, it will be replaced. It will not delegate the actual creation of rendition to the RenditionHandler like addRendition(String, InputStream, Map)

Parameters:

name - rendition name

binary - binary to create this rendition or null if binary is not available

map - it contain properties for the renditions

Returns:

rendition as resource

Since:

CQ 6.5.0

addSubAsset

Asset addSubAsset(java.lang.String name,
                  java.lang.String mimeType,
                  java.io.InputStream stream)

Adds/replaces a sub-asset to this asset. If a sub-asset already exists, it will be replaced.

Parameters:

name - The name of the sub-asset.

mimeType - The mime type of the sub-asset's original binary.

stream - The input stream of the sub-asset's original binary.

Returns:

The newly added sub-asset.

Since:

CQ 5.4.0

getSubAssets

java.util.Collection<Asset> getSubAssets()

Returns all sub-assets that exist for this asset.

Returns:

The asset's collection of sub-assets.

Since:

CQ 5.4.0

removeRendition

void removeRendition(java.lang.String name)

Removes the rendition identified by name

Parameters:

name - The name of the rendition.

Since:

CQ 5.4.0

setBatchMode

void setBatchMode(boolean mode)

Mark this asset as being part of a batch-mode process. Setting mode to true causes all changes made to the asset (e.g. via addRendition(String, java.io.InputStream, String) not to be saved. It is then the responsibility of the caller to call a session save. This mode is particularly useful for batch changes to many assets at once with only one save call at the end so as to speed up operations. The only method exempt from batch mode is createRevision(String, String) (will always cause save).

Parameters:

mode - Set to true to enable batch mode for this asset.

isBatchMode

boolean isBatchMode()

Indicates whether batch mode is enabled or not. If batch mode is enabled, any changes to the asset must be saved externally through a session save.

Returns:

Whether batch mode is enabled or not. Default is false.

getMetadataValueFromJcr

java.lang.String getMetadataValueFromJcr(java.lang.String name)

This method is different from getMetadataValue(java.lang.String) as it doesn't fallback to parse xmp in asset if property not found in JCR. Returns the metadata String value of an asset by the given property name. Available property names are defined by the asset editor configuration used for a particular asset (see http://dev.day.com/docs/en/cq/current/dam/customizing_and_extendingcq5dam.html).

Retrieving a metadata value works as follows:

      ...
      Asset asset = resource.adaptTo(Asset.class);
      String assetTitle = asset.getMetadataValue("dc:title");
      ...
 

Parameters:

name - metadata property name

Returns:

the value or an empty string if the metadata property does not exist.

getID

java.lang.String getID()

This method returns the ID associated with an Asset Returns the non-null String value of Asset's ID May return an empty (non-null) string

Returns:

the ID of an asset.

initAssetState

void initAssetState()
             throws RepositoryException

This method initializes DamConstants.DAM_ASSET_STATE property to DamConstants.DAM_ASSET_STATE_UNPROCESSED on the current asset.

Throws:

RepositoryException - Thrown in case of error in initialization.