This release includes support for Apache Groovy 3, Micronaut framework 3, Gradle 7, Spring Boot 2.6, Spring framework 5.3, and Spock 2.0.

Apache Groovy 3 is a major highlight of this release. It comes with a brand new Parrot parser and a bunch of new features and capabilities. The Parrot parser supports additional syntax and language features, such as lambda expressions, default methods with interfaces, and a lot more. In addition, several new extension methods are added to existing Java classes. See the release notes for Groovy 3.0 for details.

Grails framework 5 updates to Spring 5.3.10 and Spring Boot 2.5.5. We strongly recommend checking the following Spring technologies release notes for more information.

Grails framework 5 is built with Groovy 3.0.7, which requires JDK 8 as the minimum version of JRE. We have tested most Grails projects up to JDK 14.

IntelliJ IDEA is an excellent IDE for Grails 5.0 development. It comes in 2 editions, the free community edition and the paid-for ultimate edition.

The community edition can be used for most things, although GSP syntax higlighting is only part of the ultimate edition

To get started with Intellij IDEA and Grails 5.0 simply go to File / Open and point IDEA at your build.gradle file to import and configure the project.

There are several excellent text editors that work nicely with Groovy and Grails. See below for references:

You will need to upgrade your Grails version defined in gradle.properties as:

Grails 5.1.1 provide support for Groovy 3. We would recommend you to please check the Release notes for Groovy 3 to update your application in case you are using a specific feature which might not work in Groovy 3.

Define groovyVersion in gradle.properties to force the application to use Groovy 3.

Grails 5.1 app’s gradle.properties

If you were using GORM, you will need to update the version defined in gradle.properties as:

The GORM for MongoDB is updated to support latest mongodb-driver-sync. If you are using GORM for MongoDB and doing something specific to MongoDB Driver or low level Mongo API then you might want to take a look at Upgrading to the 4.0 Driver

The previous version of asset-pipeline is not supported with Grails 5.0 as it is compiled with a version of Groovy which is binary incompatible with Groovy 3. So, please update the plugin version to 3.2.4.

The previous version of Grails use the StringCharArrayAccessor which is enabled by default and provides optimized access to java.lang.String internals. In Grails 5.0 it is disabled by default but you can enable it by setting a system property with name stringchararrayaccessor.disabled and value false.

The format of how dependencies are defined in features and profiles has been changed. See the section on Application Profiles for more information.

In order to reduce complexity, improve performance, and increase maintainability, accessing configuration through dot notation (config.a.b.c) has been deprecated. This functionality will be removed in a future release.

Also, you would see a warning message if you are accessing configuration through the dot notation.

The recommended way to access configuration is:

Grails 5.0.0.RC1 is built on Spring 5.3.2 See the Upgrading to Spring 5.3 if you are using Spring specific features.

Grails 5.1.1 updates to Spring Boot 2.6. Please check Spring Boot 2.6 Release Notes for more information.

Grails 5.1.1 is shipped with Micronaut 3.2.0. Please check the Upgrading to Micronaut 3.x if you are using a specific feature.

Grails 5.1.1 is updated to Micronaut for Spring 4.0.1, please check out release notes for more information.

You will need to upgrade your Grails version defined in gradle.properties.

Grails 3 app’s gradle.properties

Grails 4 app’s gradle.properties

If you were using GORM, you will need to update the version defined in gradle.properties.

Grails 3 app’s gradle.properties

Grails 4 app’s gradle.properties

GORM DSL entries should be move to runtime.groovy. For instance, using following GORM configuration in the application.groovy is not supported and will break the application:

Grails 4.0 is built on Spring 5 and Spring Boot 2.1. See the migration guide and release notes if you are using Spring specific features.

Grails 4.x supports a minimum version of Hibernate 5.4 and GORM 7.x. Several changes have been made to GORM to support the newer version of Hibernate and simplify GORM itself.

The details of these changes are covered in the GORM upgrade documentation.

Please check the Spring Boot Actuator documentation since it has changed substantially from Spring Boot 1.5 the version Grails 3.x used.

If you had configuration such as:

replace it with:

Previous versions of Grails used a reloading agent called Spring Loaded. Since this library is no longer maintained and does not support Java 11 support for Spring Loaded has been removed.

As a replacement, Grails 4 applications include Spring Boot Developer Tools dependencies in the build.gradle build script. If you are migrating a Grails 3.x app, please include the following set of dependencies:

Also you should configure the necessary excludes for Spring Developer Tools in application.yml:

The above configuration prevents the server from restarting when views or message bundles are changed.

Grails 4 is built on top of Spring Boot 2.1. Grails 3 apps were built on top of Spring Boot 1.x.

Your Grails 3 app’s build.gradle may have such configuration:

Grails 4 apps are built on top of Spring Boot 2.1. Starting from Spring Boot 2.0, the addResources property no longer exists. Instead, you need to set the sourceResources property to the source set that you want to use. Typically that’s sourceSets.main. This is described in the Spring Boot Gradle plugin’s documentation.

Your Grails 4 app’s build.gradle can be configured:

Spring Boot’s new Gradle Plugin:

If you had configuration such as:

replace it with:

Grails 3 apps by default used Gradle 3.5. Grails 4 apps use Gradle 5.

To upgrade to Gradle 5 execute:

Due to changes in Gradle 5, transitive dependencies are no longer resolved for plugins. If your project makes use of a plugin that has transitive dependencies, you will need to add those explicitly to your build.gradle file.

If you customized your app’s build, other migrations may be necessary. Please check Gradle Upgrading your build documentation. Especially notice, that default Gradle daemon now starts with 512MB of heap instead of 1GB. Please check Default memory settings changed documentation.

Keep in mind, that with grails 4.0.x there is a minor groovy language upgrade (e.g. 3.3.9. used groovy 2.4.x), which requires a couple of changes, that are immediately obvious when trying to compile your source code. However there are also issues with changed implementations of core linkedlist functions! Check an overview of the breaking changes here: Breaking changes of Groovy 2.5

Spring Boot 2.1 includes native support for the H2 database web console. Since this is already included in Spring Boot the equivalent feature has been removed from Grails. The H2 console is therefore now available at /h2-console instead of the previous URI of /dbconsole. See Using H2’s Web Console in the Spring Boot documentation for more information.

If you were using GORM for Hibernate implementation in your Grails 3 app, you will need to upgrade to Hibernate 5.4.

A Grails 3 build.gradle such as:

will be in Grails 4:

Geb 1.1.x (a JDK 1.7 compatible version) was the version shipped by default with Grails 3. Grails 4 is no longer compatible with Java 1.7. You should migrate to Geb 2.3.

In Grails 3, if your build.gradle looks like:

In Grails 4, you should replace it with:

Create also a Geb Configuration file at src/integration-test/resources/GebConfig.groovy.

The following classes, which were deprecated in Grails 3.x, have been removed in Grails 4. Please, check the list below to find a suitable replacement:

For those who have added a dependency on the grails-java8 plugin, all you should need to do is simply remove the dependency. All of the classes in the plugin have been moved out to their respective projects.

A few of the profiles supported in Grails 3.x will no longer be maintained going forward and as a result it is no longer possible to create applications when them in the shorthand form. When upgrading existing projects, it will be necessary to supply the version for these profiles.

In Grails 3 no configuration or additional changes were necessary to use the Spring @Scheduled annotation. In Grails 4 you must apply the @EnableScheduling annotation to your application class in order for scheduling to work.

If you want to read runtime configuration settings, i.e. those defined in application.yml, use the grailsApplication object, which is available as a variable in controllers and tag libraries:

The config property of the grailsApplication object is an instance of the Config interface and provides a number of useful methods to read the configuration of the application.

In particular, the getProperty method (seen above) is useful for efficiently retrieving configuration properties, while specifying the property type (the default type is String) and/or providing a default fallback value.

Notice that the Config instance is a merged configuration based on Spring’s PropertySource concept and reads configuration from the environment, system properties and the local application configuration merging them into a single object.

GrailsApplication can be easily injected into services and other Grails artifacts:

Accessing configuration dynamically at runtime can have a small effect on application performance. An alternative approach is to implement the GrailsConfigurationAware interface, which provides a setConfiguration method that accepts the application configuration as a parameter when the class is initialized. You can then assign relevant configuration properties to instance properties on the class for later usage.

The Config instance has the same properties and usage as the injected GrailsApplication config object. Here is the service class from the previous example, using GrailsConfigurationAware instead of injecting GrailsApplication:

You can use Spring’s Value annotation to inject configuration values:

As you can see, when accessing configuration settings you use the same dot notation as when you define them.

Suppose you are using the JDBC_CONNECTION_STRING command line argument and you want to access the same in the yml file then it can be done in the following manner:

Similarly system arguments can be accessed.

You will need to have this in build.gradle to modify the bootRun target if grails run-app is used to start the application

For testing the following will need to change the test task as follows

Grails will read application.(properties|yml) from the ./config or the current directory by default. As Grails is a SpringBoot configuration options are available as well, for documentation please consult: https://docs.spring.io/spring-boot/docs/2.5.2/reference/html/features.html#features.external-config.files

On the runtime front, i.e. grails-app/conf/application.yml, there are quite a few more core settings:

By default Grails will scan all known source directories for controllers, domain class etc., however if there are packages in other JAR files you wish to scan you can do so by overriding the packageNames() method of the Application class:

The Application class can also be used as a source for Spring bean definitions, simply define a method annotated with the Bean and the returned object will become a Spring bean. The name of the method is used as the bean name:

Grails supports the concept of per environment configuration. The application.yml and application.groovy files in the grails-app/conf directory can use per-environment configuration using either YAML or the syntax provided by ConfigSlurper. As an example consider the following default application.yml definition provided by Grails:

The above can be expressed in Groovy syntax in application.groovy as follows:

Notice how the common configuration is provided at the top level and then an environments block specifies per environment settings for the dbCreate and url properties of the DataSource.

Grails' command line has built in capabilities to execute any command within the context of a specific environment. The format is:

In addition, there are 3 preset environments known to Grails: dev, prod, and test for development, production and test. For example to create a WAR for the test environment you would run:

To target other environments you can pass a grails.env variable to any command:

Within your code, such as in a Gant script or a bootstrap class you can detect the environment using the Environment class:

It’s often desirable to run code when your application starts up on a per-environment basis. To do so you can use the grails-app/init/BootStrap.groovy file’s support for per-environment execution:

The previous BootStrap example uses the grails.util.Environment class internally to execute. You can also use this class yourself to execute your own environment specific logic:

Hibernate can automatically create the database tables required for your domain model. You have some control over when and how it does this through the dbCreate property, which can take these values:

Setting the dbCreate setting to "none" is recommended once your schema is relatively stable and definitely when your application and database are deployed in production. Database changes are then managed through proper migrations, either with SQL scripts or a migration tool like Flyway or Liquibase. The Database Migration plugin uses Liquibase.

The default DataSource configuration in grails-app/conf/application.yml looks something like this:

This configures a single DataSource with the Spring bean named dataSource. To configure extra data sources, add a dataSources block (at the top level, in an environment block, or both, just like the standard DataSource definition) with a custom name. For example, this configuration adds a second DataSource, using MySQL in the development environment and Oracle in production:

You can use the same or different databases as long as they’re supported by Hibernate.

If you need to inject the lookup datasource in a Grails artefact, you can do it like this:

If a domain class has no DataSource configuration, it defaults to the standard 'dataSource'. Set the datasource property in the mapping block to configure a non-default DataSource. For example, if you want to use the ZipCode domain to use the 'lookup' DataSource, configure it like this:

A domain class can also use two or more data sources. Use the datasources property with a list of names to configure more than one, for example:

If a domain class uses the default DataSource and one or more others, use the special name 'DEFAULT' to indicate the default DataSource:

If a domain class uses all configured data sources, use the special value 'ALL':

If a domain class uses more than one DataSource then you can use the namespace implied by each DataSource name to make GORM calls for a particular DataSource. For example, consider this class which uses two data sources:

The first DataSource specified is the default when not using an explicit namespace, so in this case we default to 'lookup'. But you can call GORM methods on the 'auditing' DataSource with the DataSource name, for example:

As you can see, you add the DataSource to the method call in both the static case and the instance case.

You can also partition annotated Java classes into separate datasources. Classes using the default datasource are registered in grails-app/conf/hibernate.cfg.xml. To specify that an annotated class uses a non-default datasource, create a hibernate.cfg.xml file for that datasource with the file name prefixed with the datasource name.

For example if the Book class is in the default datasource, you would register that in grails-app/conf/hibernate.cfg.xml:

and if the Library class is in the "ds2" datasource, you would register that in grails-app/conf/ds2_hibernate.cfg.xml:

The process is the same for classes mapped with hbm.xml files - just list them in the appropriate hibernate.cfg.xml file.

Like Domain classes, by default Services use the default DataSource and PlatformTransactionManager. To configure a Service to use a different DataSource, use the static datasource property, for example:

A transactional service can only use a single DataSource, so be sure to only make changes for domain classes whose DataSource is the same as the Service.

Note that the datasource specified in a service has no bearing on which datasources are used for domain classes; that’s determined by their declared datasources in the domain classes themselves. It’s used to declare which transaction manager to use.

If you have a Foo domain class in dataSource1 and a Bar domain class in dataSource2, if WahooService uses dataSource1, a service method that saves a new Foo and a new Bar will only be transactional for Foo since they share the same datasource. The transaction won’t affect the Bar instance. If you want both to be transactional you’d need to use two services and XA datasources for two-phase commit, e.g. with the Atomikos plugin.

Grails does not by default try to handle transactions that span multiple data sources.

You can enable Grails to use the Best Effort 1PC pattern for handling transactions across multiple datasources. To do so you must set the grails.transaction.chainedTransactionManagerPostProcessor.enabled setting to true in application.yml:

The Best Efforts 1PC pattern is fairly general but can fail in some circumstances that the developer must be aware of.

This is a non-XA pattern that involves a synchronized single-phase commit of a number of resources. Because the 2PC is not used, it can never be as safe as an XA transaction, but is often good enough if the participants are aware of the compromises.

The basic idea is to delay the commit of all resources as late as possible in a transaction so that the only thing that can go wrong is an infrastructure failure (not a business-processing error). Systems that rely on Best Efforts 1PC reason that infrastructure failures are rare enough that they can afford to take the risk in return for higher throughput. If business-processing services are also designed to be idempotent, then little can go wrong in practice.

The BE1PC implementation was added in Grails 2.3.6. . Before this change additional datasources didn’t take part in transactions initiated in Grails. The transactions in additional datasources were basically in auto commit mode. In some cases this might be the wanted behavior. One reason might be performance: on the start of each new transaction, the BE1PC transaction manager creates a new transaction to each datasource. It’s possible to leave an additional datasource out of the BE1PC transaction manager by setting transactional = false in the respective configuration block of the additional dataSource. Datasources with readOnly = true will also be left out of the chained transaction manager (since 2.3.7).

By default, the BE1PC implementation will add all beans implementing the Spring PlatformTransactionManager interface to the chained BE1PC transaction manager. For example, a possible JMSTransactionManager bean in the Grails application context would be added to the Grails BE1PC transaction manager’s chain of transaction managers.

You can exclude transaction manager beans from the BE1PC implementation with this configuration option:

The exclude matching is done on the name of the transaction manager bean. The transaction managers of datasources with transactional = false or readOnly = true will be skipped and using this configuration option is not required in that case.

When the Best Efforts 1PC pattern isn’t suitable for handling transactions across multiple transactional resources (not only datasources), there are several options available for adding XA/2PC support to Grails applications.

The Spring transactions documentation contains information about integrating the JTA/XA transaction manager of different application servers. In this case, you can configure a bean with the name transactionManager manually in resources.groovy or resources.xml file.

You can detect the application version using Grails' support for application metadata using the GrailsApplication class. For example within controllers there is an implicit grailsApplication variable that can be used:

You can retrieve the version of Grails that is running with:

or the GrailsUtil class:

The grails command is a front to a gradle invocation, because of this there can be unexpected side-effects. For example, when executing grails -Dapp.foo=bar run-app the app.foo system property won’t be available to your application. This is because bootRun in your build.gradle configures the system properties. To make this work you can simply append all System.properties to bootRun in build.gradle like:

Or if you only want to pass through a limited set, you can prefix your system properties using an arbitrary prefix and configure bootRun like:

In this example only system properties starting with boot. are passed through.

Application and JVM arguments should be specified in bootRun as well.

When you run a script manually and it prompts you for information, you can answer the questions and continue running the script. But when you run a script as part of an automated process, for example a continuous integration build server, there’s no way to "answer" the questions. So you can pass the \--non-interactive switch to the script command to tell Grails to accept the default answer for any questions, for example whether to install a missing plugin.

For example:

Plugins and applications that need to define template generation tasks can do so using scripts. A example of this is the Scaffolding plugin which defines the generate-all and generate-controllers commands.

Every Grails script implements the TemplateRenderer interface which makes it trivial to render templates to the users project workspace.

The following is an example of the create-script command written in Groovy:

If a script is defined in a plugin or profile, the template(String) method will search for the template in the application before using the template provided by your plugin or profile. This allows users of your plugin or profile to customize what gets generated.

It is common to provide an easy way to allow users to copy the templates from your plugin or profile. Here is one example on how the angular scaffolding copies templates.

Executing the model method with a Class/String/File/Resource will return an instance of Model. The model contains several properties that can help you generate code.

Example:

In addition, an asMap method is available to turn all of the properties into a map to pass to the render method.

All scripts have access to methods on the FileSystemInteraction class. It contains helpful methods to copy, delete, and create files.

Instead of invoking another Grails CLI command you can invoke Gradle directory using the gradle property.

You can also invoke Ant tasks from scripts which can help if you need to writing code generation and automation tasks:

By default Grails will resolve profiles from the Grails central repository. However, you can override what repositories will be searched by specifying repositories in the USER_HOME/.grails/settings.groovy file.

If you want profiles to be resolved with a custom repository in addition to the Grails central repository, you must specify Grails central in the file as well:

It is also possible to store simple credentials for profile repositories directly in the USER_HOME/.grails/settings.groovy file.

To create an application that uses a custom profile, you must specify the full artifact.

To make this process easier, you can define defaults for a given profile in the USER_HOME/.grails/settings.groovy file.

With the default values specified, the command to create an application using that profile becomes:

Any profile created with the create-profile command already comes configured with a grails-profile-publish plugin defined in build.gradle:

To publish a profile using this plugin to the Grails central repository first upload the source to Github (closed source profiles will not be accepted). Then register for an account on Bintray and configure your keys as follows in the profile’s build.gradle file:

With this in place you can run gradle publishProfile to publish your profile:

The profile will be uploaded to Bintray. You can then go the Grails profiles repository and request to have your profile included by clicking "Include My Package" button on Bintray’s interface (you must be logged in to see this).

The aforementioned grails-profile-publish plugin configures Gradle’s Maven Publish plugin. In order to publish to an internal repository all you need to do is define the repository in build.gradle. For example:

Once configured you can publish your plugin with gradle publish:

The profile.yml can contain the following child elements.

A list of Maven repositories to include in the generated build. Example:

A list of Maven repositories to include in the buildscript section of the generated build. Example:

A list of Gradle plugins to configure in the generated build. Example:

A list of Gradle plugins to exclude from being inherited from the parent profile:

A map of scopes and dependencies to configure. The excludes scope can be used to exclude from the parent profile. Example:

A default list of features to use if no explicit features are specified.

A list of files to exclude from parent profile’s skeletons (supports wildcards).

The target folder that parent profile’s skeleton should be copied into. This can be used to create multi-project builds.

Which file extensions should be copied from the profile as binary. Inherited and combined from parent profiles.

File patterns that should be marked as executable in the resulting application. Inherited and combined from parent profiles. The patterns are parsed with Ant.

Text to be displayed to the user after the application is created

When the create-app command runs it takes the skeleton of the parent profiles and copies the skeletons into a new project structure.

The build.gradle file is generated is result of obtaining all of the dependency information defined in the profile.yml files and produces the required dependencies.

The command will also merge any build.gradle files defined within a profile and its parent profiles.

The grails-app/conf/application.yml file is also merged into a single YAML file taking into account the profile and all of the parent profiles.

To create a domain class use Map constructor to set its properties and call save:

The save method will persist your class to the database using the underlying Hibernate ORM layer.

Grails transparently adds an implicit id property to your domain class which you can use for retrieval:

This uses the get method that expects a database identifier to read the Person object back from the database. You can also load an object in a read-only state by using the read method:

In this case the underlying Hibernate engine will not do any dirty checking and the object will not be persisted. Note that if you explicitly call the save method then the object is placed back into a read-write state.

In addition, you can also load a proxy for an instance by using the load method:

This incurs no database access until a method other than getId() is called. Hibernate then initializes the proxied instance, or throws an exception if no record is found for the specified id.

To update an instance, change some properties and then call save again:

To delete an instance use the delete method:

Controllers can be created with the create-controller or generate-controller command. For example try running the following command from the root of a Grails project:

The command will create a controller at the location grails-app/controllers/myapp/BookController.groovy:

where "myapp" will be the name of your application, the default package name if one isn’t specified.

BookController by default maps to the /book URI (relative to your application root).

A controller can have multiple public action methods; each one maps to a URI:

This example maps to the /book/list URI by default thanks to the property being named list.

A controller has the concept of a default URI that maps to the root URI of the controller, for example /book for BookController. The action that is called when the default URI is requested is dictated by the following rules:

Scopes are hash-like objects where you can store variables. The following scopes are available to controllers:

Scopes can be accessed using the variable names above in combination with Groovy’s array index operator, even on classes provided by the Servlet API such as the HttpServletRequest:

You can also access values within scopes using the de-reference operator, making the syntax even more clear:

This is one of the ways that Grails unifies access to the different scopes.

Grails supports the concept of flash scope as a temporary store to make attributes available for this request and the next request only. Afterwards the attributes are cleared. This is useful for setting a message directly before redirecting, for example:

When the delete action is requested, the message value will be in scope and can be used to display an information message. It will be removed from the flash scope after this second request.

Note that the attribute name can be anything you want, and the values are often strings used to display messages, but can be any object type.

Newly created applications have the grails.controllers.defaultScope property set to a value of "singleton" in application.yml. You may change this value to any of the supported scopes listed below. If the property is not assigned a value at all, controllers will default to "prototype" scope.

Supported controller scopes are:

To enable one of the scopes, add a static scope property to your class with one of the valid scope values listed above, for example

You can define the default strategy in application.yml with the grails.controllers.defaultScope key, for example:

A model is a Map that the view uses when rendering. The keys within that Map correspond to variable names accessible by the view. There are a couple of ways to return a model. First, you can explicitly return a Map instance:

A more advanced approach is to return an instance of the Spring ModelAndView class:

One thing to bear in mind is that certain variable names can not be used in your model:

Currently, no error will be reported if you do use them, but this will hopefully change in a future version of Grails.

In both of the previous two examples there was no code that specified which view to render. So how does Grails know which one to pick? The answer lies in the conventions. Grails will look for a view at the location grails-app/views/book/show.gsp for this show action:

To render a different view, use the render method:

In this case Grails will attempt to render a view at the location grails-app/views/book/display.gsp. Notice that Grails automatically qualifies the view location with the book directory of the grails-app/views directory. This is convenient, but to access shared views, you use an absolute path instead of a relative one:

In this case Grails will attempt to render a view at the location grails-app/views/shared/display.gsp.

Grails also supports JSPs as views, so if a GSP isn’t found in the expected location but a JSP is, it will be used instead.

If a controller defines a namespace for itself with the namespace property that will affect the root directory in which Grails will look for views which are specified with a relative path. The default root directory for views rendered by a namespaced controller is grails-app/views/<namespace name>/<controller name>/. If the view is not found in the namespaced directory then Grails will fallback to looking for the view in the non-namespaced directory.

See the example below.

Sometimes it’s easier (for example with Ajax applications) to render snippets of text or code to the response directly from the controller. For this, the highly flexible render method can be used:

The above code writes the text "Hello World!" to the response. Other examples include:

If you plan on using Groovy’s MarkupBuilder to generate HTML for use with the render method be careful of naming clashes between HTML elements and Grails tags, for example:

This will actually call the form tag (which will return some text that will be ignored by the MarkupBuilder). To correctly output a <form> element, use the following:

Actions can be redirected using the redirect controller method:

Internally the redirect method uses the HttpServletResponse object’s sendRedirect method.

The redirect method expects one of:

In the above example Grails will construct a link using the domain class id (if present).

Parameters can optionally be passed from one action to the next using the params argument of the method:

These parameters are made available through the params dynamic property that accesses request parameters. If a parameter is specified with the same name as a request parameter, the request parameter is overridden and the controller parameter is used.

Since the params object is a Map, you can use it to pass the current request parameters from one action to the next:

Finally, you can also include a fragment in the target URI:

which will (depending on the URL mappings) redirect to something like "/myapp/test/show#profile".

Actions can also be chained. Chaining allows the model to be retained from one action to the next. For example calling the first action in this action:

results in the model:

The model can be accessed in subsequent controller actions in the chain using the chainModel map. This dynamic property only exists in actions following the call to the chain method:

Like the redirect method you can also pass parameters to the chain method:

The data binder is capable of converting and assigning values in a Map to properties of an object. The binder will associate entries in the Map to properties of the object using the keys in the Map that have values which correspond to property names on the object. The following code demonstrates the basics:

To update properties of a domain object you may assign a Map to the properties property of the domain class:

The binder can populate a full graph of objects using Maps of Maps.

The data binder can populate and update Collections and Maps. The following code shows a simple example of populating a List of objects in a domain class:

That code would work in the same way if albums were an array instead of a List.

Note that when binding to a Set the structure of the Map being bound to the Set is the same as that of a Map being bound to a List but since a Set is unordered, the indexes don’t necessarily correspond to the order of elements in the Set. In the code example above, if albums were a Set instead of a List, the bindingMap could look exactly the same but 'Foxtrot' might be the first album in the Set or it might be the second. When updating existing elements in a Set the Map being assigned to the Set must have id elements in it which represent the element in the Set being updated, as in the following example:

When binding to a Map the structure of the binding Map is the same as the structure of a Map used for binding to a List or a Set and the index inside of square brackets corresponds to the key in the Map being bound to. See the following code:

When updating an existing Map, if the key specified in the binding Map does not exist in the Map being bound to then a new value will be created and added to the Map with the specified key as in the following example:

The params object that is available in a controller has special behavior that helps convert dotted request parameter names into nested Maps that the data binder can work with. For example, if a request includes request parameters named person.homeAddress.country and person.homeAddress.city with values 'USA' and 'St. Louis' respectively, params would include entries like these:

There are two ways to bind request parameters onto the properties of a domain class. The first involves using a domain classes' Map constructor:

The data binding happens within the code new Book(params). By passing the params object to the domain class constructor Grails automatically recognizes that you are trying to bind from request parameters. So if we had an incoming request like:

Then the title and author request parameters would automatically be set on the domain class. You can use the properties property to perform data binding onto an existing instance:

This has the same effect as using the implicit constructor.

When binding an empty String (a String with no characters in it, not even spaces), the data binder will convert the empty String to null. This simplifies the most common case where the intent is to treat an empty form field as having the value null since there isn’t a way to actually submit a null as a request parameter. When this behavior is not desirable the application may assign the value directly.

The mass property binding mechanism will by default automatically trim all Strings at binding time. To disable this behavior set the grails.databinding.trimStrings property to false in grails-app/conf/application.groovy.

The mass property binding mechanism will by default automatically convert all empty Strings to null at binding time. To disable this behavior set the grails.databinding.convertEmptyStringsToNull property to false in grails-app/conf/application.groovy.

The order of events is that the String trimming happens and then null conversion happens so if trimStrings is true and convertEmptyStringsToNull is true, not only will empty Strings be converted to null but also blank Strings. A blank String is any String such that the trim() method returns an empty String.

If you have a one-to-one or many-to-one association you can use Grails' data binding capability to update these relationships too. For example if you have an incoming request such as:

Grails will automatically detect the .id suffix on the request parameter and look up the Author instance for the given id when doing data binding such as:

An association property can be set to null by passing the literal String "null". For example:

If you have a one-to-many or many-to-many association there are different techniques for data binding depending of the association type.

If you have a Set based association (the default for a hasMany) then the simplest way to populate an association is to send a list of identifiers. For example consider the usage of <g:select> below:

This produces a select box that lets you select multiple values. In this case if you submit the form Grails will automatically use the identifiers from the select box to populate the books association.

However, if you have a scenario where you want to update the properties of the associated objects the this technique won’t work. Instead you use the subscript operator:

However, with Set based association it is critical that you render the mark-up in the same order that you plan to do the update in. This is because a Set has no concept of order, so although we’re referring to books[0] and books[1] it is not guaranteed that the order of the association will be correct on the server side unless you apply some explicit sorting yourself.

This is not a problem if you use List based associations, since a List has a defined order and an index you can refer to. This is also true of Map based associations.

Note also that if the association you are binding to has a size of two and you refer to an element that is outside the size of association:

Then Grails will automatically create a new instance for you at the defined position.

You can bind existing instances of the associated type to a List using the same .id syntax as you would use with a single-ended association. For example:

Would allow individual entries in the books List to be selected separately.

Entries at particular indexes can be removed in the same way too. For example: