DDevelopment & Design

Hibernate Envers with Grails 2.1.0

Our client requires that every entity in his Grails application has to be audited with detailed information: who and when did exactly what? It is a perfect opportunity to use Hibernate Envers! It turned out not as straightforward as I thought, so I wa…

Our client requires that every entity in his Grails application has to be audited with detailed information: who and when did exactly what? It is a perfect opportunity to use Hibernate Envers! It turned out not as straightforward as I thought, so I want to share my experience with you.

Introduction

I use latest release of Grails with version 2.1.0. I’ve created a sample application on github for you as an example – SpOOnman/enversdemo. All files and techniques mentioned here can be found inside it. If you have other experiences with Grails and Envers working together, please share in comments.

Grails Envers plugin

First I’ve searched for a Grails plugin. I’ve found one outdated on google code and a (more modern) on github. This plugin is created by Lucas Ward and it has great introductionary blog post by author. This is a great place to start.

Unfortunately Lucas Ward’s plugin supports Grails up 1.3.7 and it comes with outdated Envers version. I’ve searched through forks and I’ve found most up-to-date fork by Matija Folnovic: https://github.com/mfolnovic/grails-envers-plugin. It supports Grails 2.1 out of the box. Edit: Matija pointed out that credit should go to Jay Hogan and Damir Murat for their work on upgrading Envers plugin to Grails 2.

Matija’s plugin is not packaged nor published so you have to package it by yourself:

Copy grails-envers-0.3-SNAPSHOT.zip (and rename to envers-0.3-SNAPSHOT.zip) to your application’s lib diretory or publish to your company maven repository if you have one. Last step is to include a plugin in your BuildConfig.groovy:

Audit with Envers!

It’s really easy to audit all entities with Envers. All you have to do is to use @Audit annotation on entities. SpOOnman/enversdemo audits Hotels and Bookings:

Envers plugin comes with some handy methods. For example Hotel.findAllRevisions() returns list of previous revisions. Once again I recommend a great blog post by Lucas Ward with many examples.

Grails and transactions

Grails has some glitches working with Envers. Envers is closely tied to database transactions. This means that it runs its listeners at the transaction end, when session is flushed. This is not always the case in Grails and it’s the cause of some problems. You need to make some small modifications to your application to be sure that Envers works fine.

  • controllers – you need to annotate your controllers (or separate controller methods) with @Transactional and for every save you need to flush a session manually, e.g. save(flush: true). Otherwise Envers may not be notified.
  • services in Grails are transactional by default. However you mey explicitily set them with static transactional = true to be sure that this is not altered. I recommend to use session flushing on every save as well.
  • BootStrap.groovy script is not transactional. If you want Envers to audit your changes in this script you need to wrap your inserts with transactions. You can achieve it by using withTransaction closure. You need session flushing too. Take a look at SpOOnman/enversdemo BootStrap.groovy for an example.
  • integration tests wrap every test in a separate transaction that is rolled back at the end of a test, hence Envers won’t work here. You need to disable wrapped transactions with static transactional = false. Remember that your changes are commited to database. To fulfill a contract of an empty database for every test you need to take care of cleaning up a database manually. Here is my sample integration test.

Add User to revision entities

By default Envers comes with a DefaultRevisionEntity class and creates its instance for every change on audited instance. It keeps information about entity revision, date and modification type. It lacks information about a user that made a change. I want to extend it.

There is already a code inside a plugin (here and here) but it’s not packaged with a plugin itself. I guess it’s because it adds dependency to Spring Security. This not a problem for me since I already use Spring Security plugin already in my application. I decided to add missing classes inside my application.

First I need a domain class – UserRevisionEntity. New instance of this class is created for every revision saved by Envers. It is a simple domain class with some extra annotations:

Notice that I’ve made currentUser field nullable. There may be some actions that doesn’t require user to be logged in. Also, there is no user while executing BootStrap.groovy script.

Annotations @RevisionNumber and @RevisionTimestamp are required by Envers as described in documentation. @RevisionEntity annotation configures Envers to use non-default listener – SpringSecurityRevisionListener. It looks simple:

SpringSecurityRevisionListener’s newRevision method fills each UserRevisionEntity instances with currently logged User.

Configuration

Envers offers some configuration options listed on documentation page. Options can be set in persistence.xml. However in Grails there is no persistence.xml. You can add it (and Grails supports it), but I’ve found other way to configure properties. I use System.setProperties to configure Envers and I place it in grails-app/conf/spring/resources.groovy. This is an example to change Envers tables’ prefix and suffix:

Testing

Testing Envers makes sense only with Grails integration tests. As I’ve mentioned earlier you must disable transactions that wrap your tests in order for Envers listeners to work. Also make sure you use withTransaction, session flushing and you’ve marked your controllers as @Transactional. There rules all stand in integration tests too. Example integration test can look like this:

Summary

Hibernate Envers does a great job auditing my application. It is easy to use, despite all the small glitches I’ve mentioned here. Special thanks to plugin authors that package Envers library in a plugin that can be used out of the box. I really recommend it! It would be great to hear all your thoughts on Envers and Grails working together so I can improve this post for others too.

Update 12.04.2013

Lucas Ward has posted updaate entry on Grails Hibernate Envers plugin here: http://www.lucasward.net/2013/04/grails-envers-plugin-update.html. Thanks!

— Previous article

Numery masowo przenoszone do Play

Next article —

Indeksy na kolumnach z wartościami nullowymi cz. 1

You May Also Like
DDevelopment & Design

Oracle SQL Developer dla MSSQL

Ostatnio poznałem ciekawe narzędzie do manipulacji schematami bazy danych. Oracle SQL Developer się nazywa i nie służy tylko do baz Oracle. Ponieważ pracuję obecnie przy projekcie opartym o MS SQL, to potrzebowałem możliwości połączenia z M...Ostatnio poznałem ciekawe narzędzie do manipulacji schematami bazy danych. Oracle SQL Developer się nazywa i nie służy tylko do baz Oracle. Ponieważ pracuję obecnie przy projekcie opartym o MS SQL, to potrzebowałem możliwości połączenia z M...
DDevelopment & Design

Grails session timeout without XML

This article shows clean, non hacky way of configuring featureful event listeners for Grails application servlet context. Feat. HttpSessionListener as a Spring bean example with session timeout depending on whether user account is premium or not.

Common approaches

Speaking of session timeout config in Grails, a default approach is to install templates with a command. This way we got direct access to web.xml file. Also more unnecessary files are created. Despite that unnecessary files are unnecessary, we should also remember some other common knowledge: XML is not for humans.

Another, a bit more hacky, way is to create mysterious scripts/_Events.groovy file. Inside of which, by using not less enigmatic closure: eventWebXmlEnd = { filename -> ... }, we can parse and hack into web.xml with a help of XmlSlurper.
Even though lot of Grails plugins do it similar way, still it’s not really straightforward, is it? Besides, where’s the IDE support? Hello!?

Examples of both above ways can be seen on StackOverflow.

Simpler and cleaner way

By adding just a single line to the already generated init closure we have it done:
class BootStrap {


    def init = { servletContext ->    

        servletContext.addListener(OurListenerClass)    

    }    

}

Allrighty, this is enough to avoid XML. Sweets are served after the main course though :)

Listener as a Spring bean

Let us assume we have a requirement. Set a longer session timeout for premium user account.
Users are authenticated upon session creation through SSO.

To easy meet the requirements just instantiate the CustomTimeoutSessionListener as Spring bean at resources.groovy. We also going to need some source of the user custom session timeout. Let say a ConfigService.
beans = {    

    customTimeoutSessionListener(CustomTimeoutSessionListener) {    

        configService = ref('configService')    

    }    

}

With such approach BootStrap.groovy has to by slightly modified. To keep control on listener instantation, instead of passing listener class type, Spring bean is injected by Grails and the instance passed:
class BootStrap {


    def customTimeoutSessionListener


    def init = { servletContext ->    

        servletContext.addListener(customTimeoutSessionListener)

    }    

}

An example CustomTimeoutSessionListener implementation can look like:
import javax.servlet.http.HttpSessionEvent    

import javax.servlet.http.HttpSessionListener    

import your.app.ConfigService    


class CustomTimeoutSessionListener implements HttpSessionListener {    


    ConfigService configService


    @Override    

    void sessionCreated(HttpSessionEvent httpSessionEvent) {    

        httpSessionEvent.session.maxInactiveInterval = configService.sessionTimeoutSeconds

    }    


    @Override    

    void sessionDestroyed(HttpSessionEvent httpSessionEvent) { /* nothing to implement */ }    

}
Having at hand all power of the Spring IoC this is surely a good place to load some persisted user’s account stuff into the session or to notify any other adequate bean about user presence.

Wait, what about the user context?

Honest answer is: that depends on your case. Yet here’s an example of getSessionTimeoutMinutes() implementation using Spring Security:
import org.springframework.security.core.context.SecurityContextHolder    


class ConfigService {


    static final int 3H = 3 * 60 * 60

    static final int QUARTER = 15 * 60


    int getSessionTimeoutSeconds() {    


        String username = SecurityContextHolder.context?.authentication?.principal    

        def account = Account.findByUsername(username)    


        return account?.premium ? 3H : QUARTER

    }    

}
This example is simplified. Does not contain much of defensive programming. Just an assumption that principal is already set and is a String - unique username. Thanks to Grails convention our ConfigService is transactional so the Account domain class can use GORM dynamic finder.
OK, config fetching implementation details are out of scope here anyway. You can get, load, fetch, obtain from wherever you like to. Domain persistence, principal object, role config, external file and so on...

Any gotchas?

There is one. When running grails test command, servletContext comes as some mocked class instance without addListener method. Thus we going to have a MissingMethodException when running tests :(

Solution is typical:
def init = { servletContext ->

    if (Environment.current != Environment.TEST) {    

        servletContext.addListener(customTimeoutSessionListener)    

    }    

}
An unnecessary obstacle if you ask me. Should I submit a Jira issue about that?

TL;DR

Just implement a HttpSessionListener. Create a Spring bean of the listener. Inject it into BootStrap.groovy and call servletContext.addListener(injectedListener).
DDevelopment & Design

Grails render as JSON catch

One of a reasons your controller doesn't render a proper response in JSON format might be wrong package name that you use. It is easy to overlook. Import are on top of a file, you look at your code and everything seems to be fine. Except response is still not in JSON format.

Consider this simple controller:

class RestJsonCatchController {
def grailsJson() {
render([first: 'foo', second: 5] as grails.converters.JSON)
    }

def netSfJson() {
render([first: 'foo', second: 5] as net.sf.json.JSON)
    }
}

And now, with finger crossed... We have a winner!

$ curl localhost:8080/example/restJsonCatch/grailsJson
{"first":"foo","second":5}
$ curl localhost:8080/example/restJsonCatch/netSfJson
{first=foo, second=5}

As you can see only grails.converters.JSON converts your response to JSON format. There is no such converter for net.sf.json.JSON, so Grails has no converter to apply and it renders Map normally.

Conclusion: always carefully look at your imports if you're working with JSON in Grails!

Edit: Burt suggested that this is a bug. I've submitted JIRA issue here: GRAILS-9622 render as class that is not a codec should throw exception