11.1 Declarative Transactions 2.3.8

See the light - agile, industrial strength, rapid web application development made easy

(Quick Reference) # 11.1 Declarative Transactions - Reference Documentation Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari Version: 2.3.8 ## Table of Contents ## 11.1 Declarative Transactions ### Default Declarative Transactions Services are typically involved with coordinating logic between domain classes, and hence often involved with persistence that spans large operations. Given the nature of services, they frequently require transactional behaviour. You can use programmatic transactions with the withTransaction method, however this is repetitive and doesn't fully leverage the power of Spring's underlying transaction abstraction. Services enable transaction demarcation, which is a declarative way of defining which methods are to be made transactional. All services are transactional by default. To disable this set the `transactional` property to `false`:
    class CountryService {
        static transactional = false
    }
You may also set this property to `true` to make it clear that the service is intentionally transactional. Warning: dependency injection is the only way that declarative transactions work. You will not get a transactional service if you use the `new` operator such as `new BookService()` The result is that all methods are wrapped in a transaction and automatic rollback occurs if a method throws a runtime exception (i.e. one that extends `RuntimeException`) or an `Error`. The propagation level of the transaction is by default set to PROPAGATION_REQUIRED. Checked exceptions do not roll back transactions. Even though Groovy blurs the distinction between checked and unchecked exceptions, Spring isn't aware of this and its default behaviour is used, so it's important to understand the distinction between checked and unchecked exceptions. ### Custom Transaction Configuration Grails also provides `@Transactional` and `@NotTransactional` annotations for cases where you need more fine-grained control over transactions at a per-method level or need to specify an alternative propagation level. For example, the `@NotTransactional` annotation can be used to mark a particular method to be skipped when a class is annotated with `@Transactional`. The `grails.transaction.Transactional` annotation was first introduced in Grails 2.3. Prior to 2.3, Spring's @Transactional annotation was used. Annotating a service method with `Transactional` disables the default Grails transactional behavior for that service (in the same way that adding `transactional=false` does) so if you use any annotations you must annotate all methods that require transactions. In this example `listBooks` uses a read-only transaction, `updateBook` uses a default read-write transaction, and `deleteBook` is not transactional (probably not a good idea given its name).

    import org.springframework.transaction.annotation.Transactionalclass BookService {    @Transactional(readOnly = true)
        def listBooks() {
            Book.list()
        }    @Transactional
        def updateBook() {
            // …
        }    def deleteBook() {
            // …
        }
    }
You can also annotate the class to define the default transaction behavior for the whole service, and then override that default per-method. For example, this service is equivalent to one that has no annotations (since the default is implicitly `transactional=true`):

    import org.springframework.transaction.annotation.Transactional@Transactional
    class BookService {    def listBooks() {
            Book.list()
        }    def updateBook() {
            // …
        }    def deleteBook() {
            // …
        }
    }
This version defaults to all methods being read-write transactional (due to the class-level annotation), but the `listBooks` method overrides this to use a read-only transaction:

    import org.springframework.transaction.annotation.Transactional@Transactional
    class BookService {    @Transactional(readOnly = true)
        def listBooks() {
            Book.list()
        }    def updateBook() {
            // …
        }    def deleteBook() {
            // …
        }
    }
Although `updateBook` and `deleteBook` aren't annotated in this example, they inherit the configuration from the class-level annotation. For more information refer to the section of the Spring user guide on Using @Transactional. Unlike Spring you do not need any prior configuration to use `Transactional`; just specify the annotation as needed and Grails will detect them up automatically. ## 11.1.1 Transactions Rollback and the Session ### Understanding Transactions and the Hibernate Session When using transactions there are important considerations you must take into account with regards to how the underlying persistence session is handled by Hibernate. When a transaction is rolled back the Hibernate session used by GORM is cleared. This means any objects within the session become detached and accessing uninitialized lazy-loaded collections will lead to `LazyInitializationException`s. To understand why it is important that the Hibernate session is cleared. Consider the following example:

    class Author {
        String name
        Integer age    static hasMany = [books: Book]
    }
If you were to save two authors using consecutive transactions as follows:

    Author.withTransaction { status ->
        new Author(name: "Stephen King", age: 40).save()
        status.setRollbackOnly()
    }Author.withTransaction { status ->
        new Author(name: "Stephen King", age: 40).save()
    }
Only the second author would be saved since the first transaction rolls back the author `save()` by clearing the Hibernate session. If the Hibernate session were not cleared then both author instances would be persisted and it would lead to very unexpected results. It can, however, be frustrating to get `LazyInitializationException`s due to the session being cleared. For example, consider the following example:

    class AuthorService {    void updateAge(id, int age) {
            def author = Author.get(id)
            author.age = age
            if (author.isTooOld()) {
                throw new AuthorException("too old", author)
            }
        }
    }

    class AuthorController {    def authorService    def updateAge() {
            try {
                authorService.updateAge(params.id, params.int("age"))
            }
            catch(e) {
                render "Author books ${e.author.books}"
            }
        }
    }
In the above example the transaction will be rolled back if the `Author`'s age exceeds the maximum value defined in the `isTooOld()` method by throwing an `AuthorException`. The `AuthorException` references the author but when the `books` association is accessed a `LazyInitializationException` will be thrown because the underlying Hibernate session has been cleared. To solve this problem you have a number of options. One is to ensure you query eagerly to get the data you will need:
    class AuthorService {
        …
        void updateAge(id, int age) {
            def author = Author.findById(id, [fetch:[books:"eager"]])
            ...
In this example the `books` association will be queried when retrieving the `Author`. This is the optimal solution as it requires fewer queries then the following suggested solutions. Another solution is to redirect the request after a transaction rollback:

    class AuthorController {    AuthorService authorService    def updateAge() {
            try {
                authorService.updateAge(params.id, params.int("age"))
            }
            catch(e) {
                flash.message "Can't update age"
                redirect action:"show", id:params.id
            }
        }
    }
In this case a new request will deal with retrieving the `Author` again. And, finally a third solution is to retrieve the data for the `Author` again to make sure the session remains in the correct state:

    class AuthorController {    def authorService    def updateAge() {
            try {
                authorService.updateAge(params.id, params.int("age"))
            }
            catch(e) {
                def author = Author.read(params.id)
                render "Author books ${author.books}"
            }
        }
    }
### Validation Errors and Rollback A common use case is to rollback a transaction if there are validation errors. For example consider this service:

    import grails.validation.ValidationExceptionclass AuthorService {    void updateAge(id, int age) {
            def author = Author.get(id)
            author.age = age
            if (!author.validate()) {
                throw new ValidationException("Author is not valid", author.errors)
            }
        }
    }
To re-render the same view that a transaction was rolled back in you can re-associate the errors with a refreshed instance before rendering:

    import grails.validation.ValidationExceptionclass AuthorController {    def authorService    def updateAge() {
            try {
                authorService.updateAge(params.id, params.int("age"))
            }
            catch (ValidationException e) {
                def author = Author.read(params.id)
                author.errors = e.errors
                render view: "edit", model: [author:author]
            }
        }
    }
| Quick Reference (hide)