Dynamic servlet mapping

Servlet mapping specifies which servlet should be invoked when the client requests a particular URL. In Magnolia, servlet mappings are typically configured in /server/filters/servlets. This is a static way. While creating a component (Java class or Freemarker script), the path to a servlet is hard-coded. When the mapping changes, the hard-coded string literal must be changed too and the software must be re-deployed. To work around this limitation, use dynamic servlet mapping. WARNING: Magnolia 5.3+

Dynamic mapping with SelfMappingServlet

The info.magnolia.cms.filters.SelfMappingServlet interface makes dynamic servlet mapping possible. The interface has one method:

String getSelfMappingPath();

Implement the interface in your own servlet. Instead of returning a hard-coded literal, return something originating in a configuration. Any other Java class such as a model class used in a Freemarker script can then read the value.

Example: DamDownloadServlet

Other components in the system may need to know about servlet mappings. This is the case when generating links for the DAM servlet. DamDownloadServlet implements the SelfMappingServlet interface:


public class DamDownloadServlet extends HttpServlet implements SelfMappingServlet {
    // ... more code here (this is just a snippet)

    public DamDownloadServlet(final DamCoreConfiguration configuration, final AssetProviderRegistry assetProviderRegistry) {
        this.configuration = configuration;
        this.assetProviderRegistry = assetProviderRegistry;

    public String getSelfMappingPath() {
        return configuration.getDownloadPath() + "/*";

The getSelfMappingPath() method returns a value which comes from the DamCoreConfiguration - which could be injected into any other class, too. DamCoreConfiguration#getDownloadPath() is also used in JcrAssetProvider to construct paths for links:


// ... more code here (this is just a snippet)

    public String getLink(final Asset asset) {
        final String contextPath = MgnlContext.getContextPath();
        return contextPath + configuration.getDownloadPath() + asset.getItemKey().asString() + "/" + asset.getFileName();

If for whatever reason the mapped path to the DamDownloadServlet must be changed, there is only one place where the path is adapted: /modules/dam/config/downloadPath in module configuration. The code of DamDownloadServlet and JcrAssetProvider remain the same. This means you don’t need to re-deploy the application. You only need to change configuration on the running system.

You won’t find anything at /modules/dam/config/downloadPath because DamCoreConfiguration#getDownloadPath() has a default value.

DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.