AEM Dispatcher 4.1.11  Recommended New Features

06 March 2016
Przemyslaw Pakulski

We'd all agree that there's nothing worse than a site that doesn't load quickly and efficiently.  And since load velocity can be hampered by increased traffic, it's vital to have the capability to handle growing demand cost efficiently.  This will mean using your existing infrastructure rather than committing to architectural changes or new hardware. 

That's why Dispatcher is such an important part of the AEM deployment architecture.  It's a caching and load balancing tool, used mainly to ensure the scalability and security of an overall solution.   The latest version, 4.1.11 was released at the end of last year.


(Not) just yet another release

The release cycle of Dispatcher is independent of AEM releases. The product itself is mature and stable but every few months there is a new version, featuring minor changes.

The latest release number suggests that it is a minor maintenance release with small changes and fixes but it is not. After taking a look at the configuration files and doing some tests, I can safely say that it contains some very interesting improvements, which I thought it would be interesting to review.

I'll focus on the three improvements that particularly attracted me and seem to be very useful in practice.


#3 Response headers caching

All previous versions allow for caching the content of files, but do not allow for caching additional information such as headers. To add or control headers you previously had to use additional modules (like mod_rewrite, mod_headers) on the web server.

However, with 4.1.11, it is possible to cache response headers. In fact, it allows you to control various headers from the AEM application directly.

To enable response header caching you need to add the following section with the names of the headers to cache to the dispatcher configuration file:


After applying the above changes, response headers will be stored next to the cached resource, in a file with *.h extension. Next time the cached resource is served from the cache the headers will be added to all subsequent responses.


#2 Auto-invalidation grace period

Auto-invalidation is often used when configuring the dispatcher. This is because the web pages are usually dependent on each other and the change of a single page requires a refresh of other pages. This is when auto-invalidation, a simple built-in mechanism that forces a refresh of the dependent resources, comes into play.

This is not an ideal solution but it works well in many cases. It can also cause some problems, such as an increase in the load of AEM publish instances, because:

  • a large part of the cache can be effectively invalidated at the same time,
  • in the case of multiple content activations over a short period of time (which is often the case),  the cache can be invalidated many times.

However, using the latest release you can configure a grace period for invalidated resources which, to some extent, can mitigate the issues described above.

To enable the auto-invalidation grace period (10 seconds), add the following entry into the configuration file:

/gracePeriod “10”

After configuring, the grace period dispatcher module will delay invalidation of dependent pages for the specified time, serving the resources from the cache for the next 10 seconds. If many resources have been activated within this period of time, subsequent invalidations will be effectively aggregated into a single cache invalidation. The cache hit ratio should increase while a small delay in refreshing related pages is, in most cases, acceptable.

This setting should also help with a more complex scenario in which many AEM publish instances are configured to talk with multiple dispatcher instances. In such a setup, the number of redundant cache invalidations is significantly growing with the number of AEM instances and might be problematic.


#1 Time-based cache invalidation

Content updates and auto-invalidation are the standard, built-in mechanisms of cache invalidation that have been offered by the Dispatcher module for a while now. But what has been missing is cache invalidation based on time.

Not any more - with Dispatcher 4.1.11, time-based cache invalidation is now available.

To enable time-based invalidation add the following entry in the configuration file:

/enableTTL “1”

Then add the header to the HTTP response which specifies the time when the resource should expire from the dispatcher cache.  Two headers are supported by the dispatcher: CacheControl max-age and the Expires date header:

# use CacheControl max-age to specify the relative expiry time in seconds
CacheControl: max-age=60

# use Expires date to specify absolute expiry date
Expires: Thu, 22 Oct 2015 04:01:11 GMT 

You need to set one of these headers programmatically in your AEM project implementation. You can do that, for instance, in the page template script or you can write a custom Java Servlet filter to do that. There are already some tools available which you can use to leverage TTL caching without any development effort:

After configuring the dispatcher module and setting the proper header on the http response, the empty file, with *.ttl extension, is created next to the cached resource. Dispatcher uses this file to compare modification timestamps with the cached resource file, and when the *.ttl file is older, the resource will be re-requested from the AEM publish instance.

Before 4.1.11 was released, to implement TTL based caching frequently, an additional layer of caching was needed, using tools such as Varnish or CDN provider.  The new Dispatcher will not replace these solutions but it will certainly be useful in many scenarios.



I encourage you to use and experiment with the new features and settings of the latest version. It should work with all AEM6 and CQ5 versions.

You can achieve interesting results and improve overall performance at low cost, without investing in architectural changes or more hardware. In fact, in my opinion, the latest Dispatcher release deserves more than just a minor release, it's definitely worth trying.

My final tip - I would suggest avoiding using specific file extensions (*.h,*.ttl) used by Dispatcher for other purposes (at least for clarity).

You can find more detailed information about this module and how it works in the documentation.