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 Details

    • 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:

    • 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:

    • 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

      Map<String,Object> getMetadata()
      Returns all available metadata as map.
      Returns:
      metadata
      See Also:

    • setRendition

      @Deprecated Resource setRendition(String name, InputStream is, 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:

    • 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:

    • 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
      invalid reference 
      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
      invalid reference 
      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:

    • addRendition

      Rendition addRendition(String name, InputStream is, Map<String,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:

    • 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.