Page tree
Skip to end of metadata
Go to start of metadata

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  SelfMappingServlet . This is an optional interface that servlets wrapped by  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  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>.

core.xml
<servlets>
    <servlet>
        <name>ClasspathSpoolServlet</name>
        <class>info.magnolia.cms.servlets.ClasspathSpool</class>
        <comment>Used to serve resources from the classpath.</comment>
        <mappings>
            <mapping>/.resources/*</mapping>
        </mappings>
    </servlet>
</servlets>

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.

Examples:

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 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

 server

 

 filters

 

 servlets

 

 ClasspathSpoolServlet

 

 mappings

 

 -.resources--

 

 pattern

/.resources/*

 parameters

 

 resourcesRoot

<resources root path>

 class

info.magnolia.cms.filters.ServletDispatchingFilter

 comment

Used to spool resources from the classpath.

 enabled

true

 servletClass

info.magnolia.cms.servlets.ClasspathSpool

 servletName

ClasspathSpoolServlet

Properties:

  • <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.