Groovy application utilizing Spring IoC example

With the latest performance enhancements and great dynamic, functional and meta-programming features Groovy becomes a very good choice not only for scripting, but also for big and complex application building. Long term complex application development requires extensive unit testing utilization to allow moving forward without breaking existing features. Groovy plays nicely with powerful Spring framework, which can be used to make application easily extensible and unit testing friendly.

In this article we will use all the latest approaches to inversion of control using powerful Spring Framework, unit testing and build tools utilization to show how to make good architecture of non-trivial Groovy application.

Let’s take a look at the Main class of the application:

Main.groovy

/**
 * Main class of the application that uses Spring framework
 * and JSR 330 annotations for dependency injection.
 */
class Main
{
    /**
     * Launches the application.
     * 
     * @param args command line arguments
     */
    public static void main(final String[] args) {

        <em>// Use Spring annotation-based dependency injection</em>
        def ctx = new AnnotationConfigApplicationContext()
       
        <em>// Parse command line parameters and push</em>
        <em>// all the external configuration to application environment </em>
        def appProps = new MapPropertySource("appProps", [
                greetInfo: new GreetInfo(text: "Hello",
                        name: args.length > 0 ? args[0] : "world")
        ] as Map<String, Object>)

        <em>// Push environment properties to Spring application context </em>
        ctx.getEnvironment().getPropertySources().addFirst(appProps);

        <em>// Point Spring to IoC configuration of the application</em>
        ctx.register(AppConfig.class);
        
        <em>// Wire dependencies </em>
        ctx.refresh();

        <em>// Register hook to close application context on JVM shutdown</em>
        ctx.registerShutdownHook()

        <em>// Launch the application</em>
        def app = ctx.getBean(Application.class)

        app.run()
    }

}Code language: JavaScript (javascript)

Here we configure Spring to use XML-less annotation based dependency injection. The IoC configuration is located in the AppConfig class. After that we instantiate Application bean using Spring and pass control to it by calling run method.

The most interesting place in the code is environment initialization. The Environment is a relatively new feature, that was added to Spring 3.1. Environment allows configuring Spring application context using values from external sources. Here we push command line arguments into Environment so that they will be available in different parts of our application later. We use MapPropertySource for this purpose. It lets pass a dictionary of arbitrary Objects into Environment.

Lets take a look at our AppConfig now:

/**
 * IoC configuration of application.
 */
@Configuration
@ComponentScan(basePackages = "com.sysgears.example",
        scopeResolver = Jsr330ScopeMetadataResolver.class)
class AppConfig {

    private @Inject Environment env
    
    public @Bean GreetInfo createGreetInfo() {
        env.getProperty("greetInfo", GreetInfo.class)
    }
}Code language: CSS (css)

Here we instruct Spring to scan com.sysgears.example to search for components and also to use JSR 330 annotations. JSR 330 is the standard of dependency injection for Java applications.

Notice, how we inject Environment into configuration using JSR330 @Inject annotation and retrieve objects from it. Note also, that Environment could be injected only to Spring @Configuration classes.

The source code for GreetInfo is trivial:

/**
 * Container for the greeting text and person name.
 */
class GreetInfo {

    /** Greeting text */
    def text

    /** Name of the person to greet */
    def name
}Code language: PHP (php)

By default JSR 330 components have prototype scope, which means that new instance of the component will be created each time it will be wired. To mark the component as having prototype-scope one should add @Named-annotation. Below is the example of trivial Greeter prototype-scoped component that constructs greeting string. This component has dependency on the GreeterCounter that holds global counter of the number of times the Greeter was instantiated.

/**
 * Greeter that greets a person with greeting text and output information
 * about instance no of the greeter class.
 */
@Named
class Greeter {

    /** Current greeter instance no */
    private final int instanceNo

    /**
     * Creates an instance of this greater and remembers greeter instance no
     */
    @Inject
    public Greeter(final GreetInstanceCounter greeterCounter) {
        instanceNo = greeterCounter.incrementCounter()
    }

    /**
     * Generates string for greeting {@code subject} with the given {@code text} 
     * 
     * @param text greet text
     * @param name whom to greet
     * 
     * @return greeting string 
     */
    public String greet(String text, String name) {
        "${text}, ${name}! (from greeter ${instanceNo})"
    }
}Code language: PHP (php)

The GreeterCounter should be instantiated one time for a whole application. For this to happen we should mark it with @javax.inject.Singleton annotation.

/**
 * Counter of greeter instances
 */
@Named
@javax.inject.Singleton
class GreeterCounter {
    
    /** Greeter instance current count */
    private int instanceCount = 1

    /**
     * Returns Greeter current instance count and increments counter 
     * 
     * @return Greeter current instance count 
     */
    public int incrementCounter() {
        instanceCount++
    } 
}Code language: PHP (php)

So, @Named and @javax.inject.Singleton are the primary mechanisms to control how many instances of your classes will be created. However these mechanisms only work during wiring phase, but what if you want create class instances at runtime?

JSR 330 provides @javax.inject.Provider – a separate mechanism to create instances at runtime. Here is an example of using this mechanism:

/**
 * Class that uses multiple greeter instances to output several greetings.
 */
@Named
@javax.inject.Singleton
class MultiGreeter {

    /**
     * Object that contains greeting text and name passed through environment
     */
    private @Inject GreetInfo greetInfo

    /**
     * Greeter instance factory 
     */
    private @Inject Provider<Greeter> greeterProvider

    /**
     * Outputs greeting with 2 instances of greeter.
     * 
     * @return greeting text
     */
    public String greet() {
        def greeter1 = greeterProvider.get()
        def greeter2 = greeterProvider.get()
        
        greeter1.greet(greetInfo.text, greetInfo.name) + "\n" +
                greeter2.greet(greetInfo.text, greetInfo.name)
    }
}Code language: PHP (php)

In this code we are using our Greeter to output greeting text two times, using two greeter instances.

The instances of Greeter are created with injected @Inject Provider greeterProvider. Note, that this is enough to write only this line of code to get factory of Greeter’s created for us automatically by IoC container at runtime.

This is pretty much all the logic of our pet application. Now, how to write unit tests for it? Let’s look for the simple case – a unit test for the Greeter.

@ContextConfiguration(classes = AppConfig.class)
class GreeterSpec extends Specification {
    private @Inject Greeter greeter
    
    def 'check greeting'() {
        expect: 'should generate correct greet string'
        greeter.greet('Hello', 'Test') == 'Hello, Test! (from greeter 1)' 
    }
}Code language: PHP (php)

Unit tests are implemented using Spock framework. Greeter is pretty much independent and simple class. That’s why the unit test for this class is simple as well.

In this code we point Spring to the IoC configuration of our application, using @ContextConfiguration(classes = AppConfig.class). Also we let Spring create the instance of Greeter class and wire its dependencies by using just @Inject annotated field.

The code is very neat and straightforward.

Let’s handle more complex problem – a unit test for the class that depends on Environment:

@ContextConfiguration(classes = AppConfig.class, initializers = TestContextInitializer.class)
class MultiGreeterSpec extends Specification {
    private @Inject MultiGreeter multiGreeter

    public static class TestContextInitializer implements
            ApplicationContextInitializer<ConfigurableApplicationContext> {
        @Override
        public void initialize(ConfigurableApplicationContext ctx) {
            def appProps = new MapPropertySource("appProps", [
                    greetInfo: new GreetInfo(text: "TestHello", name: "TestWorld")
            ] as Map<String, Object>)

            ctx.getEnvironment().getPropertySources().addFirst(appProps);
        }
    }

    def 'check greeting generation'() {
        expect: 'should generate correct greeting'

        multiGreeter.greet().trim() == '''
TestHello, TestWorld! (from greeter 1)
TestHello, TestWorld! (from greeter 2)
'''.trim()
    }
}Code language: PHP (php)

Here in @ContextConfiguration we point Spring to context initializer – e.g. the code that will be executed right before wiring. We use context initializer to push test environment properties into application context. This is very similar to the code we had in Main.groovy to pass external properties into Spring context.

At the end of this post I would like to share the Gradle script to build and test this application and create executable JAR that can be launched on any computer that have Java VM installed.

apply plugin: 'maven'
apply plugin: 'groovy'
group = 'com.sysgears.example'
version = '1.0'

defaultTasks 'clean', 'build', 'test', 'uberJar'

def compatibilityVersion = 1.5
def springVersion = '3.2.2.RELEASE'
def mainClassName = 'com.sysgears.example.Main'
sourceCompatibility = compatibilityVersion
targetCompatibility = compatibilityVersion

repositories {
    mavenCentral()
}

dependencies {
     <em>// Spring Framework Dependenices</em>
     compile "org.springframework:spring-beans:${springVersion}"
     compile "org.springframework:spring-context:${springVersion}"
     compile "org.springframework:spring-core:${springVersion}"
     compile "org.springframework:spring-expression:${springVersion}"

     <em>// JSR 330 annotation support</em>
     compile "javax.inject:javax.inject:1"

     <em>// Spring unit testing support</em>
     testCompile "org.springframework:spring-test:${springVersion}"

     <em>// Spock framework for unit testing</em>
     testCompile("org.spockframework:spock-core:0.7-groovy-2.0") {
         exclude module: 'groovy-all'
     }
     testCompile("org.spockframework:spock-spring:0.7-groovy-2.0") {
         exclude module: 'groovy-all'
     }

     <em>// Groovy</em>
     groovy 'org.codehaus.groovy:groovy:2.1.2'
}

<em>// Creates executable standalone JAR file of the application</em>
task uberJar(type: Jar, dependsOn:[':compileJava',':compileGroovy']) {
    from files(sourceSets.main.output.classesDir)
    from files(sourceSets.main.output.resourcesDir)
    from(configurations.runtime.asFileTree.files.collect { zipTree(it) }) {
        exclude "META-INF/*.SF"
        exclude "META-INF/*.DSA"
        exclude "META-INF/*.RSA"
    }
    manifest {
        attributes 'Implementation-Title': 'Groovy app architecture example',
                'Implementation-Version': version,
                'Built-By': System.getProperty('user.name'),
                'Built-Date': new Date(),
                'Built-JDK': System.getProperty('java.version'),
                'Main-Class': mainClassName
    }

}Code language: JavaScript (javascript)

This script is pretty-much self-explaining, however you need to make some magic, in order all things to work as expected. I hope this will be improved in the future versions of Gradle and Spock framework.

The full source code of the project is available at: GitHub repository.

Thanks for reading,

Thank you!