(Quick Reference)

Timestamped Plugin - Reference Documentation

Authors: Diego Toharia

Version: 0.4

Table of Contents

1 Introduction

The Timestamped plugin aims to solve a small yet recurrent DRY problem when using Grails: the generation of the auto-timestamping properties, which right now has to be explicitly declared along with other properties in a domain class. This has two problems:
  • These properties aren't part of the domain class logic, so don't provide value to anyone examining the class.
  • If you wan't to switch from the standard class (java.util.Date) to joda-time, you would have to edit all the domain classes to change the property type.

By using this plugin, you will be provided with an AST transformation that will inject the properties so this two problems are mitigated. Also, Timestamped supports the joda-time plugin, so it will react to the plugin being installed or not by creating the timestamped properties in the proper class

You can check the classes provided by the plugin in the Groovy API section.

2 Installation

Install as a plugin

You can add the plugin to your project as a dependency by editing your project's BuildConfig.groovy as the following:

plugins {
       // specify dependencies here under either 'build', 'compile', 'runtime', 'test' or 'provided' scopes e.g.
       …
       compile 'timestamped:0.4'
    }

Install as a maven dependency

You can add the plugin as a precompiled maven dependency by editing your project's BuildConfig.groovy as the following:

repositories {
       …
       mavenRepo 'http://deigote.github.io/grails-timestamped/maven/releases/'
       grailsPlugins()
    }
    …
    dependencies {
        …
        compile 'com.deigote.grails-plugins:timestamped:0.4'
    }

Please note that the maven repo declaration must be above the grails plugins one.

Also, keep in mind that if you want to use timestamped insied another plugin, you will need to install it as a maven dependency. That way, the plugin will be precompiled and the AST transform will be applied to the plugins as well. Bear in mind that an AST transform must be compiled before compiling the project where its being applied. Grails first compiles the plugins and then the project, so if you add the dependency as a plugin, the AST will be compiled at plugin compilation time, so will only be available for the project but not for other plugins.

3 Usage

Basic usage

Using the plugin is fairly simple. You just need to annotate the domain classes as Timestamped and the dateCreated and lastUpdated properties will be injected at compile time:

package my.awesome.grails.app

import com.tado.timestamped.transform.Timestamped

@Timestamped class Car { Brand brand String modelName }

Specifiying the properties to inject

By default, all the autotimestamping properties will be injected (at the moment, Grails provides support for dateCreated and lastUpdated ), but you can specify which one you want to avoid:

  • If you don't want the lastUpdated property to be injected, you can specify to ignore the update event:

package my.awesome.grails.app

import com.tado.timestamped.transform.Timestamped

@Timestamped(update=false) // We won't update this, so we don't need the last updated date class Brand { String name Logo logo }

  • Accordingly If you don't want the dateCreated property to be injected, you can specify to ignore the update event:

package my.awesome.grails.app

import com.tado.timestamped.transform.Timestamped

@Timestamped(create=false) // We don't care about the creation date class Car { Brand brand String modelName }

Specifiying the class of the properties to inject

The Timestamped plugin will try to use the joda-time org.joda.time.Instant class for the timestamped properties, and will fallback to the old and not so good java.util.Date if the previous one is not found, but you can specify your own class:

package my.awesome.grails.app

import com.tado.timestamped.transform.Timestamped

@Timestamped(clazz='java.lang.Long') class Brand { String name Logo logo }

Of course, this only make sense if you provide the mechanisms to manage the autostamping persistence of the specified class, as the joda-time plugin does. The Timestamped plugin will search for the specified class using the default classloader, and if not found, it will try to use one of the supported ones. The priority is then:

  1. Your own specified class
  2. org.joda.time.Instant class
  3. java.util.Date class