Grails 3 is a major step forward in the evolution of the framework and re-evaluates many aspects of the framework which have evolved over the years. One area of the framework that was re-evaluated is that related to Grails filters. Grails filters are a lot like servlet filters but are more simple and are better integrated into the Grails runtime and its conventions. Grails filters were a way to implement logic that might relate to any number of controllers and were a powerful and flexible way to address many of those concerns. Grails 3 introduces the notion of interceptors as a better way to address many of the types of concerns that previously would have been addressed with filters. Like filters, interceptors contain code which may be applied to requests before and/or after invoking controller actions without having to embed that logic into all of the controllers that the logic may relate to. Interceptors offer a number of benefits over filters including support for static compilation and more flexible configurability.
Defining An Interceptor
Like most Grails artifacts, interceptors are normal Groovy classes that follow certain conventions which allow the framework to identify them and augment them with a rich set of behavior that is relevant to tasks that interceptors frequently address.
Because interceptors are often associated with controllers the convention is to define them under the
grails-app/controllers/ directory. Interceptor class names should end with the word
The interceptor class does noes not need to extend any special base class and does not need to be marked with any special annotations in order for the framework to recognize the class as an interceptor. The location of the source file and the name of the class are sufficient to register the class as an interceptor.
create-interceptor command may be used to define an interceptor.
$ grails create-interceptor demo.First | Created grails-app/controllers/demo/FirstInterceptor.groovy | Created src/test/groovy/demo/FirstInterceptorSpec.groovy
The Interceptor Trait
Grails 3 takes advantage of Groovy’s powerful and flexible support for traits in many places. All interceptors are automatically made to implement the grails.artefact.Interceptor trait so all of the methods and properties defined by that trait and all of the methods and properties defined by traits which that trait extends are all available inside of an interceptor. This provides easy access to attributes like
session and others. The trait also provides access to methods like
A convention is imposed which will automatically configure interceptors to match all requests to their corresponding controller. The implicit mapping from an interceptor to a controller is based on the artifact names. For example, by default the
PersonInterceptor will match all requests to the
Interceptors often need to deviate from the convention and define which requests they should participate in using the
The named arguments supported are
uri. All of them except for
uri accept either a
String or a regex expression. The
uri argument supports a
String path that is compatible with Spring’s org.springframework.util.AntPathMatcher.
An interecptor may match all requests except requests that satisfy some condition.
matchAll methods in an intereceptor each return an instance of grails.interceptors.Matcher. Most of the methods in
Matcher also return the
Matcher which allows for method chaining as shown above with
Care should be taken to narrow the group of requests that an interceptor is applied to. Keep in mind that whatever logic is contained in an interceptor is being engaged for all of the requests that the interceptor matches.
There are 3 separate methods that an interceptor may define to participate in different parts of the request processing lifecycle. The
before method is executed before the controller action is invoked. The
after method is invoked after the controller action returns and before the view is rendered. The
afterView method is invoked after the view is rendered. An interceptor may provide any combination of these 3 call back methods and does not need to provide all 3.
after methods have a
boolean return type. The methods should return
true to indicate that control should continue as usual without interruption. The methods should return
false to indicate that the interceptor has decided that the request has been handled by the intereceptor and processing should not continue on as per usual. For example, a
before interceptor may recognize that a request to a controller action is invalid for some reason, issued a
redirect to handle the situation and then return
false so that the originally requested action will not be engaged.
Any number of interceptors may match a request and in some circumstances it may be useful to affect the order in which the interceptors are invoked. To support this, the framework will recognize an
int property named
order defined in any interceptor. The value of the
order property may be any number. Intereceptors are sorted based on their order from lowest to highest value and executed in that order so an interceptor with an
order of 100 will execute before an interceptor with an
order of 200. This determines the order in which the
before interceptor methods are invoked. The interceptors are configured kind of like a stack and are popped off of the stack while processing the
afterView methods so those are executed in the opposite order that the
before methods are executed.
For convenience there are properties named
LOWEST_PRECEDENCE which may be referenced when initializing the
Unlike Grails 2 filters, Grails 3 intercetors are compatible with Groovy’s static compilation and as such may be marked with the
@CompileStatic annotation. Static compilation may be of particular importance in an interceptor because code in an interceptor potentially could be executed as part of handling every request into the application so performance may be particularly important there. Referencing methods introduced by the
Interceptor trait like
render and accessing propeties like
grailsApplication are all compatible with
Like most Grails artifacts interceptors have a
The default logger name for an interceptor is
grails.app.controllers.<interceptor class name>. For the interceptor shown above that would be
grails.app.controllers.demo.SimpleAuthInterceptor so the logging could be configured in
grails-app/conf/logback.groovy as shown below.
Note that the logger name prefix is
grails.app.interceptors. This is because by default interceptors are defined under the
grails-app/controllers/ directory. The framework offers flexibility around this such that if you would like to separate your interceptors from your controllers you can do that by moving the interceptors to a directory like
grails-app/interceptors/. If the interceptor defined above were moved from
grails-app/interceptors/demo/SimpleAuthInterceptor.groovy the logger name would be
Interceptors Are Spring Beans
All interceptors are configured as beans in the Spring application context and are configured to be autowired by name. This means that just like other Grails artifacts, an interceptor may define a property with a name that matches a bean name and that property will be initialized using standard Spring dependency injection.
In addition to participating in dependency injection, because interceptors are Spring beans they participate in all of the standard Spring bean management handling. For example, if an interceptor wanted access to the application’s configuration, the intereceptor class could implement the grails.core.support.GrailsConfigurationAware interface.
With that in place, the request matching could be dynamically configured in
Interceptors may be tested on their own as first class artifacts.
The effects introduced by an interceptor may be tested in a functional test.
Grails 3 interceptors are a great way to insert logic into the request handling process. Like all Grails artifacts, interceptors take advantage of convention over configuration and sensible defaults to maximize flexibility and minimize configuration burden required to take advantage of really powerful functionality provided by the framework. Support for marking interceptors with
@CompileStatic means that the performance cost associated with interceptor logic can be minimized. The fact that interceptors are Spring beans provides a lot of flexibility for keeping interceptors simple yet powerful.