Overcoming Fear

BDD With Spock and Selenium

2012-01-16T22:58:00.000-08:00

BDD With Spock and Selenium

Goal

To develop a web site specification-first using Spock and Selenium WebDriver.

tl;dr

The sample code for this project is available on github and will be a helpful resource for following this article. The interesting technologies showcased include Spock, Selenium WebDriver, Selenium PageObjects, Sauce OnDemand, Gradle and Grails 2.0.

The Project

Suppose our product owner would like to publish a website for teachers to schedule their classes and for students to register for those courses. At the first backlog grooming, the product owner has prioritized the stories that would constitute a minimum viable product.

User Stories

During the team's first sprint planning meeting, we sized the stories, accepted four into the sprint, and have added tasks for each. Our story board for the first sprint contains sticky notes for our user stories, the acceptance criteria and the individual tasks for each story.

As a teacher
I want to sign up
So I can add courses

Acceptance Criteria:

User is greeted with intro screen
User is able to register as a teacher or to login
After registration or login, a teacher sees account info

As a student
I want to sign up
So I can take courses

Acceptance Criteria:

User is able to register or to login as a student
After registration or login, a student sees account info

As a teacher
I want to add courses
So students can register for them

Acceptance Criteria:

A teacher can add a course
Courses occur in a semester
Courses occur in timeslots
Courses can have prerequisites

As a student
I want to register for courses
So I can get credits toward my degree

Acceptance Criteria:

A student can register for a course
A student must take any pre-reqs before registering for a course
A student cannot take 2 courses that occur in the same timeslot

Project Structure

We will create a top-level project course_registry and the two sub-projects web and specifications. We will also create a build.gradle file in the root along with settings.gradle and a build.gradle file in the specifications subproject for running automated acceptance tests (While this is not strictly necessary, it will help to keep our project boundaries clear).

course_registry/build.gradle

allprojects {
  apply plugin: 'eclipse'
  version = '1.0.0-SNAPSHOT'
  group = 'timezra.course_registry'
}

subprojects {
  sourceCompatibility = 1.6
}

course_registry/settings.gradle

include 'web', 'specifications'

course_registry/specifications/build.gradle

apply plugin: 'groovy'

   repositories {
     mavenCentral()
     mavenRepo url: "http://m2repo.spockframework.org/snapshots"
   }
   
   dependencies {
     groovy group: 'org.codehaus.groovy', name: 'groovy', version: '1.8.5'
     testCompile group: 'org.spockframework', name: 'spock-core', version: '0.6-groovy-1.8-SNAPSHOT'
     testCompile group: 'org.seleniumhq.selenium', name: 'selenium-java', version: '2.16.1'
     testCompile group: 'junit', name: 'junit', version: '4.10'
   }
  

We will create a src/test/groovy folder in the specifications project. At this point we can generate Eclipse .project and .classpath files for all the projects from the project root in order to work within an IDE.

course_registry $> gradle eclipseProject
course_registry $> gradle eclipseClasspath

The Teacher Registration Spec

We are now able to write the first specification for our acceptance criteria.

timezra/course_registry/TeacherRegistrationSpec.groovy

package timezra.course_registry

import static java.util.concurrent.TimeUnit.SECONDS
import org.openqa.selenium.WebDriver
import org.openqa.selenium.firefox.FirefoxDriver
import spock.lang.Specification

class TeacherRegistrationSpec extends Specification {

  WebDriver driver

  def setup() {
    driver = new FirefoxDriver()
    driver.manage().timeouts().implicitlyWait 10, SECONDS
  }

  def cleanup() {
    driver.quit()
  }

  def "a user is greeted with an intro screen"() {
    when:
    driver.get "http://localhost:8080/course_registry"

    then:
    driver.title == "Course Registry Home"
  }
}

We can run this spec and watch it fail.

         course_registry $> gradle test --info
         ....
         Test a user is greeted with an intro screen(timezra.course_registry.TeacherRegistrationSpec) FAILED: org.gradle.messaging.remote.internal.PlaceholderException: org.spockframework.runtime.SpockComparisonFailure: Condition not satisfied:
 
         driver.title == "Course Registry Home"
         |      |     |
         |      |     false
         |      |     17 differences (15% similarity)
         |      |     (Pr)o(bl-)e(m) (load)i(ng--) (pag)e
         |      |     (C-)o(urs)e(-) (Reg-)i(stry) (Hom)e
         |      Problem loading page
         org.openqa.selenium.firefox.FirefoxDriver@4532be10
 
         Test timezra.course_registry.TeacherRegistrationSpec FAILED
         Gradle Worker 1 finished executing tests.
         1 test completed, 1 failure
 
         FAILURE: Build failed with an exception.
         ....
        

Satisfying the Spec

Suppose the team decides to use Grails 2.0 to implement the specification. This is not a restriction based on our other technology choices, since gradle is a general purpose build tool and since our specification defines how a user will interact with our web project entirely through a browser. The decision is based on the convenience of the framework, community support, the plug-in ecosystem and the skills of the developers.

First, we need to create an empty web/grails-app directory to indicate to the grails bootstrap that the project will be a grails application.
Then, we will configure our web build for Grails 2.0 in a new web/build.gradle file.

web/build.gradle

buildscript {
     repositories {
       mavenCentral()
       mavenRepo url: 'https://repository.jboss.org/nexus/content/groups/public/'
       mavenRepo url: 'http://repo.grails.org/grails/repo'
     }
   
     dependencies {
       classpath group: 'org.grails', name: 'grails-gradle-plugin', version: '1.1.0'
     }
   }
   
   grailsVersion = '2.0.0'
   apply plugin: 'grails'
   
   dependencies {
     compile group: 'org.grails', name: 'grails-resources', version: grailsVersion
     compile group: 'org.grails', name: 'grails-crud', version: grailsVersion
     compile group: 'org.grails', name: 'grails-hibernate', version: grailsVersion
     compile group: 'org.grails', name: 'grails-plugin-datasource', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-log4j', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-url-mappings', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-gsp', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-filters', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-scaffolding', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-services', version: grailsVersion
     runtime group: 'org.grails', name: 'grails-plugin-servlets', version: grailsVersion
     runtime group: 'com.h2database', name: 'h2', version: '1.3.163'
     runtime group: 'net.sf.ehcache', name: 'ehcache-core', version: '2.4.6'
   }
   
   repositories {
     mavenCentral()
     mavenRepo url: 'https://repository.jboss.org/nexus/content/groups/public/'
     mavenRepo url: 'http://repo.grails.org/grails/repo'
   }
  

From the project root we will initialize the grails project.

         course_registry $> gradle grails-init
         :web:grails-init
   The ResolvedArtifact.getResolvedDependency() method is deprecated and will be removed in the next version of Gradle.
   | Configuring classpath
   | Error log4j:WARN No appenders could be found for logger (org.springframework.core.io.support.PathMatchingResourcePatternResolver).
   | Error log4j:WARN Please initialize the log4j system properly.
   | Error log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
   | Environment set to development.....
   
   BUILD SUCCESSFUL
   
   Total time: 1 mins 36.328 secs
        

We can satisfy the spec simply by modifying application.properties with the expected web application deployment path and project version, the homepage to include the expected title, and messages.properties to contain the expected messages.

web/application.properties

app.grails.version=2.0.0
app.name=course_registry
app.servlet.version=2.5
app.version=1.0.0-SNAPSHOT

web/grails-app/views/index.gsp

<html>
  <head>
    <title><g:message code="home.title" /></title>
    <meta name="layout" content="main" />
    <style type="text/css" media="screen">
      #pageBody {
        margin-left: 280px;
        margin-right: 20px;
       }
    </style>
  </head>
  <body>
    <div id="pageBody" class="dialog">
     <p>
      <g:message code="home.welcome.message" />
     </p>
    </div>
  </body>
</html>

web/grails-app/i18n/messages.properties

....
home.title=Course Registry Home
home.welcome.message=Welcome to the course registry.

We can now add hooks to the specifications project to stop and start the web application before and after running the specifications, respectively.

specifications/build.gradle

....
test.dependsOn ':web:webStart'

gradle.taskGraph.afterTask { Task task, TaskState state ->
  if(':specifications:test' == task.path) {
    project(':web').tasks.getByPath('webStop').execute()
  }
}

These hooks depend on a specific interface in the web project, i.e., the existence of the tasks webStart and webStop. We can deploy the Grails 2.0 artifact to an embedded Jetty server through gradle to satisfy this interface.

web/build.gradle

....
    apply plugin: 'jetty'
    
    def stopPort = 8001
    def safeWord = 'banana'
    
    task webStart(dependsOn: 'grails-war') << {
      def jettyRunWar = tasks.getByPath('jettyRunWar')
      jettyRunWar.webApp = new File(projectDir, "target/course_registry-${version}.war")
      jettyRunWar.contextPath = 'course_registry'
      jettyRunWar.daemon = true
      jettyRunWar.stopPort = stopPort
      jettyRunWar.stopKey = safeWord
      jettyRunWar.execute()
    }
    
    task webStop << {
      def jettyStop = tasks.getByPath('jettyStop')
      jettyStop.stopPort = stopPort
      jettyStop.stopKey = safeWord
      jettyStop.execute()
    }
   ....
  

The first specification should now be satisfied.

course_registry $> gradle test --info
....
Started Jetty Server
Gradle Worker 1 executing tests.
Test a user is greeted with an intro screen(timezra.course_registry.TeacherRegistrationSpec) PASSED
Gradle Worker 1 finished executing tests.
....

NB: The Jetty plugin must be applied before the grails plugin, or else you will see an error similar to the following:

   FAILURE: Build failed with an exception.
   
   * Where:
   Build file '/path/to/course_registry/web/build.gradle' line: 38
   
   * What went wrong:
   A problem occurred evaluating project ':web'.
   Cause: Cannot add task ':web:clean' as a task with that name already exists.
   
   * Try:
   Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.
   
   BUILD FAILED
   
   Total time: 7.624 secs
        

Adding another test for our second acceptance criterion should be straightforward now that our infrastructure is in place.

timezra/course_registry/TeacherRegistrationSpec.groovy

  ....
    def "a user can register as a teacher"() {
      when:
      driver.get "http://localhost:8080/course_registry"
      WebElement teacherLink = driver.findElement(By.id('teacher_link'))
      teacherLink.click()
      WebElement name = driver.findElement(By.id('name'))
      type name, 'John Doe'
      WebElement email = driver.findElement(By.id('email'))
      type email, "${UUID.randomUUID()}@rutgers.edu"
      WebElement password = driver.findElement(By.id('password'))
      type password, '1234567'
      WebElement create = driver.findElement(By.id('create'))
      create.click()
  
      then:
      driver.title == 'Show Teacher'
      driver.findElement(By.className('message')).text ==~ /Teacher \d+ created/
    }
  
    def type(field, text) {
      field.clear()
      field.sendKeys text
    }

We can satisfy this specification by generating a Grails Teacher domain object with fields for the name, email and password, along with a Grails controller that uses dynamic scaffolding to generate the view and actions available, and by adding a link to the scaffolded Create Teacher page on our web/grails-app/views/index.gsp. Since the point of this tutorial is not to cover basic Grails development, we do not need to go into those specifics here, but sample code can be found on the project site or in any Grails tutorial for further reference.

Page Objects

Before we get too far with automating our acceptance criteria, we should begin to look towards a more abstract representation of the testable components of our application. From the second acceptance test above, we can already see patterns emerging. For example, when we navigate to a particular page, it would be convenient to identify that we are on the correct page, perhaps by its title. It would also be convenient to represent each view in the application as its own object, and each view could encapsulate its specific WebElements. Finally, there is a small set of actions available for any WebElement on a page, and it would be helpful to build these actions into a testing DSL. Fortunately, by combining the Page Object pattern and Groovy's dynamic language features, we can achieve all these goals with a minimal amount of code.

As we are satisfying the specifications for all the acceptance criteria, a base Page Object emerges.

specifications/src/test/groovy/timezra/course_registry/pages/CourseRegistryPage.groovy

   package timezra.course_registry.pages
   
   import static org.apache.commons.lang.StringUtils.splitByCharacterTypeCamelCase
   
   import org.openqa.selenium.WebDriver
   import org.openqa.selenium.WebElement
   import org.openqa.selenium.support.FindBy
   import org.openqa.selenium.support.PageFactory
   import org.openqa.selenium.support.ui.Select
   
   abstract class CourseRegistryPage {
   
     WebDriver driver
   
     @FindBy(className = "message")
     WebElement message
   
     static <T extends CourseRegistryPage> T goTo(String address, WebDriver driver, Class<T> page) {
       driver.get address
       PageFactory.initElements driver, page
     }
   
     CourseRegistryPage(WebDriver driver) {
       this.driver = driver
       String title = splitByCharacterTypeCamelCase(getClass().simpleName).join ' '
       if(!title.equals(driver.title)) {
         throw new IllegalStateException("Should be on page '${title}' but was on page '${driver.title}' instead")
       }
     }
   
     def methodMissing(String name, args) {
       def m
       if((m = name =~ /click_(\w+)/)) {
         def webElement = this."${m[0][1]}"
         webElement.click()
         PageFactory.initElements driver, args[0]
       }
       else if((m = name =~ /type_(\w+)/)) {
         def webElement = this."${m[0][1]}"
         webElement.clear()
         webElement.sendKeys args[0]
       }
       else if((m = name =~ /choose_(\w+)/)) {
         def webElement = this."${m[0][1]}"
         def select = new Select(webElement)
         select.selectByVisibleText args[0]
       }
       else {
         throw new MissingMethodException(name, getClass(), args)
       }
     }
   }
  

NB: The constructor verifies that the page is correct by comparing the class name to the page title; in addition, the static goTo method demonstrates how to use the PageFactory for initializing a Page Object; the methodMissing declaration also showcases Groovy's ability to call dynamic methods based on the combination of the click, type and choose actions with individual WebElement names. Such phrases become first-class elements of the testing DSL.

We can see the use of WebElement injection and dynamic methods in action with a CreateUser page that serves as the base for the CreateTeacher and CreateStudent pages.

specifications/src/test/groovy/timezra/course_registry/pages/CreateUser.groovy

package timezra.course_registry.pages

import groovy.transform.InheritConstructors

import org.openqa.selenium.WebDriver
import org.openqa.selenium.WebElement

@InheritConstructors
abstract class CreateUser extends CourseRegistryPage {
  WebElement name
  WebElement email
  WebElement password
  WebElement create

  CreateUser(WebDriver driver) {
    super(driver)
  }

  protected <T> T register(name, email, password, Class<T> nextPage) {
    type_name name
    type_email email
    type_password password
    click_create nextPage
  }
}

Other Browsers

So far, we have done all our testing with a single WebDriver, i.e., the FirefoxDriver. For simple testing, a single driver works fine, but if we wish to ensure that our website works in multiple browsers, we will need to configure our tests to use multiple WebDrivers. Fortunately, since we are using Gradle to manage our dependencies, the InternetExplorerDriver and ChromeDriver should be available to us automatically, along with the AndroidDriver and IPhoneDriver for testing our application on mobile devices. In addition, an OperaDriver is also available.

NB: Some of these drivers require that additional platform-specific software be installed, so please read the project pages for documentation on additional requirements.

Configuring our specifications to use multiple WebDrivers should just be a matter of parameterizing each Spock feature.

NB: Unlike JUnit tests which are parameterized by fixture, Spock specifications are parameterized per feature.

We will modify our TeacherRegistrationSpec to use the Spock where: block for parameterization, we will configure multiple WebDrivers, and we will share the instance driver field among the parameterized features.

timezra/course_registry/TeacherRegistrationSpec.groovy

   class TeacherRegistrationSpec extends Specification {
   
     @Shared
     WebDriver driver
   
     def setup() {
       driver.manage().timeouts().implicitlyWait 10, SECONDS
     }
   
     def cleanup() {
       driver.quit()
     }
   
     def "a user is greeted with an intro screen"() {
       when:
       ....
   
       then:
       ....
   
       where:
       browser << browsers()
     }
   
     def "a user can register as a teacher"() {
       when:
       ....
   
       then:
       ....
   
       where:
       browser << browsers()
     }
     
     ....
   
     protected def browsers() {
       System.setProperty("webdriver.chrome.driver", "/path/to/chromedriver")
       def drivers = [
         new HtmlUnitDriver(),
         new FirefoxDriver(),
         new ChromeDriver()
       ]
       new Browsers(spec: this, delegate: drivers.iterator())
     }
   
     private static final class Browsers {
       @Delegate Iterator<WebDriver> delegate
       TeacherRegistrationSpec spec
   
       @Override WebDriver next() {
         spec.driver = delegate.next()
       }
     }
   }
  

Testing In The Cloud

Now that our specifications are running through multiple browsers on a single machine, we can move a step further towards testing multiple browser versions on multiple OSes with cloud-based services such as Sauce Labs. For such a powerful service, the configuration changes to our existing application are surprisingly simple. We will modify our TeacherRegistrationSpec to use a RemoteWebDriver for the specific browser and OS combination we would like to test along with our Sauce Labs username and API key as described in the Sauce OnDemand documentation. We will also need to add a Gradle plugin to start SauceConnect from the build, just as we start our web application before running acceptance tests. Finally, we should ensure that all references to localhost in our application are changed to the IP address of the machine where we will be running our tests; otherwise, we might see the SauceConnect proxy freeze (you might have a different experience, and this freezing might just be attributable to the Gremlins in my machine).

timezra/course_registry/TeacherRegistrationSpec.groovy

   class TeacherRegistrationSpec extends Specification {
     ....
     def "a user is greeted with an intro screen"() {
       when:
       driver.get "http://<your.ip.address>:8080/course_registry"
       ....
     }
   
     def "a user can register as a teacher"() {
       when:
       driver.get "http://<your.ip.address>:8080/course_registry/"
       ....
     }
     ....
     protected def browsers() {
       def capabilities = DesiredCapabilities.internetExplorer()
       capabilities.setCapability("version", "7")
       capabilities.setCapability("platform", Platform.XP)
       capabilities.setCapability("name", "Testing Teacher Registration in Sauce")
   
       def sauceDriver = new RemoteWebDriver(
           new URL(
           "http://<username>:<apiKey>@ondemand.saucelabs.com:80/wd/hub"),
           capabilities)
       def drivers = [sauceDriver]
       new Browsers(spec: this, delegate: drivers.iterator())
     }
     ....
   }
  

course_registry/specifications/build.gradle

   import java.util.concurrent.Executors
   import java.util.concurrent.ExecutorService
   ....
   repositories {
     ....
     mavenRepo url: "https://repository-saucelabs.forge.cloudbees.com/release"
   }
   
   dependencies {
     ....
     runtime group: 'com.saucelabs', name: 'sauce-connect', version: '3.0.18'
   }
   
   apply plugin: SauceConnect
   
   sauceConfig {
     username = '<username>'
     apiKey = '<apiKey>'
   }
   
   test.dependsOn ':web:webStart', 'sauceConnect'
   
   gradle.taskGraph.afterTask { Task task, TaskState state ->
     if(':specifications:test'.equals(task.path)) {
       tasks.getByPath('sauceDisconnect').execute()
       project(':web').tasks.getByPath('webStop').execute()
     }
   }
   
   class SauceConnect implements Plugin<Project> {
     
     ExecutorService executor = Executors.newFixedThreadPool(2)
     
     def void apply(Project project) {
       project.extensions.sauceConfig = new SauceConnectExtension()
       
       project.task('sauceConnect') << {
         
         def output = new PipedOutputStream()
         def input = new PipedInputStream(output)
         def reader = new BufferedReader(new InputStreamReader(input))
         
         executor.execute {
           println "Connecting to Sauce Labs as ${project.sauceConfig.username} with key ${project.sauceConfig.apiKey}...."
           try {
             project.javaexec {
               main = 'com.saucelabs.sauceconnect.SauceConnect'
               classpath = project.sourceSets.main.runtimeClasspath
               args = [project.sauceConfig.username, project.sauceConfig.apiKey]
               standardOutput = output
             } 
           } catch(Exception ignored) {
             // Executor has been shutdown
           }
         }
         boolean okToStart = false
         executor.execute {
           def nextLine
           try {
             while((nextLine = reader.readLine()) != null) {
               println nextLine
               if(!okToStart) {
                 if(nextLine =~ /Please wait for "You may start your tests" to start your tests/) {
                   continue
                 }
                 else if(nextLine =~ /You may start your tests/) {
                   okToStart = true
                 }
               }
             }
           } catch(Exception ignored) {
             // Executor has been shutdown
           }
         }
         while(!okToStart) {
           Thread.sleep 250
         }
       }
       
       project.task('sauceDisconnect') << {
         println "Disconnecting from Sauce Labs...."
         executor.shutdownNow()
       }
     }
   }
   
   class SauceConnectExtension {
     String username
     String apiKey
   }
  

Conclusion

This post took us through the definition of user stories for a small website, the setup of a Gradle project for automating the website build and the run of its corresponding acceptance tests, the creation of our first WebDriver-based Spock specification for our acceptance criteria and the fulfillment of that spec with a Grails 2.0 application, the use of Selenium PageObjects to create abstract representations of our web pages before those web pages are even written, all the way to the creation of a Gradle plugin for running our acceptance tests on various browser/OS combinations in Sauce Labs. Each of those items in itself is worthy of a tutorial series. The combination of all these elements demonstrates with a remarkably small amount of configuration and code the type of robust and scalable ATDD infrastructure that is possible and should be at the core of any enterprise web application.

Trampoline and Memoize

2011-11-10T22:59:00.000-08:00

Trampoline and Memoize

Goal

Groovy 1.8 introduces two new closure functions. Memoization is the automatic caching of closure results. Trampolining permits a form of declarative tail-call optimization. This article introduces the two concepts and demonstrates how to combine them in order to create cached, tail-recursive closures.

tl;dr

The example code from this article is available on github.

Simple Memoization

Creating a closure that caches the result of some calculation is as easy as appending .memoize() or one of the alternate memoize...(...) methods that allows more fine-grained control over cache sizes to a closure declaration. One benefit of memoization includes the caching of results of long-running calculations that have no side effects. Memory leaks are a potential pitfall, which is why a maximum cache size should generally be prefered.
The specification below contains a closure with a side-effect. This side effect happens just once, despite the closure being invoked twice.

SimpleMemoizationSpec.groovy

package timezra.groovy.trampoline_memoize

class SimpleMemoizationSpec extends spock.lang.Specification {

  int count

  def identity = {
    count++
    it
  }.memoize()

  def "each call should be cached"() {
    when:
    def first = identity 0
    def second = identity 0

    then:
    count == 1
    first == second
    second == 0
  }
}

Recursive Memoization

Suppose we want to memoize the results of a recursive closure call. For example, we can unroll the call tree of this naive implementation of the fibonacci function.

  def fib = { n ->
    if(n == 0) 0
    else if(n == 1) 1
    else fib(n-1) + fib(n-2)
  }

The call trace for the fourth fibonacci number looks like this.

                       ___________fib 4___________
                      /                           \
               fib 3 + fib 2                 fib 2 + fib 1
             /               \                 /
      fib 2 + fib 1     fib 2 + fib 1     fib 1 + fib 0
       /
fib 1 + fib 0

NB: The closure here is entered nine times but we can see that it only needs to be entered 5 times because 4 calls are repeated. If we cache the results of the fibonacci calls, the complexity of even a naive implementation such as this will increase linearly, rather than exponentially.

Unfortunately, because, in Groovy 1.8, a closure cannot invoke another closure directly, memoizing this closure is not entirely straightforward. The example directly below does not work.

RecursiveMemoizationSpec.groovy

package timezra.groovy.trampoline_memoize

class RecursiveMemoizationSpec extends spock.lang.Specification {

  int count

  def fib = { n ->
    count++
    if(n == 0) 0
    else if(n == 1) 1
    else fib(n-1) + fib(n-2)
  }.memoize()

  def "calls should be cached"() {
    when:
    def actual = fib 10

    then:
    actual == 55
    count == 11
  }
}

The stack trace when a closure calls itself.

groovy.lang.MissingMethodException: No signature of method: org.codehaus.groovy.runtime.memoize.Memoize$MemoizeFunction.doCall() is applicable for argument types: (java.lang.Integer) values: [9]
Possible solutions: call(), call([Ljava.lang.Object;), call(java.lang.Object), call([Ljava.lang.Object;), findAll(), equals(java.lang.Object)
  at timezra.groovy.trampoline_memoize.RecursiveMemoizationSpec.$spock_initializeFields_closure1(RecursiveMemoizationSpec.groovy:11)
  at groovy.lang.Closure.call(Closure.java:410)
  at groovy.lang.Closure.call(Closure.java:423)
  at timezra.groovy.trampoline_memoize.RecursiveMemoizationSpec.calls should be cached(RecursiveMemoizationSpec.groovy:16)

Since methods can invoke memoized closures, the solution is to invoke the call method on the closure.

RecursiveMemoizationSpec.groovy

class RecursiveMemoizationSpec extends spock.lang.Specification {
....
  def fib = { n ->
    count++
    if(n == 0) 0
    else if(n == 1) 1
    else fib.call(n-1) + fib.call(n-2)
  }.memoize()
....
}

NB: The un-memoized version enters the closure 177 times, but the memoized version enters just 11.

Trampoline

Declarative tail-call optimization is as simple as adding .trampoline() to a closure declaration and ensuring that recursive calls to the closure invoke the trampoline method on the closure instead of the closure itself. Some problems are more clearly solved with recursive solutions, but without automatic tail-call optimization in the JVM, recursion can quickly lead to an explosion in the size of the call stack. Trampolining is one work-around for this design tradeoff (or defect).
A tail-recursive fibonacci closure:

  def fib = { n, a = 0, b = 1 ->
    if(n == 0) a
    else fib n - 1, b, a + b
  }

By tracing the call stack, we can see its linear growth without memoization.

fib 4
  |
fib 3, 1, 1
  |
fib 2, 1, 2
  |
fib 1, 2, 3
  |
fib 0, 3, 5

In order to avoid a java.lang.StackOverflowError for sufficiently large inputs, the tail-recursive closure must be explicitly trampolined.
TrampolineSpec.groovy

package timezra.groovy.trampoline_memoize

class TrampolineSpec extends spock.lang.Specification {

  int count

  def fib = { n, a = 0, b = 1 ->
    count++
    if(n == 0) a
    else fib.trampoline n - 1, b, a + b
  }.trampoline()

  def "tail calls chould be optimized"() {
    when:
    def actual = fib 1000

    then:
    actual == 1556111435
    count == 1001
  }
}

In this example, the trampolined closure is called 1001 times. If a method in Java were to call itself 1001 times, the stack would be overwhelmed. By trampolining, Groovy turns this recursion into iteration.

Memoizing a Trampolined Closure

Suppose we want to cache the results of a computationally expensive tail-recursive closure with no side effects. A trampolined closure that calls itself can easily be memoized in a separate closure declaration.

OneTimeTrampolineMemoizationSpec.groovy

package timezra.groovy.trampoline_memoize

class OneTimeTrampolineMemoizationSpec extends spock.lang.Specification {

  int count

  def fib_aux = { n, a = 0, b = 1 ->
    count++
    if(n == 0) a
    else fib_aux.trampoline n - 1, b, a + b
  }.trampoline()

  def fib = fib_aux.memoize()

  def "top-level trampolined calls should be cached"() {
    when:
    def first = fib 1000
    def second = fib 1000

    then:
    count == 1001
    first == second
    second == 1556111435
  }
}

NB: This solution caches the top-level trampolined closure, not the results of the intermediate calls.

Trampolining a Memoized Closure

Suppose we want to cache the intermediate results of a trampolined function call. For example, in our trace above, suppose we want to cache the results of fib 4 and fib 3, 1, 1 and fib 2, 1, 2 and fib 1, 2, 3 and fib 0, 3, 5.
Again, this situation is not straightforward because no closure can call a memoized closure directly, so in this case, the trampolined closure cannot call a memoized version of itself directly. Again, we can use the call function on the memoized closure.

FullTrampolineMemoizationSpec.groovy

package timezra.groovy.trampoline_memoize

class FullTrampolineMemoizationSpec extends spock.lang.Specification {

  int count

  def fib_aux = { n, a, b ->
    count++
    if(n == 0) a
    else fib.trampoline n - 1, b, a + b
  }.memoize()

  def fib = { n, a = 0, b = 1 ->
    fib_aux.call n, a, b
  }.trampoline()

  def "all trampolined calls should be cached"() {
    when:
    def first = fib 1000
    def second = fib 500, 315178285, -1898383934

    then:
    count == 1001
    first == second
    second == 1556111435
  }
}

Conclusion

Trampolining and memoization are two powerful new features in Groovy 1.8, but the combination of the two is not always straightforward. This tutorial has presented strategies for combining the two and for working around some of the limitations of their combination.

Tycho Archetype

2011-10-19T18:35:00.000-07:00

Goal

The purpose of this blog post is to demonstrate how to generalize a Maven project that suits a specific need into a re-usable archetype, how to publish this archetype to a Maven repository and how to use it as the starting point for similar projects.

tl;dr

The artifact that is the end result of this tutorial can be used for creating a boilerplate Tycho plug-in project hierarchy with minimal configuration. This generated project will contain a simple Eclipse UI plug-in, an integration-test fragment, a feature that contains the binary plug-in, a feature that contains the source of the plug-in and its test fragment, and an update site for publishing both features.

Generate Archetype From Project

Since we are moving from the specific to the general, we begin by cloning the save-actions-extensions project from github.

git clone git://github.com/timezra/save-actions-extensions.git

Since we need only a few of the components from the save-actions-extensions project, we can prune out the extra. We must also rename the features, plugins and update-site directories to match the artifactIds in their respective poms along with the module declarations in the root pom. This directory structure follows the Eclipse convention, but archetype generation will be easier if we make sure that the artifactIds and directory names match. We will also rename the individual plugins and features along with their artifactIds so that there is a consistent name prefix for all projects. Again, this convention will help when generating the archetype.

The pruned project

We are now ready to generate, install and test the archetype from maven.

NB: even when specifying filtered extensions, not all files (here README, MANIFEST.MF and site.xsl) are turned into velocity templates, and the hard-coded artifactId references in some files are not all replaced with parameters.

  mvn archetype:create-from-project -Darchetype.filteredExtensions=java,html,xsl,properties,xml,MF
  cd target/generated-sources/archetype/
  find ./src -type f $ -name "*.MF" -o -name "*.xsl" $ -print0 |xargs -0 perl -pi -e 's/\$/\${symbol_dollar}/g'
  find ./src -type f $ -name "*.MF" -o -name "*.xsl" $ -exec perl -pi -e "print qq(#set( \\\$symbol_pound = '#' )\n#set( \\\$symbol_dollar = '\\$' )\n#set( \\\$symbol_escape = '\\\' )\n) if $. == 1" {} \;
  find ./src -type f -print0 |xargs -0 perl -pi -e 's/timezra\.eclipse\.save_actions_extensions/\$\{rootArtifactId}/g'
  find ./src -type f -print0 |xargs -0 perl -pi -e 's/\$\{groupId}\.save_actions_extensions/\$\{rootArtifactId}/g'
  find ./src -name archetype-metadata.xml -exec perl -pi -e 'undef $/; $_=<>; s/\s*\n\s*//g; s~README~README~g;s~META-INF~META-INF~g;s~web\*\*/\*\.xsl~web**/*.xslweb~g' {} \;
  mvn clean install
  cd /path/to/tmp/archetype
  mvn archetype:generate -DarchetypeCatalog=local
    # Choose the new archetype (here local -> timezra.eclipse:timezra.eclipse.save_actions_extensions-archetype)
    # Define a groupId (e.g., my.company)
    # Define an artifactId (e.g., my.company.do_something)
    # Define a version (e.g., 1.0.0-SNAPSHOT)
    # Define a package (e.g., my.company.do_something.plugin)
  cd my.company.do_something
  mvn verify

After running this sequence of commands, we should see the eclipse workbench open and successfully run the canary integration test for our test project.

The generated project structure

Dynamic Directories

On closer comparison of the directory tree from the original project and the generated project, you might wonder how Maven knows to name folders based on the artifactIds.
If we look at the generated archetype, we will see a parameterized directory structure.

Parameterized directories are in red

You might also notice that the Activator.java and ActivatorTest.java are contained in the root of their src/main/java and src/test/java folders, respectively, in the archetype resources; however, in the generated project, the files are in the proper subdirectories with corresponding package declarations. In the generated archetype-metadata.xml, the contents of these source directories are filtered and packaged.

src/main/resources/META-INF/maven/archetype-metadata.xml

<archetype-descriptor ....>
  ....
  <modules>
    <module id="${rootArtifactId}.plugins" ....>
      <modules>
        <module id="${rootArtifactId}.plugin" ....>
          <fileSets>
            <fileSet filtered="true" packaged="true" encoding="UTF-8">
              <directory>src/main/java</directory>
              <includes>
                <include>**/*.java</include>
              </includes>
            </fileSet>
            ....
          </fileSets>
        </module>
        <module id="${rootArtifactId}.plugin.tests" ....>
          <fileSets>
            <fileSet filtered="true" packaged="true" encoding="UTF-8">
              <directory>src/test/java</directory>
              <includes>
                <include>**/*.java</include>
              </includes>
            </fileSet>
            ....
          </fileSets>
        </module>
      </modules>
    </module>
    ....
  </modules>
</archetype-descriptor>

Testing

After customizing our resources and adding any additional required properties, we can integration-test the archetype using a golden template project contained in the src/test/projects/basic/reference directory. For this example, if the generated my.company.do_something project above exactly meets our needs, then we can simply copy the entire contents of this directory to the src/test/projects/basic/reference folder and update the archetype.properties to match the properties we used for project generation.

src/test/resources/projects/basic/archetype.properties

groupId=my.company
artifactId=my.company.do_something
version=1.0.0-SNAPSHOT
package=my.company.do_something.plugin

During the integration-test phase, Maven will generate a sample project from the archetype with these properties and will compare the results with the golden template.

mvn verify

NB: use of this type of golden template can be very brittle, and any changes made to files in the src/main/resources/archetype-resources directory must be reflected by equivalent changes in the src/test/resources/projects/basic/reference directory.

Publish to a Maven Repository

Now that our Maven archetype is tested and ready for publication, we can publish it, either to an internal repository, to the sonatype repository, which will synch our artifact with Maven central, or to a private repository, which in our case can simply be github pages.
We want to partition our repository into snapshots and releases, and we will need archetype catalogs in a subfolder of each.
We can deploy our archetype to a folder that contains the gh-pages branch of a github project called maven, which will contain all our published maven artifacts.

mvn -DaltDeploymentRepository=snapshot-repo::default::file:/path/to/git_maven_repository/snapshots clean deploy

Since we have installed the archetype, we already have a ~/.m2/archetype-catalog.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0 http://maven.apache.org/xsd/archetype-catalog-1.0.0.xsd"
  xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <archetypes>
    <archetype>
      <groupId>timezra.eclipse</groupId>
      <artifactId>timezra.eclipse.save_actions_extensions-archetype</artifactId>
      <version>1.0.0-SNAPSHOT</version>
      <description>Parent project for the timezra.eclipse.save_actions_extensions project set</description>
    </archetype>
  </archetypes>
</archetype-catalog>

The Maven repository

Use the Archetype From the Repository

After our artifacts have been deployed to a Maven repository, we can generate a project from the deployed archetype in a way similar to how we generated the project from the archetype installed locally above.

Generating from an artifact in a gh-pages repository

mvn archetype:generate -DarchetypeCatalog=http://your_github_username.github.com/maven/snapshots/archetypes

Conclusion

This tutorial is a continuation of a previous post, in which we created a set of Tycho-enabled Eclipse projects. The archetype we created from this set of projects abstracts the boilerplate and conventions into a re-usable component that will make setting up similar projects even faster in the future.
The end result of this effort is the tycho_new_plugin_project.

Eclipse Plug-ins: Program to Publish

2011-10-12T00:18:00.000-07:00

Goal

The purpose of this blog entry is to demonstrate one workflow for taking an idea for an Eclipse plug-in from concept to product downloadable from the Eclipse marketplace.

tl;dr

If you want to look right away at working code for a simple Eclipse plug-in, feature, update site and their Tycho configurations, a sample project based on this tutorial is available. The plug-in can also be installed in Eclipse through the Marketplace (search for "save actions") or directly from an update site. In addition, the conventions for project setup contained in this tutorial have been extracted into a Maven archetype. Since this blog entry does not provide an in-depth introduction to the nuances of configuring and writing Eclipse plug-ins, having the project source as a reference, either locally or in a web browser, will be helpful for following the examples.

The Idea

Suppose we are starting a new project on an existing codebase and, as part of our Working Agreement, the team has decided to automate certain coding standards with Eclipse Java editor save actions. It would be convenient to bring all the existing code up to our standards before development even begins. Currently, formatting and import organization can be performed in bulk from the source submenu in the workbench. Eclipse users can also apply clean-up conventions from this submenu. Unfortunately, even though the clean-up and save participants have similar configurations, there is a disconnect between the two.
Exposing save actions for the bulk processing of Java/Groovy files through this source submenu is a simple enough feature to add to Eclipse and should provide the opportunity to experience one full cycle of Eclipse plug-in development, from the creation of a simple plug-in and its integration tests, to the addition of a feature to contain the plug-in, to the packaging of an update site, to the distribution of the product through the Eclipse Marketplace.

The Plug-in

We will begin by creating a new plug-in project named timezra.eclipse.apply_save_actions in our Eclipse workspace. Since we will eventually generate a Tycho configuration in order to automate the compilation, testing and packaging of our product, we will modify a few of the default settings for the plug-in. Our plug-in and fragment projects will be contained in a plugins subdirectory, here /path/to/workspace/plugins/timezra.eclipse.apply_save_actions. Our source folder will be src/main/java and output folder will be target/classes to follow the Maven convention.

We can either use the New Plug-in Project Wizard Hello, World Command Template or we can contribute a command to a menu with manual configuration. There are already quite a few resources for contributing commands through an extension point, so you can get more insight into specific configuration settings there.
For this example, the configuration is boilerplate. The internals of the ApplySaveActions command handler are somewhat interesting. There may be a more direct way to invoke the save participant, but this method works on both un-opened files and source buffers modified in memory for Java and Groovy, so in the interest of DTSTTCPW, we can use this simple implementation until it is no longer sufficient.

plugins/timezra.eclipse.apply_save_actions/src/main/java/timezra/eclipse/apply_save_actions/handlers/ApplySaveActions.java

package timezra.eclipse.apply_save_actions.handlers;

import static java.util.Arrays.asList;
import java.lang.reflect.InvocationTargetException;
import java.util.ArrayList;
import java.util.Collection;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IWorkspace;
import org.eclipse.core.resources.ResourcesPlugin;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdapterManager;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.OperationCanceledException;
import org.eclipse.core.runtime.Platform;
import org.eclipse.jdt.core.ICompilationUnit;
import org.eclipse.jdt.core.IJavaElement;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jdt.core.IPackageFragment;
import org.eclipse.jdt.core.IPackageFragmentRoot;
import org.eclipse.jdt.core.JavaModelException;
import org.eclipse.jface.operation.IRunnableWithProgress;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.ui.IWorkbench;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.actions.WorkspaceModifyOperation;
import org.eclipse.ui.handlers.HandlerUtil;
import org.eclipse.ui.part.FileEditorInput;
import org.eclipse.ui.texteditor.IDocumentProvider;

public class ApplySaveActions extends AbstractHandler {

  private final IAdapterManager adapterManager;
  private final IWorkspace workspace;
  private final IWorkbench workbench;

  public ApplySaveActions() {
    this(Platform.getAdapterManager(), ResourcesPlugin.getWorkspace(), PlatformUI.getWorkbench());
  }

  ApplySaveActions(final IAdapterManager adapterManager, final IWorkspace workspace, final IWorkbench workbench) {
    this.adapterManager = adapterManager;
    this.workspace = workspace;
    this.workbench = workbench;
  }

  @Override
  public Object execute(final ExecutionEvent event) throws ExecutionException {
    final ISelection currentSelection = HandlerUtil.getCurrentSelectionChecked(event);
    if (currentSelection instanceof IStructuredSelection) {
      final IStructuredSelection selections = (IStructuredSelection) currentSelection;
      try {
        applyTo(selections);
      } catch (final JavaModelException e) {
        throw new ExecutionException(Messages.APPLY_SAVE_ACTIONS_UNEXPECTED_ERROR, e);
      } catch (final InvocationTargetException e) {
        throw new ExecutionException(Messages.APPLY_SAVE_ACTIONS_UNEXPECTED_ERROR, e.getTargetException());
      }
    }
    return null;
  }

  private void applyTo(final IStructuredSelection selections) throws JavaModelException, InvocationTargetException {
    for (final Object o : selections.toList()) {
      final IJavaProject javaProject = getAdapter(o, IJavaProject.class);
      if (javaProject != null) {
        applyTo(javaProject.getPackageFragments());
        continue;
      }
      final IPackageFragmentRoot packageFragmentRoot = getAdapter(o, IPackageFragmentRoot.class);
      if (packageFragmentRoot != null) {
        applyTo(packageFragmentRoot);
        continue;
      }
      final IPackageFragment packageFragment = getAdapter(o, IPackageFragment.class);
      if (packageFragment != null) {
        applyTo(packageFragment);
        continue;
      }
      final ICompilationUnit compilationUnit = getAdapter(o, ICompilationUnit.class);
      if (compilationUnit != null) {
        applyTo(compilationUnit);
        continue;
      }
    }
  }

  private void applyTo(final IPackageFragmentRoot packageFragmentRoot) throws JavaModelException,
      InvocationTargetException {
    final IJavaElement[] children = packageFragmentRoot.getChildren();
    final IPackageFragment[] fragments = new IPackageFragment[children.length];
    System.arraycopy(children, 0, fragments, 0, children.length);
    applyTo(fragments);
  }

  private void applyTo(final IPackageFragment... packageFragments) throws JavaModelException,
      InvocationTargetException {
    final Collection<ICompilationUnit> compilationUnits = new ArrayList<ICompilationUnit>();
    for (final IPackageFragment f : packageFragments) {
      compilationUnits.addAll(asList(f.getCompilationUnits()));
    }
    applyTo(compilationUnits.toArray(new ICompilationUnit[compilationUnits.size()]));
  }

  private void applyTo(final ICompilationUnit... compilationUnits) throws InvocationTargetException {
    final IRunnableWithProgress delegate = new ApplySaveActionsOperation(compilationUnits);
    try {
      workbench.getProgressService().run(false, true, delegate);
    } catch (final InterruptedException e) {
      // cancellation is fine
    }
  }

  @SuppressWarnings("restriction")
  private IDocumentProvider createDocumentProvider() {
    return new org.eclipse.jdt.internal.ui.javaeditor.CompilationUnitDocumentProvider();
  }

  @SuppressWarnings("unchecked")
  private <T> T getAdapter(final Object o, final Class<T> c) {
    return (T) adapterManager.getAdapter(o, c);
  }

  private final class ApplySaveActionsOperation extends WorkspaceModifyOperation {
    private final ICompilationUnit[] compilationUnits;

    ApplySaveActionsOperation(final ICompilationUnit... compilationUnits) {
      this.compilationUnits = compilationUnits;
    }

    @Override
    public void execute(final IProgressMonitor pm) throws CoreException {
      pm.beginTask(Messages.APPLY_SAVE_ACTIONS_BEGIN_TASK, compilationUnits.length);
      try {
        for (final ICompilationUnit unit : compilationUnits) {
          applyTo(workspace.getRoot().getFile(unit.getPath()), pm);
        }
      } finally {
        pm.done();
      }
    }

    void applyTo(final IFile f, final IProgressMonitor pm) throws CoreException {
      report(f.getName(), pm);
      final IDocumentProvider provider = createDocumentProvider();
      final FileEditorInput editorInput = new FileEditorInput(f);
      try {
        provider.connect(editorInput);
        provider.aboutToChange(editorInput);
        provider.saveDocument(pm, editorInput, provider.getDocument(editorInput), true);
      } finally {
        provider.changed(editorInput);
        provider.disconnect(editorInput);
      }
    }

    void report(final String task, final IProgressMonitor pm) {
      if (pm.isCanceled()) {
        throw new OperationCanceledException();
      }
      pm.setTaskName(task);
      pm.worked(1);
    }
  }
}

The Test Fragment

We will similarly create a new integration test fragment alongside this plug-in, overriding the default configuration to store the fragment into the plugins subdirectory and to use Maven conventions for the source and output directories.

There are various approaches for testing Eclipse plug-ins, but the fragment approach has been embraced by the Tycho community, so we will use it here.
Again, the project configuration can be boilerplate for now. Of particular interest is the handler test case.

plugins/timezra.eclipse.apply_save_actions.tests/src/test/java/timezra/eclipse/apply_save_actions/handlers/ApplySaveActions.java

package timezra.eclipse.apply_save_actions.handlers;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNull;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Scanner;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.expressions.EvaluationContext;
import org.eclipse.core.resources.IContainer;
import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IFolder;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.resources.IWorkspaceRoot;
import org.eclipse.core.resources.ResourcesPlugin;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.NullProgressMonitor;
import org.eclipse.core.runtime.Path;
import org.eclipse.core.runtime.SubProgressMonitor;
import org.eclipse.core.runtime.preferences.InstanceScope;
import org.eclipse.jdt.core.IClasspathEntry;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jdt.core.JavaCore;
import org.eclipse.jdt.launching.JavaRuntime;
import org.eclipse.jdt.ui.JavaUI;
import org.eclipse.jdt.ui.cleanup.CleanUpOptions;
import org.eclipse.jface.text.TextSelection;
import org.eclipse.jface.viewers.StructuredSelection;
import org.eclipse.ui.ISources;
import org.junit.After;
import org.junit.Before;
import org.junit.Rule;
import org.junit.Test;
import org.junit.rules.MethodRule;
import timezra.eclipse.apply_save_actions.Constants;
import timezra.eclipse.apply_save_actions.tests.ModifiesSaveActionsPreferences;
import timezra.eclipse.apply_save_actions.tests.ModifiesSaveActionsPreferencesRule;

public class ApplySaveActionsPluginTest {

  private static final String SOURCE_FOLDER = "src/test/java";

  private static final String EOL = System.getProperty("line.separator");

  private static final IProgressMonitor NULL_PROGRESS_MONITOR = new NullProgressMonitor();

  private static final String TEST_CLASS = "TestClass";
  private static final String TEST_PACKAGE = "timezra.eclipse.apply_save_actions";

  private static final String TEST_CLASS_BEFORE_SAVE_ACTIONS = "package " + TEST_PACKAGE
      + ";import java.util.*;class " + TEST_CLASS + "{private List<" + TEST_CLASS + "> l;" + TEST_CLASS
      + "(List<" + TEST_CLASS + "> l){this.l=l;}}";

  private static final String TEST_CLASS_AFTER_SAVE_ACTIONS = "package " + TEST_PACKAGE + ";" + EOL + //
      EOL + //
      "import java.util.List;" + EOL + //
      EOL + //
      "class " + TEST_CLASS + " {" + EOL + //
      "  private final List<" + TEST_CLASS + "> l;" + EOL + //
      EOL + //
      "  " + TEST_CLASS + "(List<" + TEST_CLASS + "> l) {" + EOL + //
      "    this.l = l;" + EOL + //
      "  }" + EOL + //
      "}";

  @Rule
  public final MethodRule rule = new ModifiesSaveActionsPreferencesRule();

  private IProject aJavaProject;
  private IFolder aJavaPackage;
  private IFile aJavaFile;

  private IFolder aJavaSourceFolder;

  @Before
  public void setUp() throws CoreException {
    aJavaProject = createAJavaProject("a_java_project");
    aJavaSourceFolder = createASourceFolder(SOURCE_FOLDER);
    aJavaPackage = createAPackage(aJavaSourceFolder, TEST_PACKAGE.replaceAll("\\.", "/"));
    aJavaFile = createAJavaFile(aJavaPackage, TEST_CLASS + ".java");
  }

  @After
  public void tearDown() throws CoreException {
    aJavaProject.delete(true, NULL_PROGRESS_MONITOR);
  }

  @Test
  public void theCurrentSelectionMustBeStructured() throws ExecutionException {
    final ApplySaveActions command = new ApplySaveActions();
    final EvaluationContext context = new EvaluationContext(null, new Object());
    context.addVariable(ISources.ACTIVE_CURRENT_SELECTION_NAME, new TextSelection(0, 100));
    final ExecutionEvent event = new ExecutionEvent(null, Collections.emptyMap(), null, context);
    assertNull(command.execute(event));
  }

  @Test
  @ModifiesSaveActionsPreferences
  public void aJavaFileCanBeReformatted() throws ExecutionException, CoreException, IOException {
    enableJavaSaveActions();

    applySaveActions(JavaCore.create(aJavaFile));

    verifyThatSaveActionsHaveBeenApplied(aJavaFile);
  }

  @Test
  @ModifiesSaveActionsPreferences
  public void aJavaPackageCanBeReformatted() throws ExecutionException, CoreException, IOException {
    enableJavaSaveActions();

    applySaveActions(JavaCore.create(aJavaPackage));

    verifyThatSaveActionsHaveBeenApplied(aJavaFile);
  }

  @Test
  @ModifiesSaveActionsPreferences
  public void aJavaSourceFolderCanBeReformatted() throws ExecutionException, CoreException, IOException {
    enableJavaSaveActions();

    applySaveActions(JavaCore.create(aJavaSourceFolder));

    verifyThatSaveActionsHaveBeenApplied(aJavaFile);
  }

  @Test
  @ModifiesSaveActionsPreferences
  public void aJavaProjectCanBeReformatted() throws ExecutionException, CoreException {
    enableJavaSaveActions();

    applySaveActions(JavaCore.create(aJavaProject));

    verifyThatSaveActionsHaveBeenApplied(aJavaFile);
  }

  private void applySaveActions(final Object selection) throws ExecutionException {
    final ApplySaveActions command = new ApplySaveActions();
    final EvaluationContext context = new EvaluationContext(null, new Object());
    context.addVariable(ISources.ACTIVE_CURRENT_SELECTION_NAME, new StructuredSelection(selection));
    final ExecutionEvent event = new ExecutionEvent(null, Collections.emptyMap(), null, context);
    command.execute(event);
  }

  // contains a beaut that turns a stream into a String without using IoUtils:
  // http://stackoverflow.com/questions/309424/in-java-how-do-a-read-convert-an-inputstream-in-to-a-string
  private void verifyThatSaveActionsHaveBeenApplied(final IFile aJavaFile) throws CoreException {
    final String actualContents;
    final Scanner scanner = new Scanner(aJavaFile.getContents());
    try {
      actualContents = scanner.useDelimiter("\\A").next();
    } finally {
      scanner.close();
    }
    assertEquals(TEST_CLASS_AFTER_SAVE_ACTIONS, actualContents);
  }

  @SuppressWarnings("restriction")
  private void enableJavaSaveActions() {
    InstanceScope.INSTANCE.getNode(JavaUI.ID_PLUGIN).putBoolean(Constants.PERFORM_SAVE_ACTIONS_PREFERENCE, true);

    final Map<String, String> cleanupPreferences = new HashMap<String, String>(
        org.eclipse.jdt.internal.ui.JavaPlugin
            .getDefault()
            .getCleanUpRegistry()
            .getDefaultOptions(
                org.eclipse.jdt.internal.corext.fix.CleanUpConstants.DEFAULT_SAVE_ACTION_OPTIONS)
            .getMap());

    cleanupPreferences.put(org.eclipse.jdt.internal.corext.fix.CleanUpConstants.FORMAT_SOURCE_CODE,
        CleanUpOptions.TRUE);
    cleanupPreferences.put(org.eclipse.jdt.internal.corext.fix.CleanUpConstants.ORGANIZE_IMPORTS,
        CleanUpOptions.TRUE);
    cleanupPreferences.put(org.eclipse.jdt.internal.corext.fix.CleanUpConstants.CLEANUP_ON_SAVE_ADDITIONAL_OPTIONS,
        CleanUpOptions.TRUE);
    org.eclipse.jdt.internal.corext.fix.CleanUpPreferenceUtil.saveSaveParticipantOptions(InstanceScope.INSTANCE,
        cleanupPreferences);
  }

  private IFolder createASourceFolder(final String name) throws CoreException {
    final IFolder aJavaSourceFolder = aJavaProject.getFolder(Path.fromPortableString(name));
    create(aJavaSourceFolder);
    return aJavaSourceFolder;
  }

  private IFolder createAPackage(final IFolder aJavaSourceFolder, final String name) throws CoreException {
    final IFolder aJavaPackage = aJavaSourceFolder.getFolder(Path.fromPortableString(name));
    create(aJavaPackage);
    return aJavaPackage;
  }

  private void create(final IFolder folder) throws CoreException {
    final IContainer parent = folder.getParent();
    if (parent.getType() == IResource.FOLDER && !parent.exists()) {
      create((IFolder) parent);
    }
    folder.create(true, true, NULL_PROGRESS_MONITOR);
  }

  private IFile createAJavaFile(final IFolder aJavaPackage, final String name) throws CoreException {
    final IFile aJavaFile = aJavaPackage.getFile(Path.fromPortableString(name));
    aJavaFile.create(new ByteArrayInputStream(TEST_CLASS_BEFORE_SAVE_ACTIONS.getBytes()), true,
        NULL_PROGRESS_MONITOR);
    return aJavaFile;
  }

  // based on http://www.stateofflow.com/journal/66/creating-java-projects-programmatically
  @SuppressWarnings("restriction")
  private IProject createAJavaProject(final String name) throws CoreException {
    final IWorkspaceRoot root = ResourcesPlugin.getWorkspace().getRoot();
    final IProject project = root.getProject(name);
    project.create(NULL_PROGRESS_MONITOR);
    project.open(NULL_PROGRESS_MONITOR);
    org.eclipse.jdt.internal.ui.wizards.buildpaths.BuildPathsBlock.addJavaNature(project, new SubProgressMonitor(
        NULL_PROGRESS_MONITOR, 1));
    final IJavaProject javaProject = JavaCore.create(project);

    final List<IClasspathEntry> entries = new ArrayList<IClasspathEntry>();
    for (final IClasspathEntry entry : javaProject.getRawClasspath()) {
      if (entry.getEntryKind() == IClasspathEntry.CPE_SOURCE) {
        ((org.eclipse.jdt.internal.core.ClasspathEntry) entry).path = Path.fromPortableString(SOURCE_FOLDER);
      }
      entries.add(entry);
    }
    entries.add(JavaRuntime.getDefaultJREContainerEntry());
    javaProject.setRawClasspath(entries.toArray(new IClasspathEntry[entries.size()]), NULL_PROGRESS_MONITOR);

    return project;
  }
}

The Feature

Now that we have a tested plug-in, we will create an Eclipse feature to contain it for distribution. We can do practically all our configuration through the New Feature Project Wizard, except we want to put the feature project into a features subdirectory in the same way that we put our plug-in and fragment into the plugins subdirectory.

The Update Site

Now that we have a tested plug-in and a feature to contain it, we will create an Eclipse update site for publishing the feature. In the New Update Site Project Wizard, we will again override the default location so that our update site project is in an update-site subdirectory, just as we separated our plug-in, fragment and feature into plugins and features subdirectories.

NB: Whereas we may have multiple features or plug-ins for our project, we will have a single update site; thus the update-site project is not contained in a subfolder of update-site, but in this folder directly.

Tycho

Compiling, running integration tests and packaging an application entirely within an IDE does not scale to even a single programmer over time, let alone a team of programmers working on multiple plug-in projects. So far, the amount of ceremony for creating our menu contribution has been high, but the IDE has reduced a significant amount of the boilerplate. Before Tycho, the amount of ceremony and hackery required to get plugins, features and update sites packaged and unit and integration test suites running on a CI server had been prohibitively high. Tycho removes a significant amount of that pain.
Generating meaningful poms for our projects is as trivial as going into each of the features, plugins and update-site directories and running a Tycho goal.

mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms -DgroupId=timezra.eclipse

We can combine some of the boilerplate in each of the subproject poms in an über-parent pom at the root of our workspace. We will also add the Indigo p2 repository and a target platform configuration resolver since we are developing our Eclipse components Manifest-first.

pom.xml

We will also configure Tycho to use the UI test runner for our integration test suite, as well as add any platform-specific runtime plug-in dependencies or configuration to the test fragment pom.

plugins/timezra.eclipse.apply_save_actions.tests/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
  xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>timezra.eclipse</groupId>
    <artifactId>apply-save-actions-plugins-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>
  <groupId>timezra.eclipse</groupId>
  <artifactId>timezra.eclipse.apply_save_actions.tests</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>eclipse-test-plugin</packaging>
  
  <build>
    <outputDirectory>target/test-classes</outputDirectory>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-surefire-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <useUIHarness>true</useUIHarness>
        </configuration>
      </plugin>
    </plugins>
  </build>
  <profiles>
    <profile>
      <id>osx</id>
      <activation>
        <property>
          <name>java.vendor.url</name>
          <value>http://www.apple.com/</value>
        </property>
      </activation>
      <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <groupId>org.eclipse.tycho</groupId>
              <artifactId>tycho-surefire-plugin</artifactId>
              <version>${tycho-version}</version>
              <configuration>
                <argLine>-XstartOnFirstThread</argLine>
                <dependencies>
                  <dependency>
                    <type>p2-installable-unit</type>
                    <artifactId>org.eclipse.jdt.launching.macosx</artifactId>
                  </dependency>
                </dependencies>
              </configuration>
            </plugin>
          </plugins>
        </pluginManagement>
      </build>
    </profile>
  </profiles>
</project>

NB: we would use a different configuration if our fragment contained unit-tests instead of integration tests.

JAR signing

If you do not have access to a certificate from a trusted authority, you can generate a self-signed certificate with 1-year validity by a command such as

keytool -genkey -alias _keystore_alias_ -keystore /path/to/keystore -validity 365

In order to sign the jars deployed to our update-site before release, we will add a new profile with a plug-in management configuration to the über-parent pom.

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project ....>
  ....
  <profiles>
    <profile>
      <id>sign</id>
      
      <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-jarsigner-plugin</artifactId>
              <version>1.2</version>
              <executions>
                <execution>
                  <goals>
                    <id>sign</id>
                    <goal>sign</goal>
                  </goals>
                </execution>
                <execution>
                  <goals>
                    <id>verify</id>
                    <goal>verify</goal>
                  </goals>
                </execution>
              </executions>
            </plugin>
          </plugins>
        </pluginManagement>
      </build>
    </profile>
  </profiles>
  ....
</project>

Similarly, we will configure the plug-ins and features parent poms for jar signing.

plugins/pom.xml and features/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project ....>
  ....
  <profiles>
    <profile>
      <id>sign</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jarsigner-plugin</artifactId>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
</project>

Publishing

We are now ready to build and test our signed plug-ins and features and to package them in an update site for deployment.

mvn -Psign -Djarsigner.keystore=/path/to/keystore -Djarsigner.storepass=_keystore_password_ -Djarsigner.alias=_keystore_alias_ clean package integration-test

There will now be a fully deployable update site in update-site/target/site.
For this particular project, I distribute the contents of this directory to the gh-pages branch of the project on github.
Since the update site for the project is publicly-available and since I have an Eclipse Bugzilla login, I can simply add a new solution listing to the Eclipse Marketplace to make the menu contribution even more discoverable by and accessible to Eclipse users.

Conclusion

This tutorial has provided the outline for the workflow of taking an idea for a single-featured Eclipse contribution from inception to delivery in a very short amount of time. While Eclipse tooling has for years provided the means to perform the tasks of plug-in, fragment, feature and update site publishing entirely within the IDE, it is the Tycho project that lowers the barrier to entry for scaling out plug-in development by making the build and test process far simpler to automate and to configure than other PDE-based build systems. Along the way, we have explored JAR signing and uploading of content to github and to the Eclipse Marketplace, and we have hopefully developed a menu contribution that others will find useful in their own projects.

JPA Callbacks With Hibernate

2011-10-05T09:54:00.000-07:00

Goal:

The purpose of this blog entry is to provide one solution for using JPA Annotations with Hibernate but without using the Hibernate EntityManager. Thanks to Ben Macfarlane for posing this problem and for doing the groundwork for me to come up with a somewhat simple solution.

tl;dr

If you want to look right away at working code that compares the configuration of JPA callbacks with the EntityManager and the Hibernate SessionFactory, a sample project based on this tutorial is available.

Create a Maven Project:

We will start with a boilerplate Maven project that includes dependencies on Spring, Hibernate and JUnit.
pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>timezra.hibernate</groupId>
  <artifactId>callbacks</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <description>Demo for using JPA callbacks with hibernate</description>
  <properties>
    <maven.compiler.source>1.6</maven.compiler.source>
    <maven.compiler.target>1.6</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-orm</artifactId>
      <version>3.0.6.RELEASE</version>
    </dependency>
    <dependency>
      <groupId>cglib</groupId>
      <artifactId>cglib-nodep</artifactId>
      <version>2.2.2</version>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>3.6.7.Final</version>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-annotations</artifactId>
      <version>3.5.6-Final</version>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>3.1.0.GA</version>
    </dependency>
    <dependency>
      <groupId>org.javassist</groupId>
      <artifactId>javassist</artifactId>
      <version>3.15.0-GA</version>
    </dependency>
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <version>1.3.160</version>
    </dependency>
    <dependency>
      <groupId>commons-dbcp</groupId>
      <artifactId>commons-dbcp</artifactId>
      <version>1.4</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.10</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-test</artifactId>
      <version>3.0.6.RELEASE</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Create a Domain and Domain Access:

Our domain can be as simple as a single POJO that uses javax.persistence annotations such as @PrePersist, @PreUpdate and @PostLoad.
src/main/java/timezra/hibernate/callbacks/domain/Author.java

package timezra.hibernate.callbacks.domain;

import java.util.Calendar;
import java.util.Date;
import java.util.Locale;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.PostLoad;
import javax.persistence.PrePersist;
import javax.persistence.PreUpdate;
import javax.persistence.Table;
import javax.persistence.Transient;
import javax.persistence.UniqueConstraint;
import org.hibernate.validator.NotNull;

@Entity
@Table(uniqueConstraints = @UniqueConstraint(columnNames = Author.NAME_ATTRIBUTE))
public class Author {

  public static final String NAME_ATTRIBUTE = "name";

  @Id
  @GeneratedValue(strategy = GenerationType.SEQUENCE)
  private Long id;
  @NotNull
  private String name;
  private Date dateOfBirth;
  @Transient
  private Integer age;
  @NotNull
  private Date dateCreated;
  @NotNull
  private Date lastUpdated;

  @PrePersist
  void prePersist() {
    dateCreated = lastUpdated = new Date();
  }

  @PreUpdate
  void preUpdate() {
    lastUpdated = new Date();
  }

  @PostLoad
  void postLoad() {
    if (dateOfBirth != null) {
      final Calendar now = Calendar.getInstance(Locale.getDefault());
      final int thisYear = now.get(Calendar.YEAR);
      final int thisDay = now.get(Calendar.DAY_OF_YEAR);
      now.setTime(dateOfBirth);
      final int birthYear = now.get(Calendar.YEAR);
      final int birthDay = now.get(Calendar.DAY_OF_YEAR);
      age = thisYear - birthYear - (birthDay > thisDay ? 1 : 0);
    }
  }

  public Long getId() {
    return id;
  }

  public Date getDateCreated() {
    return dateCreated;
  }

  public Date getLastUpdated() {
    return lastUpdated;
  }

  public Integer getAge() {
    return age;
  }

  public Date getDateOfBirth() {
    return dateOfBirth;
  }

  public void setDateOfBirth(final Date dateOfBirth) {
    this.dateOfBirth = dateOfBirth;
  }

  public String getName() {
    return name;
  }

  public void setName(final String name) {
    this.name = name;
  }
}

A DAO and Service can provide access into our domain.
src/main/java/timezra/hibernate/callbacks/dao/AuthorDAO.java

package timezra.hibernate.callbacks.dao;

import javax.annotation.Resource;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.criterion.Restrictions;
import org.springframework.stereotype.Repository;
import timezra.hibernate.callbacks.domain.Author;

@Repository
public class AuthorDAO {

  @Resource
  private SessionFactory sessionFactory;

  public void create(final Author a) {
    getSession().save(a);
  }

  public Author findByName(final String name) {
    return (Author) getSession().createCriteria(Author.class) //
        .add(Restrictions.eq(Author.NAME_ATTRIBUTE, name)) //
        .uniqueResult();
  }

  public void update(final Author a) {
    getSession().update(a);
  }

  public void delete(final Author a) {
    getSession().delete(a);
  }

  private Session getSession() {
    return sessionFactory.getCurrentSession();
  }
}

src/main/java/timezra/hibernate/callbacks/service/AuthorService.java

package timezra.hibernate.callbacks.service;

import javax.annotation.Resource;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
import timezra.hibernate.callbacks.dao.AuthorDAO;
import timezra.hibernate.callbacks.domain.Author;

@Service
public class AuthorService {

  @Resource
  private AuthorDAO authorDAO;

  @Transactional
  public void create(final Author a) {
    authorDAO.create(a);
  }

  @Transactional
  public void update(final Author a) {
    authorDAO.update(a);
  }

  @Transactional
  public void delete(final Author a) {
    authorDAO.delete(a);
  }

  @Transactional(propagation = Propagation.SUPPORTS)
  public Author findByName(final String name) {
    return authorDAO.findByName(name);
  }
}

Wire It Together With Spring:

We will use Spring to glue all our components together and to manage their lifecycles.
src/main/resources/applicationContext.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
  xmlns:tx="http://www.springframework.org/schema/tx"
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
    http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd">

  <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
    destroy-method="close">
    <property name="driverClassName" value="org.h2.Driver" />
    <property name="url" value="jdbc:h2:test" />
    <property name="username" value="sa" />
    <property name="password" value="" />
  </bean>

  <bean id="sessionFactory"
    class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
    <property name="dataSource" ref="dataSource" />
    <property name="packagesToScan">
      <list>
        <value>timezra.hibernate.callbacks.domain</value>
      </list>
    </property>
    <property name="hibernateProperties">
      <props>
        <prop key="hibernate.dialect">org.hibernate.dialect.H2Dialect</prop>
        <prop key="hibernate.hbm2ddl.auto">update</prop>
      </props>
    </property>
  </bean>

  <bean id="transactionManager"
    class="org.springframework.orm.hibernate3.HibernateTransactionManager">
    <property name="sessionFactory" ref="sessionFactory" />
  </bean>

  <context:component-scan base-package="timezra.hibernate.callbacks" />
  <context:annotation-config />
  <tx:annotation-driven />
</beans>

Test The JPA Callbacks:

Finally we can test that the annotated methods are called at the expected times during Hibernate lifecycle events.
src/test/java/timezra/hibernate/callbacks/domain/AuthorTest.java

package timezra.hibernate.callbacks.domain;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertNull;
import static org.junit.Assert.assertTrue;
import java.util.Calendar;
import java.util.Date;
import java.util.Locale;
import javax.annotation.Resource;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import timezra.hibernate.callbacks.service.AuthorService;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("/applicationContext.xml")
public class AuthorTest {

  @Resource
  private AuthorService authorService;

  private Author testAuthor;

  @Before
  public void setup() {
    testAuthor = new Author();
    testAuthor.setName("timezra");
    authorService.create(testAuthor);
  }

  @After
  public void tearDown() {
    authorService.delete(testAuthor);
  }

  @Test
  public void theCreationDateIsSetAutomatically() {
    assertNotNull(testAuthor.getDateCreated());
  }

  @Test
  public void theUpdatedDateIsSetAutomaticallyOnCreation() {
    assertEquals(testAuthor.getDateCreated(), testAuthor.getLastUpdated());
  }

  @Test
  public void theUpdatedDateIsSetAutomaticallyOnUpdate() {
    testAuthor.setDateOfBirth(new Date());

    authorService.update(testAuthor);

    assertTrue(testAuthor.getDateCreated().before(testAuthor.getLastUpdated()));
  }

  @Test
  public void theAgeIsSetAutomaticallyWhenTheAuthorIsLoaded() {
    final Integer expectedAge = 42;
    final Calendar birthDate = Calendar.getInstance(Locale.getDefault());
    birthDate.add(Calendar.YEAR, -expectedAge);
    testAuthor.setDateOfBirth(birthDate.getTime());
    authorService.update(testAuthor);

    assertNull(testAuthor.getAge());
    assertEquals(expectedAge, authorService.findByName(testAuthor.getName()).getAge());
  }
}

We should expect all these tests to fail with a Hibernate validation Exception.

Update Project Dependencies:

Fortunately, the hibernate-entitymanager component provides a set of JPA lifecycle listeners that can be used independent of the Hibernate EntityManager, so we will update our project dependencies.
pom.xml

<project ....>
  ....
  <dependencies>
    ....
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-entitymanager</artifactId>
      <version>3.6.7.Final</version>
    </dependency>
    ....
  </dependencies>
</project>

NB: for this sample code, the version must be 3.6.x+ in order to access the ReflectionManager from the Hibernate configuration.

Register Hibernate Event Listeners:

We must manually tie the JPA lifecycle listeners to Hibernate events, much as the org.hibernate.ejb.EventListenerConfigurator#configure would if the Hibernate EntityManager were used.
src/main/java/timezra/hibernate/callbacks/domain/EntityCallbackHandlerInitializer.java

package timezra.hibernate.callbacks.dao;

import java.util.Iterator;
import javax.annotation.PostConstruct;
import javax.annotation.Resource;
import org.hibernate.annotations.common.reflection.ReflectionManager;
import org.hibernate.cfg.Configuration;
import org.hibernate.ejb.event.EntityCallbackHandler;
import org.hibernate.mapping.PersistentClass;
import org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean;
import org.springframework.stereotype.Component;

@Component
public class EntityCallbackHandlerInitializer {

  @Resource
  private AnnotationSessionFactoryBean annotationSessionFactory;

  @Resource
  private EntityCallbackHandler entityCallbackHandler;

  @PostConstruct
  public void init() throws ClassNotFoundException {
    final Configuration configuration = annotationSessionFactory.getConfiguration();
    final ReflectionManager reflectionManager = configuration.getReflectionManager();
    final Iterator<PersistentClass> classMappings = configuration.getClassMappings();
    while (classMappings.hasNext()) {
      entityCallbackHandler.add(
          reflectionManager.classForName(classMappings.next().getClassName(), this.getClass()),
          reflectionManager);
    }
  }
}

Finally, we will update the Hibernate configuration in the Spring context to use these event listeners. This configuration is based off a similar solution on the Spring Forum.
src/main/resources/applicationContext.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans ....>
  ....
  <bean id="sessionFactory" ....>
    ....
    <property name="eventListeners">
      <map>
        <entry key="save" value-ref="saveEventListener" />
        <entry key="flush-entity" value-ref="flushEntityEventListener" />
        <entry key="post-load" value-ref="postLoadEventListener" />
      </map>
    </property>
  </bean>

  <bean id="saveEventListener" parent="callbackHandlerEventListener"
    class="org.hibernate.ejb.event.EJB3SaveEventListener" />

  <bean id="flushEntityEventListener" parent="callbackHandlerEventListener"
    class="org.hibernate.ejb.event.EJB3FlushEntityEventListener" />

  <bean id="postLoadEventListener" parent="callbackHandlerEventListener"
    class="org.hibernate.ejb.event.EJB3PostLoadEventListener" />

  <bean id="entityCallbackHandler" class="org.hibernate.ejb.event.EntityCallbackHandler" />

  <bean id="callbackHandlerEventListener" abstract="true"
    class="org.hibernate.ejb.event.CallbackHandlerConsumer">
    <property name="callbackHandler" ref="entityCallbackHandler" />
  </bean>
  ....
</beans>

NB: This configuration is for a subset of javax.persistence annotations and should be considered a starting point. It is up to the reader to configure Hibernate to use other other listeners in the org.hibernate.ejb.event package if the enablement of more JPA annotations is desired. For the purpose of this tutorial, the three listeners above are sufficient.

The test cases now succeed.

Conclusion:

The purpose of this tutorial has been to demonstrate that, with minimal code and configuration additional to what is necessary for a standard Maven/Spring/Hibernate project, Hibernate can detect JPA annotations and tie them to its persistence lifecycle events. Along the way, we have also developed a simple methodology for testing that JPA annotated methods are called when expected, and this methodology can be used to extend the sample code to cover the remaining javax.persistence annotations not specified in this tutorial.

Sample code based on this tutorial is also available.