Package com.day.cq.dam.api

Interface Asset

  • All Superinterfaces:
    Adaptable
    public interface Asset
extends Adaptable
    The Asset interface describes the digital asset with its methods.

    • Method Detail

      • getPath

        String getPath()
        Returns the repository path of the asset.
        Returns:
        path of the asset.

      • getName

        String getName()
        Returns the name of the asset.
        Returns:
        page name

      • getMetadataValue

        String getMetadataValue​(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

        Object getMetadata​(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​(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

      • setCurrentOriginal

        @Deprecated
void setCurrentOriginal​(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​(String label,
                        String comment)
                 throws 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:
        Exception - Thrown when an error during version creation occurred.

      • createRevision

        Revision createRevision​(String label,
                        String comment,
                        User versionCreator)
                 throws 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(java.lang.String,java.lang.String)
        Returns:
        The created revision
        Throws:
        Exception - Thrown when an error during version creation occurred.

      • getRenditions

        List<Rendition> getRenditions()
        Returns a list of all Renditions of this asset.
        Returns:
        The renditions.

      • listRenditions

        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

        String getModifier()
        Returns the name of the modifier who modified the asset last
        Returns:
        modifier userId

      • restore

        Asset restore​(String revisionId)
       throws 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:
        Exception - If an error is encountered during restoring the asset.
        Since:
        CQ 5.4.0

      • getRevisions

        Collection<Revision> getRevisions​(Calendar cal)
                           throws 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:
        Exception - If an error occurred upon retrieving the revisions.
        Since:
        CQ 5.4.0

      • getMimeType

        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​(String name,
                       InputStream is,
                       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​(String name,
                       Binary binary,
                       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​(String name,
                       Binary binary,
                       Map<String,​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

      • setRendition

        Rendition setRendition​(String name,
                       Binary binary,
                       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. The difference with addRendition is this method will not touch the asset state for original rendition
        Parameters:
        name - rendition name
        binary - binary of rendition
        mimeType - The mime type of the rendition
        Returns:
        rendition as resource, return null if for any reason failed to create replace rendition
        Since:
        CQ 6.6.0

      • addSubAsset

        Asset addSubAsset​(String name,
                  String mimeType,
                  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

        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​(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

        String getMetadataValueFromJcr​(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

        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.