To register a servlet:

Create a servlet class

To create a servlet class, extend javax.servlet.http.HttpServlet. Most servlets extend this class.

HttpServlet provides an abstract class to be subclassed to create an HTTP servlet suitable for a Web site. A subclass of HttpServlet must override at least one method, usually one of these:

  • doGet, if the servlet supports HTTP GET requests
  • doPost, for HTTP POST requests
  • doPut, for HTTP PUT requests
  • doDelete, for HTTP DELETE requests
  • init and destroy, to manage resources that are held for the life of the servlet
  • getServletInfo, which the servlet uses to provide information about itself

There's almost no reason to override the service method. service handles standard HTTP requests by dispatching them to the handler methods for each HTTP request type (the doXXX methods listed above).

Likewise, there's almost no reason to override the doOptions and doTrace methods.

Servlets typically run on multithreaded servers, so be aware that a servlet must handle concurrent requests and be careful to synchronize access to shared resources. Shared resources include in-memory data such as instance or class variables and external objects such as files, database connections, and network connections.

Source: Java EE 5 SDK, Oracle

Additionally, implement 

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") SelfMappingServlet
. This is an optional interface that servlets wrapped by 
$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") ServletDispatchingFilter
 can implement, to provide their own mapping. When implementing this method, the servlet can get the mapping from any arbitrary component. This means the mapping can be configured centrally and re-used by other components, typically to generate links. See Dynamic servlet mapping for more.

Define the servlet in your module descriptor

Define the servlet in your module descriptor . Include any mappings and init parameters the servlet class supports.

Example: The Magnolia core module descriptor (Git) registers the 

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") ClasspathSpool
 servlet. The purpose of this servlet is to serve resource files such as CSS and JavaScript from the mgnl-resources folder of any module when requested with the path /.resources/<module name>.

        <comment>Used to serve resources from the classpath.</comment>

Initialization parameters:

  • name: Name of the servlet.
  • class: Fully-qualified servlet class name.
  • comment: Description of what the servlet does.
  • mappings: URLs and paths that direct requests to the servlet.

(warning) You don't need to add the servlet to your web.xml.


Configure the servlet in the filter chain

Configure the servlet in the servlets filter chain at Configuration > /server/filters/servlets. The configuration is created automatically when the module is installed. The values are taken from the module descriptor.

(warning) Servlets are registered by the

$webResourceManager.requireResource("info.magnolia.sys.confluence.artifact-info-plugin:javadoc-resource-macro-resources") RegisterModuleServletsTask
at install time; this means that if the definition changes over time, the module developer should take care of updating the configuration by using a ModuleVersionHandler.

Example: The ClasspathSpoolServlet is configured at /server/filters/servlets/ClasspathSpoolServlet. The default resources root folder /mgnl-resources is hard-coded but is also configurable with the resourcesRoot init parameter. The servlet loads files from this folder and makes them available at the path defined in the pattern parameter.

Node nameValue


















<resources root path>




Used to spool resources from the classpath.








  • <servlet name>: Name of the servlet as defined in the servletName property.
    • mappings: URLs and paths that direct requests to the servlet.
      • <mapping name>
        • pattern: A URL pattern that triggers the servlet.
    • parameters: Parameters supported by the servlet class.
      • <parameter name>
    • class: Filter class. All servlets use the info.magnolia.cms.filters.ServletDispatchingFilter class which dispatches requests to a wrapped servlet. The filter initializes the servlet and its mappings. ServletConfig is wrapped to take init parameters into account.
    • comment: Servlet description.
    • enabled: Enables and disables the servlet. Default is true.
    • servletClass: Fully-qualified name of the servlet class.
    • servletName: Name of the servlet as defined in the module descriptor.
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))