The DAM API provides the basic mechanism for the abstraction of the storage location of an asset. The API:
- Allows for external storage providers.
- Is used primarily in templating, templates and models. It provides read-only access to assets managed in the Assets app.
- Clean, simple and basic:
- Flexible, extendable and user-friendly. (You can extend the API and create your own asset providers for external systems.)
- Generic, in the sense that it is not coupled to the JCR.
- Capable of connecting to external asset providers and other systems.
- Supporting Industry standard media types
- It is now possible to plug in external asset providers like Flickr, YouTube and file systems.
The diagram provides an overview of how the main interfaces and classes of the DAM API relate.
- AssetProviderRegistry is the main entry point. Given an
MediaTypeit is responsible for:
- Finding the correct
- Finding the correct
- Finding the correct
- AssetProvider: Exposes
Assets from a particular source. Specifics of the storage of these items are left to implementations. While most provider implementations only use the
ItemKey.assetIdfield of keys passed to the various
getmethods, the entire key object is passed for consistency and flexibility. This makes it possible to implement, for example, delegating and aggregating providers.
- PathAwareAssetProvider: Exposes specific operations for
AssetProvidersthat 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.
- AssetRenderer: Provides
AssetRenditionsby bridging an asset's data and some type of converter.
AssetRendererscan be provided by
AssetProvideritself (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.
- Asset: An
Assetis a digital resource with associated metadata.
- Folder: A
Folderrepresents 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.
- Item: Defines a common interface for
- AssetQuery: Represents a query to an
AssetProvider. Use new
AssetQuery.Builder()...build()to construct instances.
- AssetRendition: An
AssetRenditionis a "view" on a asset for a specific
MediaType. It can be a simple resize of an image, or a document conversion.
- AssetProviderCapability : 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.
hierarchical). If support for write operations is added, this enum will be extended with new capabilities.
- AbstractAssetProvider: Convenient abstract base class for implementations. Enables configuration of
MediaTypes that the implemented
- AbstractItem : Common superclass for any dam
- Builder : A builder for
AssetQuerythat provides a fluent API.
- ItemKey : A composite key. In the DAM every
Folderis identified by its provider's ID and its provider-specific ID (i.e the ID with which the provider can uniquely identify the asset).
- AssetMetadata: A common interface for asset metadata. Different types of metadata can be exposed through
Assetby extending this interface. The
AssetProvidershould 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
Assetby passing the specific type of metadata, i.e, a class object that extends this interface.
- DublinCore: A collection of Dublin Core metadata names. Extends AssetMetadata. Methods:
- MagnoliaAssetMetadata: Defines Magnolia-specific metadata. Extends
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
charsetparameter is normalized to lowercase, but all others are left as-is.
Note that this specifically does not represent the value of the MIME
Content-Typeheader 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
Accessing the DAM API
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
AssetProviderhas “capabilities” (AssetProviderCapability). 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.)
ItemKeyis a specific type (composed of provider id and asset id) rather than a "magic string". It is passed to most methods, rather than the
assetIDstring. This allows for aggregation/delegation in specialized providers.
AssetProviders are registered by configuration in the DAM Core module.
Items, assets and folders
Itemis the main parent definition of a
Assetis the abstract representation of an binary document:
Folderis the abstract representation of a folder that contains
- To some extent,
Assetsmimic the JCR API, but there are subtle differences that are highlighted in the Javadocs.
Assetsare 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
Nodeinstance, and delegates to it "on demand".
AssetRenditions and MediaTypes
Asset's data and some type of converter.
AssetProviderwhen the conversion/translation can be managed by the
AssetProvideritself (or its underlying system), or via a "global" registry.
AssetProviderRegistry.getRendererFor(, 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.
AssetRenderers are registered by configuration in the DAM Core module.
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>.
AssetProviderthat delivers assets for the
- AbstractJcrItem: JCR implementation of an
- JcrAsset: JCR implementation of the
- JcrFolder: JCR implementation of the
- AssetNodeTypes: Constants and convenience methods for asset node types.
Asset: Represents the node type
AssetResource: Represent the resource node bound to an
- JcrItemNodeTypePredicate: Predicate filtering assets nodes (folders and assets) based on the following
- DamConstants: Defines commonly used constants for the DAM.JCR module. Fields:
Custom JCR asset properties
In order to access a custom property defined under a JCR Asset node, JcrAsset provides a public getter:
JCR metadata classes
- JcrDublinCore: JCR implementation of
- JcrMagnoliaAssetMetadata: Base JCR implementation of the
DAM templating functions
As a template developer, also have a look at damfn, a set of methods which can be used in freemarker scripts to easy access assets, asset renditions, and so on.