GORM for Hibernate

GORM 6.1 includes a variety of enhancements to GORM 6.0 including:

See the What’s New in GORM 6.1 guide for more information.

GORM 6.0 continues to evolve the new trait based model and includes the following new features:

GORM 5.0 replaced the majority of the custom AST transformations that power GORM with Groovy Traits.

Support for the MongoDB 3.x drivers, Neo4j 2.3.x and Hibernate 5.x was added.

GORM 4.0 continued to separate the GORM API from the Grails core APIs and was the first version to be support standalone execution outside of Grails.

GORM 4.0 was released in conjunction with Grails 3.0 and also featured auto configuration starters for Spring Boot.

Support was introduced for MongoDB 2.x drivers, Neo4j 2.2.x and Hibernate 4.3.x.

GORM 3.0 was the first release of GORM that was released separately to the Grails framework itself and was introduced in Grails 2.1.

More of the metaprogramming functions were refactored and replaced with AST transformations and APIs introduced that allowed GORM to operate against multiple database implementations including MongoDB.

The GORM API was separated from Hibernate and an SDK and TCK released for building compatible implementations.

GORM 2.0 evolved as part of Grails 2.0 and re-engineered some of the metaprogramming logic that relied on ExpandoMetaClass into a set of Groovy AST transformations.

These AST transformations relied on the Grails 2.x compiler infrastructure and hence this version of GORM was also only usable from within Grails.

The first version of GORM was a series of meta-programming functions that built on the capabilities of Groovy’s ExpandoMetaClass.

It was purely dynamic and integrated into the Grails framework and not usable without Grails and hence no actual distribution exists for this version and it is only available as part of Grails.

Due to several factors, the version of Spring that GORM 6.1.9 requires was updated to 4.3.14. This may impact Grails 3.2.x users that have an older version on their classpath. For Grails 3.2 users that would like to upgrade to GORM 6.1.9, add the following configuration to your build.gradle above the dependencies block.

GORM Async has been separated from GORM core and is no longer added by default to entities.

This was done in order to reduce the number of dependencies necessary to use GORM and to add flexibility in terms of the Async API used in the future.

In order to enable GORM Async you need to add the necessary dependency to build.gradle:

And make your entities implement the AsyncEntity trait:

The grails-datastore-simple and grails-datastore-gorm-test dependencies have been combined into a single grails-datastore-gorm-test dependency.

Unfortunately existing versions of Grails still depend on the old grails-datastore-simple dependency. And you may receive an error such as:

If you are upgrading you will need to exclude this dependency from grails-dependencies and remove any references from build.gradle. For example:

In previous versions of GORM the flush mode defaulted to AUTO. With this setting the session would be flushed with or without the presence of a transaction and before every query.

The frequent flushing of the session before queries can lead to unintended performance consequences if the behaviour of the AUTO is not fully understood by the developer.

With this in mind COMMIT is the new default flush mode in GORM 6, which will flush the session on transaction commit. You can restore the previous behaviour by configuring the flush mode in your application configuration (for example application.yml):

Configuration of multiple data sources has changed such that the default data source should be configured at the top level and additional data sources should be configured below the dataSources block. In other words instead of:

The configuration should instead be structured as follows:

In addition Hibernate specific configuration should be nested below each data source definition. For example:

With the aforementioned changes to the default flush mode, write operations that are not surrounded by a transaction may not propagate changes to the database unless flush:true is explicitly passed or the session explicitly flushed.

Not using a transaction around a write operation is considered bad practise as the connection is essentially in auto commit mode. If your code is structured this way we recommend that you add the necessary @Transactional transformation to surround the write operation.

Also note that Hibernate 5.2 and above throw an exception if you attempt a write operation outside of a transaction, and although this is not the case in the current version of GORM it is a possibility that GORM will follow this path and also throw exception for this case in the future.

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.

Previous versions of GORM shipped with a org.grails.orm.hibernate.cfg.IdentityEnumType class for altering the handling of enums. In order to support different versions of Hibernate 5.x which feature different signatures for the org.hibernate.usertype.UserType interface this class has been removed.

If you wish to obtain the same functionality you need to change your mapping block to:

Hibernate 5.2 includes many breaking API changes, in order to support Hibernate 5.2 several classes have been removed or rewritten. Including:

Most of these classes are considered internal, however if you have extended or references these classes you may need to modify your code appropriately.

Spring autowiring of domain instances has been disabled by default because it represents a performance bottleneck. If you are autowiring services into your domain instances you will need to re-enable using the mapping block:

Note that if enabled read performance will degrade.

Previous versions of GORM used property access to read and write values to entities by default. In other words the respective getters and setters were used when reflecting on the instances. GORM 6.1 uses field access by default instead, which means the field is used when reading and writing data via reflection to instances.

If you wish to continue to use property access this can be configured by altering the default mapping in your configuration:

The grails.gorm.failOnError setting can no longer be used to configure the packages to enable fail on error. Instead grails.gorm.failOnErrorPackages should be used.

GORM now includes its own implementation of dirty checking in order to improve performance. This implementation uses the DirtyCheckable trait to store changes in the entity itself so that Hibernate does not have to do internal array comparison to verify whether an object has changed or not.

There may however be some differences in behaviour, so if you wish to continue to use the Hibernate implementation you can re-enable it with the following configuration:

Some differences in behaviour and workarounds are covered below.

Domain objects can inherit from abstract base classes defined in the src directory. Previous versions of GORM performed dirty checking automatically on fields from any abstract base class. GORM 6.1 requires that the abstract base class be marked with the @DirtyCheck annotation to include the base class fields in domain object dirty checking:

Domain objects embed classes defined in the src directory. Previous versions of GORM performed dirty checking automatically on fields an embedded entity. GORM 6.1 requires that the embedded class be marked with the @DirtyCheck annotation to include the embedded class fields in domain object dirty checking:

Grails 3.2.x is based on Spring Boot 1.4.x which enforces Hibernate 5.0.x as the default version. If you want to continue to use Hibernate 4 you must explicitly declare the Hibernate 4 dependences in build.gradle.

Grails 3.1.x and below are based on Spring Boot 1.3.x which enforces Hibernate 4 as the default version of Hibernate, hence you have to use explicit versions to depend on Hibernate 5:

Grails 3.0.x enforces Spring 4.1.x as the Spring version, so if you want to use Hibernate 5 you must force an upgrade to Spring 4.2.x in build.gradle:

The resolutionStrategy is needed to enforce an upgrade to Spring 4.2.x which is required by Hibernate 5 support. This block is not needed if you are using Grails 3.1 or above.

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

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

The save() method is defined by the GormEntity trait.

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

This uses the static get(id) 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(id) 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(id) 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:

You may have reason to want to change how all domain classes map to the database. For example, by default GORM uses the native id generation strategy of the database, whether that be an auto-increment column or a sequence.

If you wish to globally change all domain classes to use a uuid strategy then you can specify that in the default mapping:

As you can see you can assign a closure that is equivalent to the mapping block used to customize how a domain class maps to a database table.

For validation, GORM applies a default set of constraints to all domain classes.

For example, by default all properties of GORM classes are not nullable by default. This means a value has to be supplied for each property, otherwise you will get a validation error.

In most cases this is what you want, but if you are dealing with a large number of columns, it may prove inconvinient.

You can alter the default constraints using Groovy configuration using the grails.gorm.default.constraints setting:

In the above example, all properties are allowed to be nullable by default, but limited to a size of between 1 and 20.

The HibernateConnectionSourceFactory is used to create a new Hibernate SessionFactory on startup.

If you are using Spring, it is registered as a Spring bean using the name hibernateConnectionSourceFactory and therefore can be overridden.

If you are not using Spring it can be passed to the constructor of the HibernateDatastore class on instantiation.

The HibernateConnectionSourceFactory has a few useful setters that allow you to specify a Hibernate Interceptor or MetadataContributor (Hibernate 5+ only).

HibernateMappingContextConfiguration is built by the HibernateConnectionSourceFactory, but a customized version can be specified using the hibernate.configClass setting in your configuration:

The customized version should extend HibernateMappingContextConfiguration and using this class you can add additional classes, packages, hbm.cfg.xml files and so on.

A many-to-one relationship is the simplest kind, and is defined with a property of the type of another domain class. Consider this example:

A one-to-many relationship is when one class, example Author, has many instances of another class, example Book. With GORM you define such a relationship with the hasMany setting:

In this case we have a unidirectional one-to-many. GORM will, by default, map this kind of relationship with a join table.

GORM will automatically inject a property of type java.util.Set into the domain class based on the hasMany setting. This can be used to iterate over the collection:

If you need "eager" fetching you can use the ORM DSL or specify eager fetching as part of a query

The default cascading behaviour is to cascade saves and updates, but not deletes unless a belongsTo is also specified:

If you have two properties of the same type on the many side of a one-to-many you have to use mappedBy to specify which the collection is mapped:

This is also true if you have multiple collections that map to different properties on the many side:

GORM supports many-to-many relationships by defining a hasMany on both sides of the relationship and having a belongsTo on the owned side of the relationship:

GORM maps a many-to-many using a join table at the database level. The owning side of the relationship, in this case Author, takes responsibility for persisting the relationship and is the only side that can cascade saves across.

For example this will work and cascade saves:

However this will only save the Book and not the authors!

This is the expected behaviour as, just like Hibernate, only one side of a many-to-many can take responsibility for managing the relationship.

As well as associations between different domain classes, GORM also supports mapping of basic collection types. For example, the following class creates a nicknames association that is a Set of String instances:

GORM will map an association like the above using a join table. You can alter various aspects of how the join table is mapped using the joinTable argument:

The example above will map to a table that looks like the following:

bunch_o_nicknames Table

At the database level GORM by default uses table-per-hierarchy mapping with a discriminator column called class so the parent class (Content) and its subclasses (BlogEntry, Book etc.), share the same table.

Table-per-hierarchy mapping has a down side in that you cannot have non-nullable properties with inheritance mapping. An alternative is to use table-per-subclass which can be enabled with the ORM DSL

However, excessive use of inheritance and table-per-subclass can result in poor query performance due to the use of outer join queries. In general our advice is if you’re going to use inheritance, don’t abuse it and don’t make your inheritance hierarchy too deep.

The upshot of inheritance is that you get the ability to polymorphically query. For example using the list() method on the Content super class will return all subclasses of Content:

By default when you define a relationship with GORM it is a java.util.Set which is an unordered collection that cannot contain duplicates. In other words when you have:

The books property that GORM injects is a java.util.Set. Sets guarantee uniqueness but not order, which may not be what you want. To have custom ordering you configure the Set as a SortedSet:

In this case a java.util.SortedSet implementation is used which means you must implement java.lang.Comparable in your Book class:

The result of the above class is that the Book instances in the books collection of the Author class will be ordered by their release date.

To keep objects in the order which they were added and to be able to reference them by index like an array you can define your collection type as a List:

In this case when you add new elements to the books collection the order is retained in a sequential list indexed from 0 so you can do:

The way this works at the database level is Hibernate creates a books_idx column where it saves the index of the elements in the collection to retain this order at the database level.

When using a List, elements must be added to the collection before being saved, otherwise Hibernate will throw an exception (org.hibernate.HibernateException: null index column for collection):

If ordering and uniqueness aren’t a concern (or if you manage these explicitly) then you can use the Hibernate Bag type to represent mapped collections.

The only change required for this is to define the collection type as a Collection:

Since uniqueness and order aren’t managed by Hibernate, adding to or removing from collections mapped as a Bag don’t trigger a load of all existing instances from the database, so this approach will perform better and require less memory than using a Set or a List.

If you want a simple map of string/value pairs GORM can map this with the following:

In this case the key and value of the map MUST be strings.

If you want a Map of objects then you can do this:

The static hasMany property defines the type of the elements within the Map. The keys for the map must be strings.

The Java Set type doesn’t allow duplicates. To ensure uniqueness when adding an entry to a Set association Hibernate has to load the entire associations from the database. If you have a large numbers of entries in the association this can be costly in terms of performance.

The same behavior is required for List types, since Hibernate needs to load the entire association to maintain order. Therefore it is recommended that if you anticipate a large numbers of records in the association that you make the association bidirectional so that the link can be created on the inverse side. For example consider the following code:

In this example the association link is being created by the child (Book) and hence it is not necessary to manipulate the collection directly resulting in fewer queries and more efficient code. Given an Author with a large number of associated Book instances if you were to write code like the following you would see an impact on performance:

You could also model the collection as a Hibernate Bag as described above.

For example, consider the following domain model:

It looks simple, right? And it is. Just set the location property to a Location instance and you have linked an author to a location. But see what happens when we run the following code:

An exception is thrown. If you look at the ultimate “caused by” exception, you’ll see the message “not-null property references a null or transient value: Author.location”. What’s going on?

A transient instance is one that isn’t attached to a Hibernate session. As you can see from the code, we are setting the Author.location property to a new Location instance, not one retrieved from the database. Hence the instance is transient. The obvious fix is to make the Location instance persistent by saving it:

Another option is to alter the cascade policy for the association. There are two ways to do that. One way is to define belongsTo on the Location class:

Note that this above syntax does not make the association bidirectional since no property is defined. A bidirectional example would be:

Alternatively if you prefer that the Location class has nothing to do with the Author class you can define the cascade policy in Author:

The above example will configure the cascade policy to cascade saves and updates, but not deletes.

In the case of a bidirectional one-to-many where the many side defines a belongsTo then the cascade strategy is set to "ALL" for the one side and "NONE" for the many side.

What this means is that whenever an instance of A is saved or updated. So will any instances of B. And, critically, whenever any instance of A is deleted so will all the associated instances of B!

In the case of a unidirectional one-to-many where the many side defines no belongsTo then the cascade strategy is set to "SAVE-UPDATE".

Since the belongsTo is not defined, this means that saves and updates will be cascaded from A to B, however deletes will not cascade!

Only when you define belongsTo in B or alter the cascading strategy of A will deletes be cascaded.

In the case of a bidirectional one-to-many where the many side does not define a belongsTo then the cascade strategy is set to "SAVE-UPDATE" for the one side and "NONE" for the many side.

So exactly like the previous case of a undirectional One-to-Many, without belongsTo definition no delete operations will be cascaded, but crucially saves and updates will by default. If you do not want saves and updates to cacade then you must alter the cascade policy of A:

In the case of a unidirectional many-to-one association that defines a belongsTo then the cascade strategy is set to "ALL" for the owning side of the relationship (A→B) and "NONE" from the side that defines the belongsTo (B→A)

You may be wondering why this association is a many-to-one and not a one-to-one. The reason is because it is possible to have multiple instances of B associated to the same instance of A. If you wish to define this association as a true one-to-one association a unique constraint is required:

Note that if you need further control over cascading behaviour, you can use the ORM DSL.

By default GORM classes are configured for optimistic locking. Optimistic locking is a feature of Hibernate which involves storing a version value in a special version column in the database that is incremented after each update.

The version column gets read into a version property that contains the current versioned state of persistent instance which you can access:

When you perform updates Hibernate will automatically check the version property against the version column in the database and if they differ will throw a StaleObjectException. This will roll back the transaction if one is active.

This is useful as it allows a certain level of atomicity without resorting to pessimistic locking that has an inherit performance penalty. The downside is that you have to deal with this exception if you have highly concurrent writes. This requires flushing the session:

The way you deal with the exception depends on the application. You could attempt a programmatic merge of the data or go back to the user and ask them to resolve the conflict.

Alternatively, if it becomes a problem you can resort to pessimistic locking.

Pessimistic locking is equivalent to doing a SQL "SELECT * FOR UPDATE" statement and locking a row in the database. This has the implication that other read operations will be blocking until the lock is released.

In GORM pessimistic locking is performed on an existing instance with the lock() method:

GORM will automatically deal with releasing the lock for you once the transaction has been committed.

However, in the above case what we are doing is "upgrading" from a regular SELECT to a SELECT..FOR UPDATE and another thread could still have updated the record in between the call to get() and the call to lock().

To get around this problem you can use the static lock(id) method that takes an id just like get(id):

In this case only SELECT..FOR UPDATE is issued.

As well as the lock(id) method you can also obtain a pessimistic locking using queries. For example using a dynamic finder:

Or using criteria:

You can use the isDirty() method to check if any field has been modified:

You can also check if individual fields have been modified:

You can use the getDirtyPropertyNames() method to retrieve the names of modified fields; this may be empty but will not be null:

You can use the getPersistentValue(fieldName) method to retrieve the value of a modified field:

A method expression in GORM is made up of the prefix such as findBy* followed by an expression that combines one or more properties. The basic form is:

The tokens marked with a ? are optional. Each comparator changes the nature of the query. For example:

In the above example the first query is equivalent to equality whilst the latter, due to the Like comparator, is equivalent to a SQL like expression.

The possible comparators include:

Notice that the last three require different numbers of method arguments compared to the rest, as demonstrated in the following example:

Method expressions can also use a boolean operator to combine two or more criteria:

In this case we’re using And in the middle of the query to make sure both conditions are satisfied, but you could equally use Or:

You can combine as many criteria as you like, but they must all be combined with And or all Or. If you need to combine And and Or or if the number of criteria creates a very long method name, just convert the query to a Criteria or HQL query.

Associations can also be used within queries:

In this case if the Author instance is not null we use it in a query to obtain all the Book instances for the given Author.

The same pagination and sorting parameters available on the list() method can also be used with dynamic finders by supplying a map as the final parameter:

The where() method accepts a closure that looks very similar to Groovy’s regular collection methods. The closure should define the logical criteria in regular Groovy syntax, for example:

The returned object is a DetachedCriteria instance, which means it is not associated with any particular database connection or session. This means you can use the where method to define common queries at the class level:

Query execution is lazy and only happens upon usage of the DetachedCriteria instance. If you want to execute a where-style query immediately there are variations of the findAll and find methods to accomplish this:

Each Groovy operator maps onto a regular criteria method. The following table provides a map of Groovy operators to methods:

It is possible use regular Groovy comparison operators and logic to formulate complex queries:

The Groovy regex matching operators map onto like and ilike queries unless the expression on the right hand side is a Pattern object, in which case they map onto an rlike query:

A between criteria query can be done by combining the in keyword with a range:

Finally, you can do isNull and isNotNull style queries by using null with regular comparison operators:

Since the return value of the where method is a DetachedCriteria instance you can compose new queries from the original query:

Note that you cannot pass a closure defined as a variable into the where method unless it has been explicitly cast to a DetachedCriteria instance. In other words the following will produce an error:

The above must be written as follows:

As you can see the closure definition is cast (using the Groovy as keyword) to a DetachedCriteria instance targeted at the Person class.

As mentioned previously you can combine regular Groovy logical operators (|| and &&) to form conjunctions and disjunctions:

You can also negate a logical comparison using !:

If you use a property name on both the left hand and right side of a comparison expression then the appropriate property comparison criteria is automatically used:

The following table described how each comparison operator maps onto each criteria property comparison method:

Associations can be queried by using the dot operator to specify the property name of the association to be queried:

You can group multiple criterion inside a closure method call where the name of the method matches the association name:

This technique can be combined with other top-level criteria:

For collection associations it is possible to apply queries to the size of the collection:

The following table shows which operator maps onto which criteria method for each size() comparison:

If you define a query for an association an alias is automatically generated for the query. For example the following query:

Will generate an alias for the owner association such as owner_alias_0. These generated aliases are fine for most cases, but are not useful if you want to later sort or use a projection on the results. For example the following query will fail:

If you plan to sort the results then an explicit alias should be used and these can be defined by simply declaring a variable in the where query:

By assigning the name of an association to a local variable it will automatically become an alias usable within the query itself and also for the purposes of sorting or projecting the results.

It is possible to execute subqueries within where queries. For example to find all the people older than the average age the following query can be used:

The following table lists the possible subqueries:

You can apply additional criteria to any subquery by using the of method and passing in a closure containing the criteria:

Since the property subquery returns multiple results, the criterion used compares all results. For example the following query will find all people younger than people with the surname "Simpson":

The support for subqueries has been extended. You can now use in with nested subqueries

Criteria and where queries can be seamlessly mixed:

Subqueries can be used with projections:

Correlated queries that span two domain classes can be used:

And support for aliases (cross query references) using simple variable declarations has been added to where queries:

There are several functions available to you within the context of a query. These are summarized in the table below:

For example the following query can be used to find all pet’s born in 2011:

You can also apply functions to associations:

Since each where method call returns a DetachedCriteria instance, you can use where queries to execute batch operations such as batch updates and deletes. For example, the following query will update all people with the surname "Simpson" to have the surname "Bloggs":

To batch delete records you can use the deleteAll method:

As demonstrated in the previous example you can group criteria in a logical OR using an or { } block:

This also works with logical AND:

And you can also negate using logical NOT:

All top level conditions are implied to be AND’d together.

Associations can be queried by having a node that matches the property name. For example say the Account class had many Transaction objects:

We can query this association by using the property name transactions as a builder node:

The above code will find all the Account instances that have performed transactions within the last 10 days. You can also nest such association queries within logical blocks:

Here we find all accounts that have either performed transactions in the last 10 days OR have been recently created in the last 10 days.

Projections may be used to customise the results. Define a "projections" node within the criteria builder tree to use projections. There are equivalent methods within the projections node to the methods found in the Hibernate Projections class:

When multiple fields are specified in the projection, a List of values will be returned. A single value will be returned otherwise.

If the raw value or simple object array returned by the criteria method doesn’t suit your needs, the result can be transformed with a ResultTransformer. Let’s say we want to transform the criteria results into a Map so that we can easily reference values by key:

Note that we’ve added an alias to each projection as an additional parameter to be used as the key. For this to work, all projections must have aliases defined, otherwise the corresponding map entry will not be built.

We can also transform the result into an object of our choosing via the Transformers.aliasToBean() method. In this case, we’ll transform it into an AccountsOverview:

Each alias must have a corresponding property or explicit setter on the bean otherwise an exception will be thrown.

The criteria DSL provides access to Hibernate’s SQL projection API.

The first argument to the sqlProjection method is the SQL which defines the projections. The second argument is a list of Strings which represent column aliases corresponding to the projected values expressed in the SQL. The third argument is a list of org.hibernate.type.Type instances which correspond to the projected values expressed in the SQL. The API supports all org.hibernate.type.Type objects but constants like INTEGER, LONG, FLOAT etc. are provided by the DSL which correspond to all of the types defined in org.hibernate.type.StandardBasicTypes.

Consider that the following table represents the data in the BOX table.

The query above would return results like this:

Each of the inner lists contains the 2 projected values for each Box, perimeter and area.

If only 1 value is being projected, the alias and the type do not need to be included in a list.

That query would return a single result with the value of 84 as the total area of all of the Box instances.

The DSL supports grouped projections with the sqlGroupProjection method.

The first argument to the sqlGroupProjection method is the SQL which defines the projections. The second argument represents the group by clause that should be part of the query. That string may be single column name or a comma separated list of column names. The third argument is a list of Strings which represent column aliases corresponding to the projected values expressed in the SQL. The fourth argument is a list of org.hibernate.type.Type instances which correspond to the projected values expressed in the SQL.

The query above is projecting the combined heights of boxes grouped by width and would return results that look like this:

Each of the inner lists contains 2 values. The first value is a box width and the second value is the sum of the heights of all of the boxes which have that width.

You can access Hibernate’s SQL Restrictions capabilities.

SQL Restrictions may be parameterized to deal with SQL injection vulnerabilities related to dynamic restrictions.

Also note that the SQL used here is not necessarily portable across databases.

You can use Hibernate’s ScrollableResults feature by calling the scroll method:

To quote the documentation of Hibernate ScrollableResults:

Contrary to JDBC, columns of results are numbered from zero.

If a node within the builder tree doesn’t match a particular criterion it will attempt to set a property on the Criteria object itself. This allows full access to all the properties in this class. This example calls setMaxResults and setFirstResult on the Criteria instance:

In the section on Eager and Lazy Fetching we discussed how to declaratively specify fetching to avoid the N+1 SELECT problem. However, this can also be achieved using a criteria query:

Notice the usage of the join method: it tells the criteria API to use a JOIN to fetch the named associations with the Task instances. It’s probably best not to use this for one-to-many associations though, because you will most likely end up with duplicate results. Instead, use the select fetch mode:

Although this approach triggers a second query to get the flights association, you will get reliable results - even with the maxResults option.

An important point to bear in mind is that if you include associations in the query constraints, those associations will automatically be eagerly loaded. For example, in this query:

the flights collection would be loaded eagerly via a join even though the fetch mode has not been explicitly set.

If you invoke the builder with no method name such as:

The build defaults to listing all the results and hence the above is equivalent to:

You can combine multiple criteria closures in the following way:

This technique requires that each criteria must refer to the same domain class (i.e. Airport). A more flexible approach is to use Detached Criteria, as described in the following section.

The primary point of entry for using the Detached Criteria is the DetachedCriteria class which accepts a domain class as the only argument to its constructor:

Once you have obtained a reference to a detached criteria instance you can execute where queries or criteria queries to build up the appropriate query. To build a normal criteria query you can use the build method:

Note that methods on the DetachedCriteria instance do not mutate the original object but instead return a new query. In other words, you have to use the return value of the build method to obtain the mutated criteria object:

Unlike regular criteria, Detached Criteria are lazy, in that no query is executed at the point of definition. Once a Detached Criteria query has been constructed then there are a number of useful query methods which are summarized in the table below:

As an example the following code will list the first 4 matching records sorted by the firstName property:

You can also supply additional criteria to the list method:

To retrieve a single result you can use the get or find methods (which are synonyms):

The DetachedCriteria class itself also implements the Iterable interface which means that it can be treated like a list:

In this case the query is only executed when the each method is called. The same applies to all other Groovy collection iteration methods.

You can also execute dynamic finders on DetachedCriteria just like on domain classes. For example:

Within the context of a regular criteria query you can use DetachedCriteria to execute subquery. For example if you want to find all people who are older than the average age the following query will accomplish that:

Notice that in this case the subquery class is the same as the original criteria query class (i.e. Person) and hence the query can be shortened to:

If the subquery class differs from the original criteria query then you will have to use the original syntax.

In the previous example the projection ensured that only a single result was returned (the average age). If your subquery returns multiple results then there are different criteria methods that need to be used to compare the result. For example to find all the people older than the ages 18 to 65 a gtAll query can be used:

The following table summarizes criteria methods for operating on subqueries that return multiple results:

The DetachedCriteria class can be used to execute batch operations such as batch updates and deletes. For example, the following query will update all people with the surname "Simpson" to have the surname "Bloggs":

To batch delete records you can use the deleteAll method:

In this case the value passed to the query is hard coded, however you can equally use named parameters:

Use the triple quoted strings to separate the query across multiple lines:

You can also perform pagination and sorting whilst using HQL queries. To do so simply specify the pagination options as a Map at the end of the method call and include an "ORDER BY" clause in the HQL:

Fired before an object is saved to the database

Fired before an existing object is updated

Fired before an object is deleted.

Notice the usage of withNewSession method above. Since events are triggered whilst Hibernate is flushing using persistence methods like save() and delete() won’t result in objects being saved unless you run your operations with a new Session.

Fortunately the withNewSession method lets you share the same transactional JDBC connection even though you’re using a different underlying Session.

Fired before an object is validated.

The beforeValidate method is run before any validators are run.

GORM supports an overloaded version of beforeValidate which accepts a List parameter which may include the names of the properties which are about to be validated. This version of beforeValidate will be called when the validate method has been invoked and passed a List of property names as an argument.

Either or both versions of beforeValidate may be defined in a domain class. GORM will prefer the List version if a List is passed to validate but will fall back on the no-arg version if the List version does not exist. Likewise, GORM will prefer the no-arg version if no arguments are passed to validate but will fall back on the List version if the no-arg version does not exist. In that case, null is passed to beforeValidate.

Fired immediately before an object is loaded from the database:

beforeLoad() is effectively a synonym for onLoad(), so only declare one or the other.

Fired immediately after an object is loaded from the database:

To register a custom event listener you need to subclass AbstractPersistenceEventListener (in package org.grails.datastore.mapping.engine.event) and implement the methods onPersistenceEvent and supportsEventType. You also must provide a reference to the datastore to the listener. The simplest possible implementation can be seen below:

The AbstractPersistenceEvent class has many subclasses (PreInsertEvent, PostInsertEvent etc.) that provide further information specific to the event. A cancel() method is also provided on the event which allows you to veto an insert, update or delete operation.

Once you have created your event listener you need to register it. If you are using Spring this can be done via the ApplicationContext:

If you are not using Spring then you can register the event listener using the getApplicationEventPublisher() method:

It is generally encouraged to use the non-Hibernate specific API described above, but if you need access to more detailed Hibernate events then you can define custom Hibernate-specific event listeners.

You can also register event handler classes in an application’s grails-app/conf/spring/resources.groovy or in the doWithSpring closure in a plugin descriptor by registering a Spring bean named hibernateEventListeners. This bean has one property, listenerMap which specifies the listeners to register for various Hibernate events.

The values of the Map are instances of classes that implement one or more Hibernate listener interfaces. You can use one class that implements all of the required interfaces, or one concrete class per interface, or any combination. The valid Map keys and corresponding interfaces are listed here:

For example, you could register a class AuditEventListener which implements PostInsertEventListener, PostUpdateEventListener, and PostDeleteEventListener using the following in an application:

or use this in a plugin:

If you define a dateCreated property it will be set to the current date for you when you create new instances. Likewise, if you define a lastUpdated property it will be automatically be updated for you when you change persistent instances.

If this is not the behaviour you want you can disable this feature with:

It is also possible to disable the automatic timestamping temporarily. This is most typically done in the case of a test where you need to define values for the dateCreated or lastUpdated in the past. It may also be useful for importing old data from other systems where you would like to keep the current values of the timestamps.

Timestamps can be temporarily disabled for all domains, a specified list of domains, or a single domain. To get started, you need to get a reference to the AutoTimestampEventListener. If you already have access to the datastore, you can execute the getAutoTimestampEventListener method. If you don’t have access to the datastore, inject the autoTimestampEventListener bean.

Once you have a reference to the event listener, you can execute withoutDateCreated, withoutLastUpdated, or withoutTimestamps. The withoutTimestamps method will temporarily disable both dateCreated and lastUpdated.

Example:

By default GORM classes use table-per-hierarchy inheritance mapping. This has the disadvantage that columns cannot have a NOT-NULL constraint applied to them at the database level. If you would prefer to use a table-per-subclass inheritance strategy you can do so as follows:

The mapping of the root Payment class specifies that it will not be using table-per-hierarchy mapping for all child classes.

You can customize how GORM generates identifiers for the database using the DSL. By default GORM relies on the native database mechanism for generating ids. This is by far the best approach, but there are still many schemas that have different approaches to identity.

To deal with this Hibernate defines the concept of an id generator. You can customize the id generator and the column it maps to as follows:

In this case we’re using one of Hibernate’s built in hilo generators that uses a separate table to generate ids.

Although you don’t typically specify the id field (GORM adds it for you) you can still configure its mapping like the other properties. For example to customise the column for the id property you can do:

GORM supports the concept of composite identifiers (identifiers composed from 2 or more properties). It is not an approach we recommend, but is available to you if you need it:

The above will create a composite id of the firstName and lastName properties of the Person class. To retrieve an instance by id you use a prototype of the object itself:

Domain classes mapped with composite primary keys must implement the Serializable interface and override the equals and hashCode methods, using the properties in the composite key for the calculations. The example above uses a HashCodeBuilder for convenience but it’s fine to implement it yourself.

Another important consideration when using composite primary keys is associations. If for example you have a many-to-one association where the foreign keys are stored in the associated table then 2 columns will be present in the associated table.

For example consider the following domain class:

In this case the address table will have an additional two columns called person_first_name and person_last_name. If you wish the change the mapping of these columns then you can do so using the following technique:

To get the best performance out of your queries it is often necessary to tailor the table index definitions. How you tailor them is domain specific and a matter of monitoring usage patterns of your queries. With GORM’s DSL you can specify which columns are used in which indexes:

Note that you cannot have any spaces in the value of the index attribute; in this example index:'Name_Idx, Address_Index' will cause an error.

As discussed in the section on Optimistic and Pessimistic Locking, by default GORM uses optimistic locking and automatically injects a version property into every class which is in turn mapped to a version column at the database level.

If you’re mapping to a legacy schema that doesn’t have version columns (or there’s some other reason why you don’t want/need this feature) you can disable this with the version method:

As described in the section on cascading updates, the primary mechanism to control the way updates and deletes cascade from one association to another is the static belongsTo property.

However, the ORM DSL gives you complete access to Hibernate’s transitive persistence capabilities using the cascade attribute.

Valid settings for the cascade attribute include:

To specify the cascade attribute simply define one or more (comma-separated) of the aforementioned settings as its value:

You saw in an earlier section that you can use composition (with the embedded property) to break a table into multiple objects. You can achieve a similar effect with Hibernate’s custom user types. These are not domain classes themselves, but plain Java or Groovy classes. Each of these types also has a corresponding "meta-type" class that implements org.hibernate.usertype.UserType.

The Hibernate reference manual has some information on custom types, but here we will focus on how to map them in GORM. Let’s start by taking a look at a simple domain class that uses an old-fashioned (pre-Java 1.5) type-safe enum class:

All we have done is declare the rating field the enum type and set the property’s type in the custom mapping to the corresponding UserType implementation. That’s all you have to do to start using your custom type. If you want, you can also use the other column settings such as "column" to change the column name and "index" to add it to an index.

Custom types aren’t limited to just a single column - they can be mapped to as many columns as you want. In such cases you explicitly define in the mapping what columns to use, since Hibernate can only use the property name for a single column. Fortunately, GORM lets you map multiple columns to a property using this syntax:

The above example will create "first_name" and "last_name" columns for the author property. You’ll be pleased to know that you can also use some of the normal column/property mapping attributes in the column definitions. For example:

The column definitions do not support the following attributes: type, cascade, lazy, cache, and joinTable.

One thing to bear in mind with custom types is that they define the SQL types for the corresponding database columns. That helps take the burden of configuring them yourself, but what happens if you have a legacy database that uses a different SQL type for one of the columns? In that case, override the column’s SQL type using the sqlType attribute:

Mind you, the SQL type you specify needs to still work with the custom type. So overriding a default of "varchar" with "text" is fine, but overriding "text" with "yes_no" isn’t going to work.

A derived property is one that takes its value from a SQL expression, often but not necessarily based on the value of one or more other persistent properties. Consider a Product class like this:

If the tax property is derived based on the value of price and taxRate properties then is probably no need to persist the tax property. The SQL used to derive the value of a derived property may be expressed in the ORM DSL like this:

Note that the formula expressed in the ORM DSL is SQL so references to other properties should relate to the persistence model not the object model, which is why the example refers to PRICE and TAX_RATE instead of price and taxRate.

With that in place, when a Product is retrieved with something like Product.get(42), the SQL that is generated to support that will look something like this:

Since the tax property is derived at runtime and not stored in the database it might seem that the same effect could be achieved by adding a method like getTax() to the Product class that simply returns the product of the taxRate and price properties. With an approach like that you would give up the ability query the database based on the value of the tax property. Using a derived property allows exactly that. To retrieve all Product objects that have a tax value greater than 21.12 you could execute a query like this:

Derived properties may be referenced in the Criteria API:

The SQL that is generated to support either of those would look something like this:

By default GORM uses Hibernate’s ImprovedNamingStrategy to convert domain class Class and field names to SQL table and column names by converting from camel-cased Strings to ones that use underscores as word separators. You can customize these on a per-class basis in the mapping closure but if there’s a consistent pattern you can specify a different NamingStrategy class to use.

Configure the class name to be used in grails-app/conf/application.groovy in the hibernate section, e.g.

You can also specify the name of the class and it will be loaded for you:

A third option is to provide an instance if there is some configuration required beyond calling the default constructor:

You can use an existing class or write your own, for example one that prefixes table names and column names:

In a Grails application you can create a Data Service in either src/main/groovy or grails-app/services. To write a Data Service you should create either an interface (although abstract classes can also be used, more about that later) and annotate it with the grails.gorm.services.Service annotation with the domain class the service applies to:

The @Service annotation is an AST transformation that will automatically implement the service for you. You can then obtain the service via Spring autowiring:

Or if you are using GORM standalone by looking it up from the HibernateDatastore instance:

The @Service transformation will look at the the method signatures of the interface and make a best effort to find a way to implement each method.

If a method cannot be implemented then a compilation error will occur. At this point you have the option to use an abstract class instead and provide an implementation yourself.

The @Service transformation will also generate a META-INF/services file for the service so it can be discovered via the standard Java service loader. So no additional configuration is necessary.

There are several advantages to Data Services that make them worth considering to abstract your persistence logic.

If you come across a method that GORM doesn’t know how to implement, then you can provide an implementation by using an abstract class.

For example: