import groovy.transform.CompileStatic
@CompileStatic
class MyClass {
// this class will be statically compiled...
}14 Static Type Checking And Compilation
Version: 8.0.0-M2
14 Static Type Checking And Compilation
Groovy is a dynamic language and by default Groovy uses a dynamic dispatch mechanism to carry out method calls and property access. This dynamic dispatch mechanism provides a lot of flexibility and power to the language. For example, it is possible to dynamically add methods to classes at runtime and it is possible to dynamically replace existing methods at runtime. Features like these are important and provide a lot of power to the language. However, there are times when you may want to disable this dynamic dispatch in favor of a more static dispatch mechanism and Groovy provides a way to do that. The way to tell the Groovy compiler that a particular class should compiled statically is to mark the class with the groovy.transform.CompileStatic annotation as shown below.
See these notes on Groovy static compilation for more details on how CompileStatic works and why you might want to use it.
One limitation of using CompileStatic is that when you use it you give up access to the power and flexibility offered by dynamic dispatch. For example, in Grails you would not be able to invoke a GORM dynamic finder from a class that is marked with CompileStatic because the compiler cannot verify that the dynamic finder method exists, because it doesn’t exist at compile time. It may be that you want to take advantage of Groovy’s static compilation benefits without giving up access to dynamic dispatch for Grails specific things like dynamic finders and this is where grails.compiler.GrailsCompileStatic comes in. GrailsCompileStatic behaves just like CompileStatic but is aware of certain Grails features and allows access to those specific features to be accessed dynamically.
14.1 The GrailsCompileStatic Annotation
GrailsCompileStatic
The GrailsCompileStatic annotation may be applied to a class or methods within a class.
import grails.compiler.GrailsCompileStatic
@GrailsCompileStatic
class SomeClass {
// all of the code in this class will be statically compiled
def methodOne() {
// ...
}
def methodTwo() {
// ...
}
def methodThree() {
// ...
}
}import grails.compiler.GrailsCompileStatic
class SomeClass {
// methodOne and methodThree will be statically compiled
// methodTwo will be dynamically compiled
@GrailsCompileStatic
def methodOne() {
// ...
}
def methodTwo() {
// ...
}
@GrailsCompileStatic
def methodThree() {
// ...
}
}It is possible to mark a class with GrailsCompileStatic and exclude specific methods by marking them with GrailsCompileStatic and specifying that the type checking should be skipped for that particular method as shown below.
import grails.compiler.GrailsCompileStatic
import groovy.transform.TypeCheckingMode
@GrailsCompileStatic
class SomeClass {
// methodOne and methodThree will be statically compiled
// methodTwo will be dynamically compiled
def methodOne() {
// ...
}
@GrailsCompileStatic(TypeCheckingMode.SKIP)
def methodTwo() {
// ...
}
def methodThree() {
// ...
}
}Code that is marked with GrailsCompileStatic will all be statically compiled except for Grails specific interactions that cannot be statically compiled but that GrailsCompileStatic can identify as permissible for dynamic dispatch. These include things like invoking dynamic finders and DSL code in configuration blocks like constraints and mapping closures in domain classes.
Care must be taken when deciding to statically compile code. There are benefits associated with static compilation but in order to take advantage of those benefits you are giving up the power and flexibility of dynamic dispatch. For example if code is statically compiled it cannot take advantage of runtime metaprogramming enhancements which may be provided by plugins.
Tag Library Calls in Controllers
Controllers annotated with @GrailsCompileStatic can invoke tag library methods without compile errors.
Tag dispatch is handled at runtime through TagLibraryInvoker, and @GrailsCompileStatic includes a built-in type-checking extension that recognises these call sites and allows them to compile.
Both calling patterns work:
import grails.compiler.GrailsCompileStatic
@GrailsCompileStatic
class BookController {
def index() {
// Direct call — tag in the default namespace invoked on `this`
response.writer << link(controller: 'book', action: 'list')
// Namespaced call — namespace dispatcher property, then tag method
response.writer << g.message(code: 'book.list.title')
}
}Only controller classes (those whose name ends with Controller) receive this treatment.
All other code in the controller remains fully type-checked.
If you need to opt a single method out of static compilation, use @GrailsCompileStatic(TypeCheckingMode.SKIP) on that method.
Applying GrailsCompileStatic Across All Controllers, Services and Tag Libraries
Rather than annotating each class individually, static compilation can be enabled for every controller, service and tag library in an application. The Grails Gradle plugin exposes these opt-ins in the nested compileStatic block of the grails build configuration:
build.gradle
grails {
compileStatic {
controllers = true // compile every grails-app/controllers class with @GrailsCompileStatic
services = true // compile every grails-app/services class with @GrailsCompileStatic
tagLibs = true // compile every grails-app/taglib class with @GrailsCompileStatic
}
}The options are lazy properties that are read when the Groovy compile task runs, so they may be configured from anywhere in the build regardless of ordering. All three are disabled by default and are independent, so each artefact type can be enabled on its own. To turn them all on at once, use the all shortcut instead:
build.gradle
grails {
compileStatic {
all = true // shortcut for controllers + services + tag libraries
}
}When an opt-in is enabled, every matching artefact is compiled exactly as if it were annotated with @GrailsCompileStatic, including the Grails-specific dispatch that the annotation already permits — dynamic finders, constraints and mapping DSLs, and tag library calls in both controllers and tag libraries.
|
For tag libraries, define tags as methods (for example |
An individual class always wins over the build-wide default by declaring its own compilation annotation. A class annotated with @CompileDynamic (or @GrailsCompileStatic, @CompileStatic, @GrailsTypeChecked or @TypeChecked) keeps its own setting and is never overridden by the opt-in:
import groovy.transform.CompileDynamic
@CompileDynamic
class LegacyController {
// compiled dynamically even when compileStatic { controllers = true } is enabled
}As with any move to static compilation, enabling these options trades the flexibility of dynamic dispatch (such as runtime metaprogramming contributed by plugins) for the benefits of static compilation. Introduce them incrementally and rely on the per-class opt-out for code that still needs dynamic behaviour.
14.2 The GrailsTypeChecked Annotation
GrailsTypeChecked
The grails.compiler.GrailsTypeChecked annotation works a lot like the GrailsCompileStatic annotation except that it only enables static type checking, not static compilation. This affords compile time feedback for expressions which cannot be validated statically at compile time while still leaving dynamic dispatch in place for the class.
import grails.compiler.GrailsTypeChecked
@GrailsTypeChecked
class SomeClass {
// all of the code in this class will be statically type
// checked and will be dynamically dispatched at runtime
def methodOne() {
// ...
}
def methodTwo() {
// ...
}
def methodThree() {
// ...
}
}