14 Grails and Spring

14.1 The Underpinnings of Grails

Grails leverages Spring MVC in the following areas:

• Basic controller logic - Grails subclasses Spring's DispatcherServlet and uses it to delegate onto Grails controllers
• Data Binding and Validation - Grails' validation and data binding capabilities are built on those provided by Spring
• Runtime configuration - Grails' entire runtime convention based system is wired together by a Spring ApplicationContext
• Transactions - Grails uses Spring's transaction management in GORM

In other words Grails has Spring embedded running all the way through it.

The Grails ApplicationContext

Spring developers are often keen to understand how the Grails ApplicationContext instance is constructed. The basics of it are as follows.

• Grails constructs a parent ApplicationContext from the web-app/WEB-INF/applicationContext.xml. This ApplicationContext sets up the GrailsApplication instance and the GrailsPluginManager.
• Using this ApplicationContext as a parent Grails' analyses the conventions with the GrailsApplication instance and constructs a child ApplicationContext that is used as the root ApplicationContext of the web application

Configured Spring Beans

Most of Grails' configuration happens at runtime. Each plug-in may configure Spring beans that are registered with the ApplicationContext. For a reference as to which beans are configured refer to the reference guide which describes each of the Grails plug-ins and which beans they configure.

14.2 Configuring Additional Beans

Using XML

Beans can be configured using the grails-app/conf/spring/resources.xml file of your Grails application. This file is typical Spring XML file and the Spring documentation has an excellent reference on how to go about configuration Spring beans. As a trivial example you can configure a bean with the following syntax:

<bean id="myBean" class="my.company.MyBeanImpl"></bean>

Once configured the bean, in this case named myBean, can be auto-wired into most Grails types including controllers, tag libraries, services and so on:

class ExampleController {
     def myBean
}

Referencing Existing Beans

Beans declared in resources.xml can also reference Grails classes by convention. For example if you need a reference to a service such as BookService in your bean you use the property name representation of the class name. In the case of BookService this would be bookService. For example:

<bean id="myBean" class="my.company.MyBeanImpl">
	<property name="bookService" ref="bookService" />	
</bean>

The bean itself would of course need a public setter, which in Groovy is defined like this:

package my.company
class MyBeanImpl {
	BookService bookService
}

or in Java like this:

package my.company;
class MyBeanImpl {
    private BookService bookService;
    public void setBookService(BookService theBookService) {
        this.bookService = theBookService;
    }
}

Since much of Grails configuration is done at runtime by convention many of the beans are not declared anywhere, but can still be referenced inside your Spring configuration. For example if you need a reference to the Grails DataSource you could do:

<bean id="myBean" class="my.company.MyBeanImpl">
    <property name="bookService" ref="bookService" />	
    <property name="dataSource" ref="dataSource" />
</bean>

Or if you need the Hibernate SessionFactory this will work:

<bean id="myBean" class="my.company.MyBeanImpl">
    <property name="bookService" ref="bookService" />	
    <property name="sessionFactory" ref="sessionFactory" />
</bean>

For a full reference of the available beans see the Plug-in reference in the reference guide.

Using the Spring DSL

If you want to use the Spring DSL that Grails provides then you need to create a grails-app/conf/spring/resources.groovy file and define a property called beans that is assigned a block:

beans = {
    // beans here
}

The same configuration for the XML example could be represented as:

beans = {
    myBean(my.company.MyBeanImpl) {
        bookService = ref("bookService")
    }	
}

The main advantage of this way is that you can now mix logic in within your bean definitions, for example based on the environment:

import grails.util.*
beans = {
    switch(Environment.current) {
    case Environment.PRODUCTION:
        myBean(my.company.MyBeanImpl) {
            bookService = ref("bookService")
        }
        break
    case Environment.DEVELOPMENT:
        myBean(my.company.mock.MockImpl) {
            bookService = ref("bookService")
        }	
        break
    }	
}

The GrailsApplication object can be accessed by the application variable, which can be used to access config (amongst other things):

import grails.util.*
beans = {
    if (application.config.my.company.mockService) {
        myBean(my.company.mock.MockImpl) {
            bookService = ref("bookService")
        }   
    } else {
        myBean(my.company.MyBeanImpl) {
            bookService = ref("bookService")
        }
    }
}

14.3 Runtime Spring with the Beans DSL

In addition, Spring's regular way of configuration (via XML) is essentially static and very difficult to modify and configure at runtime other than programmatic XML creation which is both error prone and verbose. Grails' BeanBuilder changes all that by making it possible to programmatically wire together components at runtime thus allowing you to adapt the logic based on system properties or environment variables.

This enables the code to adapt to its environment and avoids unnecessary duplication of code (having different Spring configs for test, development and production environments)

The BeanBuilder class

Grails provides a grails.spring.BeanBuilder class that uses dynamic Groovy to construct bean definitions. The basics are as follows:

import org.apache.commons.dbcp.BasicDataSource
import org.codehaus.groovy.grails.orm.hibernate.ConfigurableLocalSessionFactoryBean
import org.springframework.context.ApplicationContext
def bb = new grails.spring.BeanBuilder()
bb.beans {
    dataSource(BasicDataSource) {
        driverClassName = "org.hsqldb.jdbcDriver"
        url = "jdbc:hsqldb:mem:grailsDB"
        username = "sa"
        password = ""
    }
    sessionFactory(ConfigurableLocalSessionFactoryBean) {
        dataSource = dataSource
        hibernateProperties = [ "hibernate.hbm2ddl.auto":"create-drop",
                                "hibernate.show_sql":true  ]
    }
}
ApplicationContext appContext = bb.createApplicationContext()

Within plug-ins and the grails-app/conf/spring/resources.groovy file you don't need to create a new instance of BeanBuilder. Instead the DSL is implicitly available inside the doWithSpring and beans blocks respectively.

The above example shows how you would configure Hibernate with an appropriate data source with the BeanBuilder class.

Essentially, each method call (in this case dataSource and sessionFactory calls) map to the name of the bean in Spring. The first argument to the method is the bean's class, whilst the last argument is a block. Within the body of the block you can set properties on the bean using standard Groovy syntax

Bean references are resolved automatically be using the name of the bean. This can be seen in the example above with the way the sessionFactory bean resolves the dataSource reference.

Certain special properties related to bean management can also be set by the builder, as seen in the following code:

sessionFactory(ConfigurableLocalSessionFactoryBean) { bean ->
    // Autowiring behaviour. The other option is 'byType'. [autowire]
    bean.autowire = 'byName'
    // Sets the initialisation method to 'init'. [init-method]
    bean.initMethod = 'init'
    // Sets the destruction method to 'destroy'. [destroy-method]
    bean.destroyMethod = 'destroy'
    // Sets the scope of the bean. [scope]
    bean.scope = 'request'
    dataSource = ref('dataSource')
    hibernateProperties = ["hibernate.hbm2ddl.auto": "create-drop",
                           "hibernate.show_sql":     "true"]
}

The strings in square brackets are the names of the equivalent bean attributes in Spring's XML definition.

Using BeanBuilder with Spring MVC

If you want to take advantage of BeanBuilder in a regular Spring MVC application you need to make sure the grails-spring-<version>.jar file is in your classpath. Once that is done you can need to set the following <context-param> values in your /WEB-INF/web.xml file:

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/applicationContext.groovy</param-value>
</context-param>
<context-param>
    <param-name>contextClass</param-name>
    <param-value>
      org.codehaus.groovy.grails.commons.spring.GrailsWebApplicationContext
    </param-value>
</context-param>

With that done you can then create a /WEB-INF/applicationContext.groovy file that does the rest:

beans {
	dataSource(org.apache.commons.dbcp.BasicDataSource) {
        driverClassName = "org.hsqldb.jdbcDriver"
        url = "jdbc:hsqldb:mem:grailsDB"
        username = "sa"
        password = ""
    }
}

Loading Bean Definitions from the File System

You can use the BeanBuilder class to load external Groovy scripts that define beans using the same path matching syntax defined here. Example:

def bb = new BeanBuilder()
bb.loadBeans("classpath:*SpringBeans.groovy")
def applicationContext = bb.createApplicationContext()

Here the BeanBuilder will load all Groovy files on the classpath ending with SpringBeans.groovy and parse them into bean definitions. An example script can be seen below:

beans {
    dataSource(BasicDataSource) {
        driverClassName = "org.hsqldb.jdbcDriver"
        url = "jdbc:hsqldb:mem:grailsDB"
        username = "sa"
        password = ""
    }
    sessionFactory(ConfigurableLocalSessionFactoryBean) {
        dataSource = dataSource
        hibernateProperties = [ "hibernate.hbm2ddl.auto":"create-drop",
                                "hibernate.show_sql":true  ]
    }
}

Adding Variables to the Binding (Context)

If you're loading beans from a script you can set the binding to use by creating a Groovy Binding object:

def binding = new Binding()
binding.foo = "bar"
def bb = new BeanBuilder()
bb.binding = binding
bb.loadBeans("classpath:*SpringBeans.groovy")
def ctx = bb.createApplicationContext()

14.4 The BeanBuilder DSL Explained

Using Constructor Arguments

Constructor arguments can be defined using parameters to each method that reside between the class of the bean and the last closure:

bb.beans {
    exampleBean(MyExampleBean, "firstArgument", 2) {
        someProperty = [1,2,3]
    }
}

Configuring the BeanDefinition (Using factory methods)

The first argument to the closure is a reference to the bean configuration instance, which you can use to configure factory methods and invoke any method on the AbstractBeanDefinition class:

bb.beans {
    exampleBean(MyExampleBean) { bean ->
        bean.factoryMethod = "getInstance"
        bean.singleton = false
        someProperty = [1,2,3]
    }
}

As an alternative you can also use the return value of the bean defining method to configure the bean:

bb.beans {
    def example = exampleBean(MyExampleBean) {
        someProperty = [1,2,3]
    }
    example.factoryMethod = "getInstance"
}

Using Factory beans

Spring defines the concept of factory beans and often a bean is created not from a class, but from one of these factories. In this case the bean has no class and instead you must pass the name of the factory bean to the bean:

bb.beans {
    myFactory(ExampleFactoryBean) {
        someProperty = [1,2,3]
    }
    myBean(myFactory) {
        name = "blah"
    }
}

Note in the example above instead of a class we pass a reference to the myFactory bean into the bean defining method. Another common task is provide the name of the factory method to call on the factory bean. This can be done using Groovy's named parameter syntax:

bb.beans {
    myFactory(ExampleFactoryBean) {
        someProperty = [1,2,3]
    }
    myBean(myFactory:"getInstance") {
        name = "blah"
    }
}

Here the getInstance method on the ExampleFactoryBean bean will be called in order to create the myBean bean.

Creating Bean References at Runtime

Sometimes you don't know the name of the bean to be created until runtime. In this case you can use a string interpolation to invoke a bean defining method dynamically:

def beanName = "example"
bb.beans {
    "${beanName}Bean"(MyExampleBean) {
        someProperty = [1,2,3]
    }
}

In this case the beanName variable defined earlier is used when invoking a bean defining method.

Furthermore, because sometimes bean names are not known until runtime you may need to reference them by name when wiring together other beans. In this case using the ref method:

def beanName = "example"
bb.beans {
    "${beanName}Bean"(MyExampleBean) {
        someProperty = [1,2,3]
    }
    anotherBean(AnotherBean) {
        example = ref("${beanName}Bean")
    }
}

Here the example property of AnotherBean is set using a runtime reference to the exampleBean. The ref method can also be used to refer to beans from a parent ApplicationContext that is provided in the constructor of the BeanBuilder:

ApplicationContext parent = ...//
der bb = new BeanBuilder(parent)
bb.beans {
    anotherBean(AnotherBean) {
        example = ref("${beanName}Bean", true)
    }
}

Here the second parameter true specifies that the reference will look for the bean in the parent context.

Using Anonymous (Inner) Beans

You can use anonymous inner beans by setting a property of the bean to a block that takes an argument that is the bean type:

bb.beans {
    marge(Person.class) {
        name = "marge"
        husband =  { Person p ->
            name = "homer"
            age = 45
            props = [overweight:true, height:"1.8m"]
        }
        children = [bart, lisa]
    }
    bart(Person) {
        name = "Bart"
        age = 11
    }
    lisa(Person) {
        name = "Lisa"
        age = 9
    }
}

In the above example we set the marge bean's husband property to a block that creates an inner bean reference. Alternatively if you have a factory bean you can ommit the type and just use passed bean definition instead to setup the factory:

bb.beans {
    personFactory(PersonFactory.class)
    marge(Person.class) {
        name = "marge"
        husband =  { bean ->
            bean.factoryBean = "personFactory"
            bean.factoryMethod = "newInstance"
            name = "homer"
            age = 45
            props = [overweight:true, height:"1.8m"]
        }
        children = [bart, lisa]
    }
}

Abstract Beans and Parent Bean Definitions

To create an abstract bean definition define a bean that takes no class:

class HolyGrailQuest {
    def start() { println "lets begin" }
}
class KnightOfTheRoundTable {
    String name
    String leader
    KnightOfTheRoundTable(String n) {
        this.name = n
    }
    HolyGrailQuest quest
    def embarkOnQuest() {
        quest.start()
    }
}
def bb = new grails.spring.BeanBuilder()
bb.beans {
    abstractBean {
        leader = "Lancelot"
    }
    …
}

Here we define an abstract bean that sets that has a leader property with the value of "Lancelot". Now to use the abstract bean set it as the parent of the child bean:

bb.beans {
    …
    quest(HolyGrailQuest)
    knights(KnightOfTheRoundTable, "Camelot") { bean ->
        bean.parent = abstractBean
        quest = quest
    }
}

When using a parent bean you must set the parent property of the bean before setting any other properties on the bean!

If you want an abstract bean that has a class you can do it this way:

def bb = new grails.spring.BeanBuilder()
bb.beans {
    abstractBean(KnightOfTheRoundTable) { bean ->
        bean.'abstract' = true
        leader = "Lancelot"
    }
    quest(HolyGrailQuest)
    knights("Camelot") { bean ->
        bean.parent = abstractBean
        quest = quest
    }
}

In the above example we create an abstract bean of type KnightOfTheRoundTable and use the bean argument to set it to abstract. Later we define a knights bean that has no class, but inherits the class from the parent bean.

Using Spring Namespaces

Since Spring 2.0, users of Spring have been granted easier access to key features via XML namespaces. With BeanBuilder you can use any Spring namespace by first declaring it:

xmlns context:"http://www.springframework.org/schema/context"

And then invoking a method that matches the names of the Spring namespace tag and its associated attributes:

context.'component-scan'( 'base-package' :"my.company.domain" )

You can do some useful things with Spring namespaces, such as looking up a JNDI resource:

xmlns jee:"http://www.springframework.org/schema/jee"
jee.'jndi-lookup'(id:"dataSource", 'jndi-name':"java:comp/env/myDataSource")

The example above will create a Spring bean with the identifier of dataSource by performing a JNDI lookup on the given JNDI name. With Spring namespaces you also get full access to all of the powerful AOP support in Spring from BeanBuilder. For example given the following two classes:

class Person {
 int age;
 String name;
 void birthday() {
      ++age;
 }
}
class BirthdayCardSender {
   List peopleSentCards = []
   void onBirthday(Person person) {
      peopleSentCards << person
   }
}

You can define an AOP aspect that uses a pointcut to detect whenever the birthday() method is called:

xmlns aop:"http://www.springframework.org/schema/aop"
fred(Person) {
    name = "Fred"
    age = 45
}
birthdayCardSenderAspect(BirthdayCardSender)
aop {
    config("proxy-target-class": true) {
        aspect(id: "sendBirthdayCard", ref: "birthdayCardSenderAspect") {
            after method: "onBirthday",
                  pointcut: "execution(void ..Person.birthday()) and this(person)"
        }
    }
}

14.5 Property Placeholder Configuration

Settings defined in either ConfigSlurper scripts or Java properties files can be used as placeholder values for Spring configuration in grails-app/conf/spring/resources.xml. For example given the following entries in grails-app/conf/Config.groovy (or an externalized config):

database.driver="com.mysql.jdbc.Driver"
database.dbname="mysql:mydb"

You can then specify placeholders in resources.xml as follows using the familiar ${..} syntax:

<bean id="dataSource"
      class="org.springframework.jdbc.datasource.DriverManagerDataSource">
    <property name="driverClassName">
        <value>${database.driver}</value>
    </property>
    <property name="url">
        <value>jdbc:${database.dbname}</value>
    </property>
 </bean>

14.6 Property Override Configuration

Essentially you define a beans block with the names of beans and their values:

beans {
    bookService {
        webServiceURL = "http://www.amazon.com"
    }
}

The general format is:

[bean name].[property name] = [value]

The same configuration in a Java properties file would be:

beans.bookService.webServiceURL=http://www.amazon.com