Custom filters
This page explains how to create and configure a custom Filter.
Please read about Filters and request processing which explains some filters used by Magnolia.
Implementation
To ensure your filter is properly registered using Magnolia
configuration, your filter should implement
info.magnolia.cms.filters.MgnlFilter or extend another
Magnolia filter that implements MgnlFilter. Extending
info.magnolia.cms.filters.AbstractMgnlFilter is usually a
good starting point.
Example:
public class KlackerFilter extends AbstractMgnlFilter{
@Override
public void doFilter(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse,
FilterChain filterChain) throws IOException, ServletException {
httpServletResponse.setHeader("X-Clacks-Overhead", "GNU Terry Pratchett" );
filterChain.doFilter(httpServletRequest, httpServletResponse);
}
}The example above is a dummy example inspired by GNU Terry Pratchett HTTP-Header.
Configuration and Registration of filters
Filters in a Java webapp using servlets 2.5 must be registered in the
web.xml. However:
When adding a filter to Magnolia - you should not register it in web.xml but on Magnolia configuration. If the configuration is done properly - filters are registered dynamically by Magnolia.
You can configure filters implementing
info.magnolia.cms.filters.MgnlFilter as well as other
filters with Magnolia configuration by using the
Configuration app.
Unlike web.xml configuration, you can change the configuration
on the running instance. This also includes enabling and disabling a filter.
As with any other configuration data - bootstrap the configuration within your module with a bootstrap file or create an installation task to ensure configuration is set correctly when your project must be reinstalled or deployed.
Add a node to /server/filters
To configure a filter add a node to /server/filters:
| Property | Description |
|---|---|
|
required The fully qualified class name of your custom filter. Must implement info.magnolia.cms.filters.MgnlFilter. |
|
optional, default is Setting to false disables the filter. |
|
optional Add mappings. |
Configuring and registering filters not implementing MgnlFilter
If you have a filter that cannot implement info.magnolia.cms.filters.MgnlFilter for some reason but that should be registered in the Magnolia filter chain, your configuration should look like this:
| Property | Description |
|---|---|
|
required In this case class must be info.magnolia.cms.filters.FilterDecorator. |
|
required |
|
required The fully qualified class name of your custom filter (which does not implement info.magnolia.cms.filters.AbstractMgnlFilter). |
|
optional A map to add filter init parameters. You may add as many parameters as required. The init parameters can be read in the init method of the filter (see below). |
Adding filter init parameters
javax.servlet.Filter has an #init method which is called once when the filter is initialized.
Init parameters for filters implementing MgnlFilter
When using filters implementing
info.magnolia.cms.filters.MgnlFilter, you can use a
normal Node2Bean mechanism and add bean properties to the filter class.
public class KlackerFilter extends AbstractMgnlFilter {
// bean properties
private String klackerMessage;
private int maximumKlackerNumber;
@Override
public void init(FilterConfig filterConfig) throws ServletException {
super.init(filterConfig);
// use bean properties - here klackerMessage, maximumKlackerNumber -
// to do something usefull
}
@Override
public void doFilter(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse,
FilterChain filterChain) throws IOException, ServletException {
// do something usefull here
filterChain.doFilter(httpServletRequest, httpServletResponse);
}
// getter and setter methods for the bean properties
public String getKlackerMessage() {
return klackerMessage;
}
public void setKlackerMessage(String klackerMessage) {
this.klackerMessage = klackerMessage;
}
public int getMaximumKlackerNumber() {
return maximumKlackerNumber;
}
public void setMaximumKlackerNumber(int maximumKlackerNumber) {
this.maximumKlackerNumber = maximumKlackerNumber;
}
}
Init parameters for filters not implementing MgnlFilter
If you are using FilterDecorator for custom filters not implementing
info.magnolia.cms.filters.MgnlFilter, use the config node
to add init parameters
(see above). The parameters are set to javax.servlet.FilterConfig and can be
used in the init method:
public class AnotherFilter implements Filter {
@Override
public void init(FilterConfig filterConfig) throws ServletException {
String initParam = filterConfig.get("myInitParam");
// do something usefull here with the initParam
}
@Override
public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
throws IOException, ServletException {
// do something usefull here
filterChain.doFilter(servletRequest, servletResponse);
}
@Override
public void destroy() {
}
}Ensure position in filter chain
Filters are executed in the order they are in the chain, from top to bottom. If you do not care about execution order, you can skip this section, otherwise make sure the filter is in the right position in the chain.
Magnolia provides task classes to adapt the order of the filter via
module version handler. Use
info.magnolia.module.delta.FilterOrderingTask or
info.magnolia.module.delta.OrderFilterBeforeTask. The
code example below
is using the FilterOrderingTask.
When installing a module, you can define the position with `ModuleVersionHandler#getExtraInstallTasks`.
public class MyModuleVersionHandler extends DefaultModuleVersionHandler {
@Override
protected List<Task> getExtraInstallTasks(InstallContext installContext) {
List<Task> extraInstallTasks = new ArrayList<Task>(super.getExtraInstallTasks(installContext));
extraInstallTasks.add(new FilterOrderingTask("klacker", new String[]{"contentType"}));
return extraInstallTasks;
}
}
The code above would ensure to have the filter klacker right after
the filter contentType.
|