Before and after interceptors were removed. So all beforeInterceptor and afterInterceptor need to be replaced by Stand alone interceptors.

Classes and methods deprecated in Grails 3.0.x have been removed in Grails 3.2. This includes all classes in the org.codehaus.groovy.grails package. If your application or plugin uses deprecated classes they should be updated to use non-deprecated replacements.

The log property injected at compile time into all classes is now an Slf4j Logger instance and not an instance of the Commons Logging Log class.

This should be a simple upgrade for most use cases, however this change does have some implications, for example it is no longer possible to pass non-string types to the log method. Example:

The latter call to the info method will throw an exception as it is not a String.

Instead you should use Slf4j’s formatting anchors to log. The advantage is the toString() method is not called unless the message will be logged.

See the Slf4j FAQ for more information.

Grails 3.2 comes with Spring 4.3 which no longer supports Hibernate 3 and hence Grails 3.2 no longer supports Hibernate 3 either and you will need to upgrade to Hibernate 4 or above.

Spring Boot 1.4, through its dependency management mechanism, enforces the upgrade for many depndencies. You should review your dependencies following the upgrade to ensure the new versions are compatible with your application.

Spring Boot 1.4 also deprecates many testing annotations (such as WebIntegrationTest).

See the Spring Boot 1.4 release notes for more information on the changes required at the Boot level.

Related to Spring Boot 1.4, one important change is that Hibernate 5 is now the default version, so if you have declared a dependency on the hibernate4 plugin in Grails such as:

This will not be enough to ensure that Hibernate 4 is used. You must instead also directly declare the Hibernate 4 dependencies:

In preparation for Hibernate 5.2 support the previous "SessionFactoryBean" notion has been removed. Now if you wish to customize SessionFactory creation you should instead register a custom org.grails.orm.hibernate.connections.HibernateConnectionSourceFactory in Spring.

The grails-datastore-test-support dependency has been removed and the HibernateTestMixin class integrated directly into the plugin, so if you receive a resolve error remove the following dependency from your build.gradle:

An improvement was added to make groovy configuration behave like yml configuration when it comes to the CLI. Previously, configuration values in application.groovy were not available to commands like grails create-controller. A side effect of this change causes an exception when those commands are executed if the configuration relies on classes in the runtime.

The solution is to create a separate file called runtime.groovy in grails-app/conf. That file will not be parsed by the CLI and will only be included at runtime.

Using the default package in places like UrlMappings.groovy, BootStrap.groovy or in a taglib can cause that code to fail or not execute at all when packaged in a JAR or WAR file. Make sure all Groovy/Java files start with the package statement and move any affected files to the respective folder. For example, change:

to:

and copy the file from grails-app/controllers/UrlMappings.groovy into .grails-app/controllers/myapp/UrlMappings.groovy

Grails 3.1 ships with GORM 5, which is a near complete rewrite of GORM ontop of Groovy traits and is not binary compatible with the previous version of GORM.

If you receive an error such as:

You are using a plugin or class that was compiled with a previous version of GORM and these will need to be recompiled to be Grails 3.1 and GORM 5 compatible.

For the GORM 5 release the hibernate plugin has been renamed to hibernate4 (and there are hibernate3 and hibernate5 versions too). You should change your build.gradle to reflect that:

The default path for static resources resolved from src/main/resources/public has been changed to be nested under the static/* pattern instead of directly under the root of the application. For example a link in GSP pages such as:

Will produce a URI such as /static/files/mydoc.pdf instead of /files/mydoc.pdf. If you wish to revert to the previous behavior you can configure this in application.yml:

The Filters plugin was replaced by Interceptors in Grails 3.0.x, although the plugin was still present. In Grails 3.1.x the Filters plugin has been removed. If you still wish to use the filters plugin you can add a dependency on the previous version provided by Grails 3.0.x. For example:

You would also need to move the filters to any other source directory (e.g. grails-app/controllers) as grails-app/conf is not considered a source directory anymore.

Because the grails.transactional.Transactional transform already provides the ability to create transactional services without the need for proxies, traditional support for transactional proxies has been disabled by default for new applications.

This means that if you have any services that use the transactional property and not the Transactional annotation they should be altered. For example the following service:

Becomes:

In addition because in previous versions of a Grails transactional defaulted to true any services that do not declare transactional should be altered too.

If you wish to adopt the new behavior then transctional proxies can be disabled with the following configuration:

The default JSON converter no longer includes the class property by default. This can be re-enable with the following configuration:

In addition the default JSON converter will no longer render the id property if it is null.

The class grails.web.JSONBuilder has been deprecated and replaced with groovy.json.StreamingJsonBuilder, the default JSON builder within Groovy. This avoids confusion with the differences between JSON builders and better aligns with Groovy’s core libraries.

This also means that any render blocks that rendered JSON will need to be updated to use the groovy.json.StreamingJsonBuilder syntax. For example the following code:

Should instead be written as:

If you are upgrading and prefer to continue to use the previous implementation then you can re-enable the deprecated JSONBuilder with the following configuration:

With the addition of JSON views the previous API for using JSON converters is largely discouraged in favour of views. The converters plugin will in the future be separated into an external plugin and JSON views phased in to replace it. The JSON converter API is not deprecated, however JSON views provide a more fully featured, elegant API that is superior to writing JSON converters and/or marshallers.

Grails 3.1 ships with upgraded third party libraries that may require changes. See the Spring Boot upgrade notes for information.

Unlike Spring Boot 1.2, Spring Boot 1.3 no longer uses the Gradle Application Plugin so if you relied on any behavior the application plugin then the plugin will need to be re-applied to your build.gradle.

Spring Boot 1.3 also uses Spring Security 4.x by default, so if you project depends on Spring Security 3.x you have to force a downgrade. For example:

Because the Gradle run task for application startup was provided by the Gradle Application Plugin (see above), it is no longer available by default. If you use Gradle to start up your application, use the bootRun task instead, or re-apply the Application plugin in your build.gradle.

Note: If you don’t have need of the Gradle Application plugin’s features, but have custom Gradle tasks or IDE configurations that depend on run, you can supply your own run task that depends on bootRun in your build.gradle:

The Resource annotation applied to domain classes defaults to XML in Grails 3.0.x, but in Grails 3.1.x and above it defaults to JSON.

If you use this annotation with the expecation of produces XML responses as the default you can modify the definition as follows:

This will restore the Grails 3.0.x behavior.

If you use Geb with HTMLUnit (something that is not recommended, as a more native driver such as PhantomJS is recommended) you will need to upgrade your dependencies in build.grade:

Note that there are also some changes in behavior in HTMLUnit 2.18 that may cause issues in existing tests including:

An improvement was added to make groovy configuration behave like yml configuration when it comes to the CLI. Previously, configuration values in application.groovy were not available to commands like grails create-controller. A side effect of this change causes an exception when those commands are executed if the configuration relies on classes in the runtime.

The solution is to create a separate file called runtime.groovy in grails-app/conf. That file will not be parsed by the CLI and will only be included at runtime.

The first step is to create a new Grails 3 plugin using the command line:

This will create a Grails 3 plugin in the quartz directory.

The next step is to copy the sources from the original Grails 2 plugin to the Grails 3 plugin:

You will need to add a package declaration to the plugin descriptor. In this case QuartzGrailsPlugin is modified as follows:

In addition you should remove the version property from the descriptor as this is now defined in build.gradle.

The repositories and dependencies defined in grails-app/conf/BuildConfig.groovy of the original Grails 2.x plugin will need to be defined in build.gradle of the new Grails 3.x plugin:

It is recommended to use the latest stable, Grails 3+ compatible version of plugins. (Grails 2.x plugin versions will not work.)

In Grails 3.x all internal APIs can be found in the org.grails package and public facing APIs in the grails package. The org.codehaus.groovy.grails package no longer exists.

All package declaration in sources should be modified for the new location of the respective classes. Example org.codehaus.groovy.grails.commons.GrailsApplication is now grails.core.GrailsApplication.

Some plugins define a default configuration file. For example the Quartz plugin defines a file called grails-app/conf/DefaultQuartzConfig.groovy. In Grails 3.x this default configuration can be migrated to grails-app/conf/application.yml and it will automatically be loaded by Grails without requiring manual configuration merging.

Old plugins may have a pluginExcludes property defined that lists the patterns for any files that should not be included in the plugin package. This is normally used to exclude artifacts such as domain classes that are used in the plugin’s integration tests. You generally don’t want these polluting the target application.

This property is no longer sufficient in Grails 3, and nor can you use source paths. Instead, you must specify patterns that match the paths of the compiled classes. For example, imagine you have some test domain classes in the grails-app/domain/plugin/tests directory. You should first change the pluginExcludes value to

and then add this block to the build file:

The easiest way to ensure these patterns work effectively is to put all your non-packaged class into a distinct Java package so that there is a clean separation between the main plugin classes and the rest.

In Grails 3.x ArtefactHandler definitions written in Java need to be declared in a file called src/main/resources/META-INF/grails.factories since these need to be known at compile time.

The Quartz plugin requires the following definition to register the ArtrefactHandler:

Many plugins previously defined command line scripts in Gant. In Grails 3.x command line scripts have been replaced by two new features: Code generation scripts and Gradle tasks.

If your script is doing simple code generation then for many cases a code generation script can replace an old Gant script.

The create-job script provided by the Quartz plugin in Grails 2.x was defined in scripts/CreateJob.groovy as:

A replacement Grails 3.x compatible script can be created using the create-script command:

Which creates a new script called src/main/scripts/create-job.groovy. Using the new code generation API it is simple to implement:

Please refer to the documentation on Creating Custom Scripts for more information.

Using the old Grails 2.x build system it was relatively common to spin up Grails inside the command line. In Grails 3.x it is not possible to load a Grails application within a code generation script created by the create-script command.

Instead a new mechanism specific to plugins exists via the create-command command. The create-command command will create a new ApplicationCommand, for example the following command will execute a query:

With this command in place once the plugin is installed into your local Maven cache you can add the plugin to both the build classpath and the runtime classpath of the application’s build.gradle file:

Grails will automatically create a Gradle task called runQuery and a command named run-query so both the following examples will execute the command:

You should now delete and cleanup the project of any files no longer required by Grails 3.x (BuildConfig.groovy, Config.groovy, DataSource.groovy etc.)

Once the plugins are Grails 3.x compatible you can upgrade the application. To upgrade an application it is again best to create a new Grails 3 application using the "web" profile:

The next step is to copy the sources from the original Grails 2 application to the Grails 3 application:

The repositories and dependencies defined in grails-app/conf/BuildConfig.groovy of the original Grails 2.x application will need to be defined in build.gradle of the new Grails 3.x application.

In Grails 3.x all internal APIs can be found in the org.grails package and public facing APIs in the grails package. The org.codehaus.groovy.grails package no longer exists.

All package declaration in sources should be modified for the new location of the respective classes. Example org.codehaus.groovy.grails.commons.GrailsApplication is now grails.core.GrailsApplication.

The configuration of the application will need to be migrated, this can normally be done by simply renaming grails-app/conf/Config.groovy to grails-app/conf/application.groovy and merging the content of grails-app/conf/DataSource.groovy into grails-app/conf/application.groovy.

Note however that Log4j has been replaced by grails-app/conf/logback.groovy for logging, so any logging configuration in grails-app/conf/Config.groovy should be migrated to logback format.

If you have a modified web.xml template then you will need to migrate this to Spring as Grails 3.x does not use a web.xml (although it is still possible to have on in src/main/webapp/WEB-INF/web.xml).

New servlets and filters can be registered as Spring beans or with ServletRegistrationBean and FilterRegistrationBean respectively.

If you have static assets in your web-app directory of your Grails 2.x application such as HTML files, TLDs etc. these need to be moved. For public assets such as static HTML pages and so on these should go in src/main/resources/public.

TLD descriptors and non public assets should go in src/main/resources/WEB-INF.

As noted earlier, src/main/webapp folder can also be used for this purpose but it is not recommended.

Once the package names are corrected unit tests will continue to run, however any tests that extend the deprecated and removed JUnit 3 hierarchy will need to be migrated to Spock or JUnit 4.

Integration tests will need to be annotated with the Integration annotation and should not extend GroovyTestCase or any JUnit 3 super class.

The Constraints section of a Domain Class (or other validateable object) looks like this:

In Grails 2.x, fields with no constraints could be declared in the Constraints block, as a method call with no arguments. Example (NB. the following syntax is no longer supported):

A different syntax has to be used in Grails 3. Either remove the field declaration from the constraints block (if there are no constraints to specify for it), or to keep the field placeholder, pass an empty map argument: \[:\] instead of ().

Replacement code for Grails 3.x:

If such declarations have not yet been changed then a log message like this emits on startup:

If your project had inline plugins in Grails 2.x, contains ASTs, or if your project is composed of several modules or related applications then you may decide to restructure your project as a Gradle multi-project build.

Sample multi-project structure:

How to configure this is documented in the Plugins section under the heading 'Inline Plugins in Grails 3.0'.

During the progress of migrating code from Grails 2.4 to Grails 3.1+, your project (and the plugins that your project depends on) will be moving to GORM 5 (or higher) and other newer library versions. You might also wish to familiarise yourself with the differences mentioned in the section Upgrading from Grails 3.0.

If your application contains AST transformations, please be aware that for these to be applied to your application code, they must now be contained within a plugin. (In Grails 2.x it was possible to pre-compile AST transformations then apply them to your application code by hooking into compile events in _Events.groovy. This is no longer possible. Move your AST Transformation classes and associated annotations into a plugin for this purpose.)

There are two AST patterns on which you can base migration of your AST transformer code:

Grails uses Spring Boot to embed a Tomcat or Jetty instance by default. To build a war file for deployment to a container you will need to make a simple change to build.gradle (so that a container is not embedded).

If you deploy to a Tomcat 7 container then there is an additional step. Grails 3 is built against Tomcat 8 APIs by default. You will need to change the target Tomcat version in the build to 7.

There are standalone deployment options available.

Refer to the Deployment guide for further details.

If your application uses multiple datasources, then be aware that the way these are declared in application.yml or application.groovy (previously DataSources.groovy) has changed.

If there is more than one DataSource in an application there is now a dataSources { …​ } configuration block to contain them all. Previously, multiple dataSource declarations were used, with an underscore and suffix on the additional datasources, e.g. dataSource_lookup { …​ }.

Please refer to the user guide section on Multiple Datasources for examples.

In your Grails 2.x app you may have used Spring @Autowired in a few situations, such as dependency injection into certain base classes, and for typed field dependency injection. For example:

Grails now has support for dependency injection into typed fields in addition to untyped def fields, following the usual Grails conventions of field name matching the bean property name. Example:

You may find that @Autowired no longer works as it did previously in your code on artefacts or base classes, in certain scenarios, resulting in NULL for these fields. Changing these to a simple typed Grails dependency following the Grails naming convention and removing @Autowired should resolve this.