GORM for Hibernate 7

The Grails 8 / Hibernate 7 query API keeps the Hibernate 5 calling conventions while making the idiomatic Groovy query form injection-safe by default. There is no breaking change here: the methods that accepted a plain String on Hibernate 5 still do.

DefaultSchemaHandler now quotes schema names using the JDBC identifier quote character (connection.metaData.identifierQuoteString) before executing SET SCHEMA and CREATE SCHEMA DDL statements. This prevents SQL injection via tenant identifiers.

Embedded quote characters are stripped from the schema name before quoting. If the JDBC driver does not support identifier quoting (returns " " or empty), the name is used unquoted as before — no behaviour change for such drivers.

No application changes are required unless your tenant resolver intentionally produces schema names containing the database’s identifier quote character (typically " or `` ` ``), in which case those characters will be stripped.

Grails proxies answer identifier access (id, getId(), ident()) and metaClass access without initializing the proxy. By default, calling toString() on an uninitialized proxy initializes it and delegates to the domain class’s own toString() implementation.

If you prefer toString() to also avoid initialization — for example to keep log statements from triggering database access — enable lazy toString() in application.yml:

With this setting enabled, toString() on an uninitialized proxy returns entityName:id (for example com.example.Author:1) without initializing it. Once the proxy has been initialized, toString() always delegates to the domain class’s implementation.

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.

To reload an already-loaded entity’s database state and version directly under a pessimistic WRITE lock, pass lock: true to the refresh(Map) instance method. The lock is acquired before the state is read, so the reload sees the committed state the lock protects. Unlike calling lock() first, the already-loaded version is never checked, and unlike calling refresh() first, no competing update can slip in between. The same instance is returned.

To request a lock other than a pessimistic WRITE lock, pass a jakarta.persistence.LockModeType (or its name) as the lock argument, for example book.refresh(lock: LockModeType.PESSIMISTIC_READ). lock: true is equivalent to lock: LockModeType.PESSIMISTIC_WRITE, and the semantics of each mode are those of the JPA LockModeType of the same name. A value that is neither a boolean, a LockModeType, nor the name of one throws IllegalArgumentException.

The instance must be attached to the current session; refreshing a detached instance under a lock throws IllegalArgumentException, so re-attach it with attach() first. book.refresh() is unchanged, and book.refresh([:]), book.refresh(lock: false) or book.refresh(lock: LockModeType.NONE) behave exactly like it: a plain refresh with no lock and no transaction requirement. To lock by identifier and reload at the same time, use Book.lock(id, refresh: true) as described above.

The lock applies to the refreshed entity’s own row. Associated entities reloaded through a refresh cascade are not guaranteed to be locked: databases that cannot lock outer-joined rows, such as H2 and PostgreSQL, leave those rows unlocked, and GORM does not issue follow-on locking queries for them.

Refreshing under a lock is supported by GORM for Hibernate 5 and Hibernate 7. Datastores that do not support it throw UnsupportedOperationException rather than silently falling back to a plain refresh.

The database and transaction isolation level determine which state is visible to the locked refresh. refresh(lock: true) does not override isolation rules or guarantee that every concurrent attempt succeeds. Deadlocks, lock timeouts, and transaction serialization failures remain possible.

mutex(Closure) locks the instance exclusively for the scope of the closure and returns the closure’s result:

It reloads the instance’s state and version under the lock, so a transaction that committed to the row after it was loaded is waited for rather than reported as an optimistic locking failure, and the closure runs on the committed state. The lock is always exclusive; there is no argument to select another mode, because a shared or optimistic lock would not give the closure mutual exclusion.

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 sort value must be a property path made up of identifiers separated by dots, such as "title" or "author.name", that resolves through the domain class mapping. Anything else, for example a value carrying a second expression or a function call, is rejected with an IllegalArgumentException before the query is built, so request parameters can be passed through safely. A dotted key whose first segment is not a property of the domain class is left for the query implementation to resolve, so aliases created with createAlias or declared in a where query can still be sorted on; a bare name must be a property of the domain class. The order value must be "asc" or "desc", case-insensitive and ignoring surrounding whitespace; anything else is rejected in the same way. The same checks apply to the sort and order arguments of list(), of a criteria query’s list() call and of a where query’s list() call, and to the order argument of listOrderBy*, so a value is never silently coerced on one entry point and rejected on another.

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:

In Hibernate 7, the criteria builder has been completely rewritten to leverage the JPA Criteria API. The HibernateCriteriaBuilder implements the GORM criteria DSL and provides seamless integration with Hibernate 7 features.

The DSL supports all standard GORM criteria methods such as eq, ne, gt, lt, ge, le, between, like, ilike, in, isNull, isNotNull, isEmpty, isNotEmpty, and more.

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.

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

Common projections include count, countDistinct, groupProperty, avg, min, max, sum, id, and property.

You can restrict the results with a native SQL condition, which is added to the where clause of the query as written, in parentheses.

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

Each ? in the SQL is bound to the value at the same position in the list, so the number of ? placeholders must match the number of values, and a value must not be null. A ? in a string literal, such as '%?', in a quoted identifier or in a comment is not a placeholder.

When the query joins other tables, qualify the columns with {alias}, which stands for the table alias of the queried class, so that a column a joined table also has is not ambiguous:

Inside an association block, such as pets { ... }, the condition restricts the association, as the other criteria in the block do, and {alias} stands for the table alias of the association instead. This includes an association block inside an and, or or not block.

A detached criteria accepts sqlRestriction too.

The builder allows setting properties that control how the query is executed.

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 the criteria.

The Hibernate 7 criteria builder supports several advanced features:

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

To quote the Hibernate documentation on ScrollableResults:

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

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 builder 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 grails.gorm.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:

A detached criteria also accepts sqlRestriction, which restricts the results with a native SQL condition as in a criteria query. {alias} stands for the table alias of the class of the detached criteria, also when the detached criteria is used as a subquery:

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 grails.gorm.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:

Fired before an object is saved to the database

Fired before an existing object is updated

Notice the usage of autowire true above. This is required for the bean securityService to be injected.

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.

GORM for Hibernate 7 also publishes a PersistEvent (eventType Persist) whenever an entity is persisted, whether explicitly through save() or by a cascade when the session flushes, and a MergeEvent (eventType Merge) whenever an entity is merged. Both are published before Hibernate performs the operation and cannot be cancelled; the exception is an application that registers a listener of its own for merge or persist, in which case that listener performs the operation and GORM’s event is published after it. A MergeEvent carries the detached instance passed to the merge rather than the managed copy it produces, and neither event is published for an uninitialized proxy.

GORM for Hibernate 5 publishes a SaveOrUpdateEvent (eventType SaveOrUpdate) when an entity is saved, and publishes no event for a merge. A listener that switches over every eventType and runs against either version should therefore handle all three values.

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:

If work inside the closure runs on other threads (for example an executor-based import), the suppression must be propagated to those threads explicitly. Capture the state with captureTimestampSuppression and apply it on the executing thread with withTimestampSuppression:

The captured state is immutable and may be applied on any number of threads, even after the capturing closure has completed.