Page History

Architecture

The diagram provides an overview of how the main interfaces and classes of the DAM API relate.

Interfaces

• Javadoc resource link
  0 info.magnolia.dam.api.AssetProviderRegistry className info.magnolia.dam.api.AssetProviderRegistry renderType asynchronous

  is the main entry point. Given an ItemKey or MediaType it is responsible for:
  
  • Finding the correct AssetProvider.
  • Finding the correct AssetRenderer.

• Javadoc resource link
  0 info.magnolia.dam.api.AssetProvider className info.magnolia.dam.api.AssetProvider renderType asynchronous

  : Exposes Folders and Assets from a particular source. Specifics of the storage of these items are left to implementations. While most provider implementations only use the ItemKey.assetId field of keys passed to the various get methods, the entire key object is passed for consistency and flexibility. This makes it possible to implement, for example, delegating and aggregating providers.

• Javadoc resource link
  0 info.magnolia.dam.api.PathAwareAssetProvider className info.magnolia.dam.api.PathAwareAssetProvider renderType asynchronous

  : Exposes specific operations for AssetProviders that are aware of paths, for example JCR, CMIS, File system etc. Not all providers need or want to implement these features. The term "path" here should be taken "with a pinch of salt". It could, for example, be a single name or a "relative" path if the provider serves assets from a subset of its underlying data source.

• Javadoc resource link
  0 info.magnolia.dam.api.AssetRenderer className info.magnolia.dam.api.AssetRenderer renderType asynchronous

  : Provides AssetRenditions by bridging an asset's data and some type of converter. AssetRenderers can be provided by AssetProviders if the AssetProvider itself (or the underlying system) is capable of managing the conversion/translation, or via a "global" registry. AssetProviderRegistry.getRendererFor(info.magnolia.dam.api.Asset, com.google.common.net.MediaType) provides the entry point. It looks up in provider, then in its own registry, and bridges to other possible conversion mechanisms that are independent of Magnolia DAM.

• Javadoc resource link
  0 info.magnolia.dam.api.Asset className info.magnolia.dam.api.Asset renderType asynchronous

  : An Asset is a digital resource with associated metadata.

• Javadoc resource link
  0 info.magnolia.dam.api.Folder className info.magnolia.dam.api.Folder renderType asynchronous

  : A Folder represents a structural item holding Assets. Depending on the provider, this can be directly mapped to the concept of folders/directories (JCR, FileSystems etc.), and for other types it may map to the concept of albums, playlists, sets, etc.

• Javadoc resource link
  0 info.magnolia.dam.api.Item className info.magnolia.dam.api.Item renderType asynchronous

  : Defines a common interface for Asset and Folder. 

• Javadoc resource link
  0 info.magnolia.dam.api.AssetQuery className info.magnolia.dam.api.AssetQuery renderType asynchronous

  : Represents a query to an AssetProvider. Use new AssetQuery.Builder()...build() to construct instances. 

• Javadoc resource link
  0 info.magnolia.dam.api.AssetRendition className info.magnolia.dam.api.AssetRendition renderType asynchronous

  : An AssetRendition is a "view" on a asset for a specific MediaType . It can be a simple resize of an image, or a document conversion.

Enum

• Javadoc resource link
  0 info.magnolia.dam.api.AssetProviderCapability className info.magnolia.dam.api.AssetProviderCapability renderType asynchronous

  : Clients can ask a provider if they support a certain feature before attempting to use it. Typically, this would enable/disable certain UI features. In some cases, this will also indicate that client code can cast to a specific interface. (e.g. PathAwareAssetProvider for hierarchical). If support for write operations is added, this enum will be extended with new capabilities. 

Classes

• Javadoc resource link
  0 info.magnolia.dam.api.AbstractAssetProvider className info.magnolia.dam.api.AbstractAssetProvider renderType asynchronous

  : Convenient abstract base class for implementations. Enables configuration of MediaTypes that the implemented AssetProvider provides.

• Javadoc resource link
  0 info.magnolia.dam.api.AbstractItem className info.magnolia.dam.api.AbstractItem renderType asynchronous

  : Common superclass for any dam Item.
  

• Javadoc resource link
  0 info.magnolia.dam.api.AssetQuery.Builder className info.magnolia.dam.api.AssetQuery.Builder renderType asynchronous

  : A builder for AssetQuery that provides a fluent API.
  

• Javadoc resource link
  0 info.magnolia.dam.api.ItemKey className info.magnolia.dam.api.ItemKey renderType asynchronous

  : A composite key. In the DAM every Asset and Folder is identified by its provider's ID and its provider-specific ID (i.e the ID with which the provider can uniquely identify the asset).

Metadata interfaces

• Javadoc resource link
  0 info.magnolia.dam.api.metadata.AssetMetadata className info.magnolia.dam.api.metadata.AssetMetadata renderType asynchronous

  : A common interface for asset metadata. Different types of metadata can be exposed through Asset by extending this interface. The AssetProvider should implement support for those. Specific metadata interfaces should expose methods with explicit names and return types, and ideally provide property descriptions in the Javadocs. Metadata is retrieved through an Asset by passing the specific type of metadata, i.e, a class object that extends this interface.

• Javadoc resource link
  0 info.magnolia.dam.api.metadata.DublinCore className info.magnolia.dam.api.metadata.DublinCore renderType asynchronous

  : A collection of Dublin Core metadata names. Extends AssetMetadata. Methods: getContributor,getCoverage, getCreated, getCreator, getDate, getDescription, getFormat, getIdentifier, getLanguage, getModified, getPublisher, getRelation, getRights, getSource, getSubject, getTitle, getType.

• Javadoc resource link
  0 info.magnolia.dam.api.metadata.MagnoliaAssetMetadata className info.magnolia.dam.api.metadata.MagnoliaAssetMetadata renderType asynchronous

  : Defines Magnolia-specific metadata. Extends AssetMetadata. Methods: getHeight, getWidth.

MediaType

DAM 2.0 introduces the com.google.common.net.MediaType  class included in the Google Guava library. 

Here's the class description from the Guava Javadoc.

Represents an Internet Media Type (also known as a MIME Type or Content Type). This class also supports the concept of media ranges defined by HTTP/1.1. As such, the * character is treated as a wildcard and is used to represent any acceptable type or subtype value. A media type may not have wildcard type with a declared subtype. The * character has no special meaning as part of a parameter. All values for type, subtype, parameter attributes or parameter values must be valid according to RFCs 2045 and 2046.

All portions of the media type that are case-insensitive (type, subtype, parameter attributes) are normalized to lowercase. The value of the charset parameter is normalized to lowercase, but all others are left as-is.

Note that this specifically does not represent the value of the MIME Content-Type header and as such has no support for header-specific considerations such as line folding and comments.

For media types that take a charset the predefined constants default to UTF-8 and have a "_UTF_8" suffix. To get a version without a character set, use withoutParameters() .

Accessing the DAM API

To access AssetProviderRegistry from your custom module, adapt your pom and module descriptor XML files to include a dependency. You can simply inject or use components to access the AssetProviderRegistry

    private final AssetProviderRegistry providerRegistry;
    // By Injection
	@Inject
    public MyFunctions(AssetProviderRegistry providerRegistry) {
        this.providerRegistry = providerRegistry;
    }
	// Or using Components
	public void myCustomMethod() {
        this.providerRegistry = Components.getComponent(AssetProviderRegistry.class);
    }

AssetProvider

• AssetProvider  has “capabilities” (

  Javadoc resource link
  0 info.magnolia.dam.api.AssetProviderCapability className info.magnolia.dam.api.AssetProviderCapability renderType asynchronous

  ). Some implementations will not support all features. This can be used to drive a UI to enable/disable certain actions or UI elements. Implementations should still throw exceptions when those unsupported operations are called. (although this may not consistently be the case, for example when aggregating search results from different providers.)
• ItemKey  is a specific type (composed of provider id and asset id) rather than a "magic string". It is passed to most methods, rather than the assetID string. This allows for aggregation/delegation in specialized providers.

Items, assets and folders

• Item is the main parent definition of a Folder and an Asset .
• Asset is the abstract representation of an binary document:
• Folder is  the abstract representation of a folder that contains Asset

Implementation notes:

• To some extent, Items, Folders and Assets mimic the JCR API, but there are subtle differences that are highlighted in the Javadocs.
  
• Items, Folders and Assets   are meant to be implemented "lazily". Implementations will typically keep a reference to their provider. For example, the JCR implementation simply keeps a reference to the corresponding Node instance, and delegates to it "on demand". 

AssetRenditions and MediaTypes

An AssetRendition is a transformation of an Asset. The AssetRenderer provides AssetRenditions by bridging an Asset's data and some type of converter.

• AssetRenderer  can be provided by AssetProvider when the conversion/translation can be managed by the AssetProvider itself (or its underlying system), or via a "global" registry.
• AssetProviderRegistry.getRendererFor(Asset  asset,MediaType mediaType) , provides the entry point. It looks up in the provider then in its own registry, and bridges to other possible conversion mechanisms that are  independent of the Magnolia DAM.

JCR API

The DAM JCR API classes reside in the DAM JCR module and implement the DAM API for JCR assets that are stored in the dam workspace and accessible in the Assets app <link>.

JCR classes

• Javadoc resource link
  0 info.magnolia.dam.jcr.JcrAssetProvider className info.magnolia.dam.jcr.JcrAssetProvider renderType asynchronous

  : AssetProvider that delivers assets for the dam workspace. Extends AbstractAssetProvider and implements PathAwareAssetProvider. 

• Javadoc resource link
  0 info.magnolia.dam.jcr.AbstractJcrItem className info.magnolia.dam.jcr.AbstractJcrItem renderType asynchronous

  : JCR implementation of an Item. Extends AbstractItem<JcrAssetProvider>. 

• Javadoc resource link
  0 info.magnolia.dam.jcr.JcrAsset className info.magnolia.dam.jcr.JcrAsset renderType asynchronous

  : JCR implementation of the Asset definition. Extends AbstractJcrItem.

• Javadoc resource link
  0 info.magnolia.dam.jcr.JcrFolder className info.magnolia.dam.jcr.JcrFolder renderType asynchronous

  : JCR implementation of the Folder definition. Extends AbstractJcrItem.

• Javadoc resource link
  0 info.magnolia.dam.jcr.AssetNodeTypes className info.magnolia.dam.jcr.AssetNodeTypes renderType asynchronous

  : Constants and convenience methods for asset node types.
  
  • Asset: Represents the node type mgnl:asset. Fields: caption, comment, copyright, description, language, master, name, provider_type, subject, title, type.
  • AssetResource: Represent the resource node bound to an Asset. Fields: data, extension, filename, height, mimetype, name, ressource_name, size, width.

• Javadoc resource link
  0 info.magnolia.dam.jcr.JcrItemNodeTypePredicate className info.magnolia.dam.jcr.JcrItemNodeTypePredicate renderType asynchronous

  : Predicate filtering assets nodes (folders and assets) based on the following Node.getPrimaryNodeType():
  
  • AssetNodeTypes.Asset.NAME
  • NodeTypes.Folder#NAME.

Extends info.magnolia.jcr.predicate.AbstractPredicate<javax.jcr.Node>.

• Javadoc resource link
  0 info.magnolia.dam.jcr.DamConstants className info.magnolia.dam.jcr.DamConstants renderType asynchronous

  : Defines commonly used constants for the DAM.JCR module. Fields: default_jcr_provider_id, workspace.

Custom JCR asset properties

In order to access a custom property defined under a JCR Asset node, 

/**
    * JcrAsset specific implementation that lets you access a property value linked to an asset node.
    * This requires an open session.
        * 
       * @return property value Object if the property exists or null otherwise.
       */

    public Object getProperty(String propertyName) {
        return PropertyUtil.getPropertyValueObject(getNode(), propertyName);