DAM API
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 Magnolia Assets subapp.
Key features of DAM API:
-
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.
Architecture
The diagram provides an overview of how the main interfaces and classes of the DAM API relate.
Interfaces
-
info.magnolia.dam.api.AssetProviderRegistry is the main entry point. Given an
ItemKey
orMediaType
, it is responsible for finding the correctAssetProvider
andAssetRenderer
. -
info.magnolia.dam.api.AssetProvider: Exposes
Folders
andAssets
from a particular source. Specifics of the storage of these items are left to implementations. While most provider implementations only use theItemKey.assetId
field of keys passed to the variousget
methods, the entire key object is passed for consistency and flexibility. This makes it possible to implement, for example, delegating and aggregating providers. -
info.magnolia.dam.api.PathAwareAssetProvider: 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 termpath
here should be taken with a pinch of salt. It could, for example, be a single name or arelative
path if the provider serves assets from a subset of its underlying data source. -
info.magnolia.dam.api.AssetRenderer: Provides
AssetRenditions
by bridging an asset’s data and some type of converter.AssetRenderers
can be provided byAssetProviders
if theAssetProvider
itself (or the underlying system) is capable of managing the conversion/translation, or via aglobal
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. -
info.magnolia.dam.api.Asset: An
Asset
is a digital resource with associated metadata. -
info.magnolia.dam.api.Folder: A
Folder
represents a structural item holdingAssets
. 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. -
info.magnolia.dam.api.Item: Defines a common interface for
Asset
andFolder
. -
info.magnolia.dam.api.AssetQuery: Represents a query to an
AssetProvider
. Use newAssetQuery.Builder()…build()
to construct instances. -
info.magnolia.dam.api.AssetRendition: An
AssetRendition
is aview
on a asset for a specificMediaType
. It can be a simple resize of an image, or a document conversion.
Enum
-
info.magnolia.dam.api.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.
PathAwareAssetProvider
forhierarchical
). If support for write operations is added, this enum will be extended with new capabilities.
Classes
-
info.magnolia.dam.api.AbstractAssetProvider: Convenient abstract base class for implementations. Enables configurations of
MediaType
that the implementedAssetProvider
provides. -
info.magnolia.dam.api.AbstractItem: Common superclass for any DAM
Item
. -
Builder
: A builder forAssetQuery
that provides a fluent API. -
info.magnolia.dam.api.ItemKey: A composite key. In the DAM, every
Asset
andFolder
are 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
-
info.magnolia.dam.api.metadata.AssetMetadata: A common interface for asset metadata. Different types of metadata can be exposed through
Asset
by extending this interface. TheAssetProvider
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 anAsset
by passing the specific type of metadata, i.e, a class object that extends this interface. -
info.magnolia.dam.api.metadata.DublinCore: 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
. -
info.magnolia.dam.api.metadata.MagnoliaAssetMetadata: 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, usewithoutParameters()
.
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 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
hascapabilities
(info.magnolia.dam.api.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). -
ItemKey
is a specific type (composed ofproviderId
andassetId
) rather than amagic string
. It is passed to most methods, rather than theassetId
string. This allows for aggregation/delegation in specialized providers.
AssetProviders
are registered by configuration in the
DAM
Core module.
Items, assets and folders
-
Item
is the main parent definition of aFolder
and anAsset
. -
Asset
is the abstract representation of a binary document. -
Folder
is the abstract representation of a folder that containsAsset
.
AssetRenditions and MediaTypes
An AssetRendition
is a transformation of an Asset
. The
AssetRenderer
provides AssetRenditions
by bridging an Assets
data
and some type of converter.
-
AssetRenderer
can be provided byAssetProvider
when the conversion/translation can be managed by theAssetProvider
itself (or its underlying system), or via aglobal
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.
AssetRenderers
are registered by configuration in the
DAM
Core module.
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.
JCR classes
-
info.magnolia.dam.jcr.JcrAssetProvider:
AssetProvider
that delivers assets for thedam
workspace. ExtendsAbstractAssetProvider
and implementsPathAwareAssetProvider
. -
info.magnolia.dam.jcr.AbstractJcrItem: JCR implementation of an
Item
. ExtendsAbstractItem<JcrAssetProvider>
. -
info.magnolia.dam.jcr.JcrAsset: JCR implementation of the
Asset
definition. ExtendsAbstractJcrItem
. -
info.magnolia.dam.jcr.JcrFolder: JCR implementation of the
Folder
definition. ExtendsAbstractJcrItem
. -
info.magnolia.dam.jcr.AssetNodeTypes: Constants and convenience methods for asset node types.
-
Asset
: Represents the node typemgnl:asset
. Fields:caption
,comment
,copyright
,description
,language
,master
,name
,provider_type
,subject
,title
,type
. -
AssetResource
: Represents the resource node bound to anAsset
. Fields:data
,extension
,filename
,height
,mimetype
,name
,ressource_name
,size
,width
.
-
-
info.magnolia.dam.jcr.JcrItemNodeTypePredicate: Predicate filtering asset 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>
.
-
info.magnolia.dam.jcr.DamConstants: 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, info.magnolia.dam.jcr.JcrAsset provides a public getter:
/** * 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);
JCR metadata classes
-
info.magnolia.dam.jcr.metadata.JcrDublinCore: JCR implementation of
DublinCore
. Fields:dc_contributor
,dc_coverage
,dc_creator
,dc_publisher
,dc_relation
,dc_source
,dc_subject
,dc_type
. Methods:getContributor
,getCoverage
,getCreated
,getCreator
,getDate
,getDescription
,getFormat
,getIdentifier
,getLanguage
,getModified
,getPublisher
,getRelation
,getRights
,getSource
,getSubject
,getTitle
,getType
. -
info.magnolia.dam.jcr.metadata.JcrMagnoliaAssetMetadata: Base JCR implementation of the
MagnoliaAssetMetadata
definition. Methods:getHeight
,getWidth
.
DAM templating functions
As a template developer, have a look at
damfn
, a
set of methods that can be used in FreeMarker scripts to easily access
assets, asset renditions, etc.