NoBlogDefFound

Gentle introduction to WADL (in Java)

2012-01-24T18:57:00.000+01:00

WADL (Web Application Description Language) is to REST what WSDL is to SOAP. The mere existence of this language causes a lot of controversy (see: Do we need WADL? and To WADL or not to WADL). I can think of few legitimate use cases for using WADL, but if you are here already, you are probably not seeking for yet another discussion. So let us move forward to the WADL itself.

In principle WADL is similar to WSDL, but the structure of the language is much different. Whilst WSDL defines a flat list of messages and operations either consuming or producing some of them, WADL emphasizes the hierarchical nature of RESTful web services. In REST, the primary artifact is the resource. Each resource (noun) is represented as an URI. Every resource can define both CRUD operations (verbs, implemented as HTTP methods) and nested resources. The nested resource has a strong relationship with a parent resource, typically representing an ownership.

A simple example would be http://example.com/api/books resource representing a list of books. You can (HTTP) GET this resource, meaning to retrieve the whole list. You can also GET the http://example.com/api/books/7 resource, fetching the details of 7th book inside books resource. Or you can even PUT new version or DELETE the resource altogether using the same URI. You are not limited to a single level of nesting: GETting http://example.com/api/books/7/reviews?page=2&size=10 will retrieve the second page (up to 10 items) of reviews of 7th book. Obviously you can also place other resources next to books, like http://example.com/api/readers

The requirement arose to formally and precisely describe every available resource, method, request and response, just like WSDL guys were able to do. WADL is one of the options to describe “available URIs", although some believe that well-written REST service should be self-descriptive (see HATEOAS). Nevertheless here is a simple, empty WADL document:

<application xmlns="http://wadl.dev.java.net/2009/02">
    <resources base="http://example.com/api"/>
</application>

Nothing fancy here. Note that the <resources> tag defines base API address. All named resources, which we are just about to add, are relative to this address. Also you can define several <resources> tags to describe more than one APIs. So, let's add a simple resource:

<application xmlns="http://wadl.dev.java.net/2009/02">
    <resources base="http://example.com/api">
        <resource path="books">
            <method name="GET"/>
            <method name="POST"/>
        </resource>
    </resources>
</application>

This defines resource under http://example.com/api/books with two methods possible: GET to retrieve the whole list and POST to create (add) new item. Depending on your requirements you might want to allow DELETE method as well (to delete all items), and it is the responsibility of WADL to document what is allowed.

Remember our example at the beginning: /books/7? Obviously 7 is just an example and we won't declare every possible book id in WADL. Instead there is a handy placeholder syntax:

<application xmlns="http://wadl.dev.java.net/2009/02">
    <resources base="http://example.com/api">
        <resource path="books">
            <method name="GET"/>
            <resource path="{bookId}">
                <param required="true" style="template" name="bookId"/>
                <method name="GET"/>
            </resource>
        </resource>
    </resources>
</application>

There are two important aspects you should note: first, The {bookId} place-holder was used in place of nested resource. Secondly, to make it clear, we are documenting this place-holder using <param/> tag. We will see soon how it can be used in combination with methods. Just to make sure you are still with me, the document above describes GET /books and GET /books/some_id resources.

<application xmlns="http://wadl.dev.java.net/2009/02">
    <resources base="http://example.com/api">
        <resource path="books">
            <method name="GET"/>
            <resource path="{bookId}">
                <param required="true" style="template" name="bookId"/>
                <method name="GET"/>
                <method name="DELETE"/>
                <resource path="reviews">
                    <method name="GET">
                        <request>
                            <param name="page" required="false" default="1" style="query"/>
                            <param name="size" required="false" default="20" style="query"/>
                        </request>
                    </method>
                </resource>
            </resource>
        </resource>
        <resource path="readers">
            <method name="GET"/>
        </resource>
    </resources>
</application>

The web service is getting complex, however it describes quite a lot of operations. First of all GET /books/42/reviews is a valid operation. But the interesting part is the nested <request/> tag. As you can see we can describe parameters of each method independently. In our case optional query parameters (as opposed to template parameters used previously for URI place-holders) were defined. This gives the client additional knowledge about acceptable page and size query parameters. This means that /books/7/reviews?page=2&size=10 is a valid resource identifier. And did I mention that every resource, method and parameter can have documentation attached as per the WADL specification?

We will stop here and only mention about remaining pieces of WADL. First of all, as you have probably guessed so far, there is also a <response/> child tag possible for each <method/>. Both request and response can define exact grammar (e.g. in XML Schema) that either the request or the response must follow. The response can also document possible HTTP response codes. But since we will be using the knowledge you have gained so far in a code-first application, I intentionally left the <grammars/> definition. WADL is agile and it allows you to define as little (or as much) information as you need.

So we know the basics of WADL, now we would like to use it, maybe as a consumer or as a producer in a Java-based application. Fortunately there is a wadl.xsd XML Schema description of the language itself, which we can use to generate JAXB-annotated POJOs to work with (using xjc tool in the JDK):

$ wget http://www.w3.org/Submission/wadl/wadl.xsd
$ xjc wadl.xsd

And there it... hangs! The life of a software developer is full of challenges and non-trivial problems. And sometimes it is just an annoying network filter that makes suspicious packets (together with half hour of your life) disappear. It is not hard to spot the problem, once you recall that article written around 2008: W3C’s Excessive DTD Traffic:

  <xs:import namespace="http://www.w3.org/XML/1998/namespace" 
    schemaLocation="http://www.w3.org/2001/xml.xsd"/>

Accessing xml.xsd from the browser returns an HTML page instantly, but xjc tool waits forever. Downloading this file locally and correcting the schemaLocation attribute in wadl.xsd helped. It's always the little things...

$ xjc wadl.xsd 
parsing a schema... 
compiling a schema... 
net/java/dev/wadl/_2009/_02/Application.java 
net/java/dev/wadl/_2009/_02/Doc.java 
net/java/dev/wadl/_2009/_02/Grammars.java 
net/java/dev/wadl/_2009/_02/HTTPMethods.java 
net/java/dev/wadl/_2009/_02/Include.java 
net/java/dev/wadl/_2009/_02/Link.java 
net/java/dev/wadl/_2009/_02/Method.java 
net/java/dev/wadl/_2009/_02/ObjectFactory.java 
net/java/dev/wadl/_2009/_02/Option.java 
net/java/dev/wadl/_2009/_02/Param.java 
net/java/dev/wadl/_2009/_02/ParamStyle.java 
net/java/dev/wadl/_2009/_02/Representation.java 
net/java/dev/wadl/_2009/_02/Request.java 
net/java/dev/wadl/_2009/_02/Resource.java 
net/java/dev/wadl/_2009/_02/ResourceType.java 
net/java/dev/wadl/_2009/_02/Resources.java 
net/java/dev/wadl/_2009/_02/Response.java 
net/java/dev/wadl/_2009/_02/package-info.java

Since we'll be using these classes in a maven based project (and I hate committing generated classes to source repository), let's move xjc execution to maven lifecycle:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxb2-maven-plugin</artifactId>
    <version>1.3</version>
    <dependencies>
        <dependency>
            <groupId>net.java.dev.jaxb2-commons</groupId>
            <artifactId>jaxb-fluent-api</artifactId>
            <version>2.0.1</version>
            <exclusions>
                <exclusion>
                    <groupId>com.sun.xml</groupId>
                    <artifactId>jaxb-xjc</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <goals>
                <goal>xjc</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <arguments>-Xfluent-api</arguments>
        <bindingFiles>bindings.xjb</bindingFiles>
        <packageName>net.java.dev.wadl</packageName>
    </configuration>
</plugin>

Well, pom.xml isn't the most concise format ever... Never mind, this will generate WADL XML classes during every build, before the source code is compiled. I also love the fluent-api plugin that adds with*() methods along with ordinary setters, returning this to allow chaining. Pretty convenient. Finally we define more pleasant package name for generated artifacts (if you find net.java.dev.wadl._2009._02 package name pleasant enough, you can skip this step) and add Wadl prefix to all generated classes bindings.xjb file:

<jxb:bindings version="1.0"
  xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
  jxb:extensionBindingPrefixes="xjc">

    <jxb:bindings schemaLocation="../xsd/wadl.xsd" node="/xs:schema">
        <jxb:schemaBindings>
            <jxb:nameXmlTransform>
                <jxb:typeName prefix="Wadl"/>
                <jxb:anonymousTypeName prefix="Wadl"/>
                <jxb:elementName prefix="Wadl"/>
            </jxb:nameXmlTransform>
        </jxb:schemaBindings>
    </jxb:bindings>

</jxb:bindings>

We are now ready to produce and consume WADL in XML format using JAXB and POJO classes. Equipped with that knowledge and the foundation we are ready to develop some interesting library – which will be the subject of the next article.

Enabling JMX in Hibernate, EhCache, Quartz, DBCP and Spring

2011-12-20T19:44:00.000+01:00

Continuing our journey with JMX (see: ...JMX for human beings) we will learn how to enable JMX support (typically statistics and monitoring capabilities) in some popular frameworks. Most of this information can be found on project's home pages, but I decided to collect it with few the addition of some useful tips.

Hibernate (with Spring support)

Exposing Hibernate statistics with JMX is pretty simple, however some nasty workarounds are requires when JPA API is used to obtain underlying SessionFactory

class JmxLocalContainerEntityManagerFactoryBean() extends LocalContainerEntityManagerFactoryBean {
 override def createNativeEntityManagerFactory() = {
  val managerFactory = super.createNativeEntityManagerFactory()
  registerStatisticsMBean(managerFactory)
  managerFactory
 }

 def registerStatisticsMBean(managerFactory: EntityManagerFactory) {
  managerFactory match {
   case impl: EntityManagerFactoryImpl =>
    val mBean = new StatisticsService();
    mBean.setStatisticsEnabled(true)
    mBean.setSessionFactory(impl.getSessionFactory);
    val name = new ObjectName("org.hibernate:type=Statistics,application=spring-pitfalls")
    ManagementFactory.getPlatformMBeanServer.registerMBean(mBean, name);
   case _ =>
  }
 }

}

Note that I have created a subclass of Springs built-in LocalContainerEntityManagerFactoryBean. By overriding createNativeEntityManagerFactory() method I can access EntityManagerFactory and by trying to downcast it to org.hibernate.ejb.EntityManagerFactoryImpl we were able to register Hibernate Mbean.
One more thing has left. Obviously we have to use our custom subclass instead of org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean. Also, in order to collect the actual statistics instead of just seeing zeroes all the way down we must set the hibernate.generate_statistics flag.

@Bean
def entityManagerFactoryBean() = {
 val entityManagerFactoryBean = new JmxLocalContainerEntityManagerFactoryBean()
 entityManagerFactoryBean.setDataSource(dataSource())
 entityManagerFactoryBean.setJpaVendorAdapter(jpaVendorAdapter())
 entityManagerFactoryBean.setPackagesToScan("com.blogspot.nurkiewicz")
 entityManagerFactoryBean.setJpaPropertyMap(
  Map(
   "hibernate.hbm2ddl.auto" -> "create",
   "hibernate.format_sql" -> "true",
   "hibernate.ejb.naming_strategy" -> classOf[ImprovedNamingStrategy].getName,
   "hibernate.generate_statistics" -> true.toString
  ).asJava
 )
 entityManagerFactoryBean
}

Here is a sample of what can we expect to see in JvisualVM (don't forget to install all plugins!):

In addition we get a nice Hibernate logging:

HQL: select generatedAlias0 from Book as generatedAlias0, time: 10ms, rows: 20

EhCache

Monitoring caches is very important, especially in application where you expect values to generally be present there. I tend to query the database as often as needed to avoid unnecessary method arguments or local caching. Everything to make code as simple as possible. However this approach only works when caching on the database layer works correctly. Similar to Hibernate, enabling JMX monitoring in EhCache is a two-step process. First you need to expose provided MBean in MBeanServer:

@Bean(initMethod = "init", destroyMethod = "dispose")
def managementService = new ManagementService(ehCacheManager(), platformMBeanServer(), true, true, true, true, true)

@Bean def platformMBeanServer() = ManagementFactory.getPlatformMBeanServer

def ehCacheManager() = ehCacheManagerFactoryBean.getObject

@Bean def ehCacheManagerFactoryBean = {
 val ehCacheManagerFactoryBean = new EhCacheManagerFactoryBean
 ehCacheManagerFactoryBean.setShared(true)
 ehCacheManagerFactoryBean.setCacheManagerName("spring-pitfalls")
 ehCacheManagerFactoryBean
}

Note that I explicitly set CacheManager name. This is not required but this name is used as part of the Mbean name and a default one contains hashCode value, which is not very pleasant. The final touch is to enable statistics on a cache basis:

<cache name="org.hibernate.cache.StandardQueryCache"
    maxElementsInMemory="10000"
    eternal="false"
    timeToIdleSeconds="3600"
    timeToLiveSeconds="600"
    overflowToDisk="false"
    memoryStoreEvictionPolicy="LRU"
    statistics="true"
/>

Now we can happily monitor various caching characteristics of every cache separately:

As we can see the percentage of cache misses increases. Never a good thing. If we don't enable cache statistics, enabling JMX is still a good idea since we get a lot of management operations for free, including flushing and clearing caches (useful during debugging and testing).

Quartz scheduler

In my humble opinion Quartz scheduler is very underestimated library, but I will write an article about it on its own. This time we will only learn how to monitor it via JMX. Fortunately it's as simple as adding:

org.quartz.scheduler.jmx.export=true

To quartz.properties file. The JMX support in Quartz could have been slightly broader, but still one can query e.g. which jobs are currently running. By the way the new major version of Quartz (2.x) brings very nice DSL-like support for scheduling:

val job = newJob(classOf[MyJob])
val trigger = newTrigger().
  withSchedule(
   repeatSecondlyForever()
  ).
  startAt(
   futureDate(30, SECOND)
  )
scheduler.scheduleJob(job.build(), trigger.build())

Apache Commons DBCP

Apache Commons DBCP is the most reasonable JDBC pooling library I came across. There is also c3p0, but it doesn't seem like it's actively developed any more. Tomcat JDBC Connection Pool looked promising, but since it's bundled in Tomcat, your JDBC drivers can no longer be packaged in WAR.
The only problem with DBCP is that it does not support JMX. At all (see this two and a half year old issue). Fortunately this can be easily worked around. Besides we will learn how to use Spring built-in JMX support.
Looks like the standard BasicDataSource has all what we need, all we have to do is to expose existing metrics via JMX. With Spring it is dead-simple – just subclass BasicDataSource and add @ManagedAttribute annotation over desired attributes:

@ManagedResource
class ManagedBasicDataSource extends BasicDataSource {

    @ManagedAttribute override def getNumActive = super.getNumActive
    @ManagedAttribute override def getNumIdle = super.getNumIdle
    @ManagedAttribute def getNumOpen = getNumActive + getNumIdle
    @ManagedAttribute override def getMaxActive: Int= super.getMaxActive
    @ManagedAttribute override def setMaxActive(maxActive: Int) {
        super.setMaxActive(maxActive)
    }

    @ManagedAttribute override def getMaxIdle = super.getMaxIdle
    @ManagedAttribute override def setMaxIdle(maxIdle: Int) {
        super.setMaxIdle(maxIdle)
    }

    @ManagedAttribute override def getMinIdle = super.getMinIdle
    @ManagedAttribute override def setMinIdle(minIdle: Int) {
        super.setMinIdle(minIdle)
    }

    @ManagedAttribute override def getMaxWait = super.getMaxWait
    @ManagedAttribute override def setMaxWait(maxWait: Long) {
        super.setMaxWait(maxWait)
    }

    @ManagedAttribute override def getUrl = super.getUrl
    @ManagedAttribute override def getUsername = super.getUsername
}

Here are few data source metrics going crazy during load-test:

JMX support in the Spring framework itself is pretty simple. As you have seen above exposing arbitrary attribute or operation is just a matter of adding an annotation. You only have to remember about enabling JMX support using either XML or Java (also see: SPR-8943 : Annotation equivalent to <context:mbean-export/> with @Configuration):

<context:mbean-export/>

or:

@Bean def annotationMBeanExporter() = new AnnotationMBeanExporter()

This article wasn't particularly exciting. However, the knowledge of JMX metrics will enable us to write simple yet fancy dashboards in no time. Stay tuned!

Spring pitfalls: transactional tests considered harmful

2011-11-15T22:27:00.001+01:00

One of the Spring killer-features is anin-container integrationtesting. While EJB lacked this functionality for many years (JavaEE 6 finally addressesthis, however I haven't, ekhem, tested it), Spring from the verybeginning allowed you to test the full stack, starting from web tier,through services all the way down to the database.

Database is the problematic part. Firstyou need to use in-memory self-contained database like H2to decouple your tests from an external database. Spring helps withthis to a great degree, especially now with profiles and embeddeddatabase support. The second problem is more subtle. Whiletypical Spring application is almost completely stateless (for betteror worse), database is inherently stateful. This complicatesintegration testing since the very first principle of writing testsis that they should be independent on each other and repeatable. Ifone test writes something to the database, another test may fail;also the same test may fail on subsequent call due to databasechanges.

Obviously Spring handlesthis problem as well with a very neat trick: prior to runningevery test Spring starts a new transaction. The whole test (includingits setup and tear down) runs within the same transaction which is...rolled back at the end. This means all the changes made during thetest are visible in the database just like if they were persisted.However rollback after every test wipes out all the changes and thenext test works on a clean and freshdatabase. Brilliant!

Unfortunatelythis is not yet another article about Spring integration testingadvantages. I think I have written hundreds if not thousands of suchtests and I truly appreciate the transparent support Spring frameworkgives. But I also came across numerous quirks and inconsistenciesintroduces by this comfortable feature. To make matters worse, veryoften so-called transactional tests are actually hidingerrorsconvincing the developer that the software works, while it failsafter deployment! Here is a non-exhaustive but eye-opening collectionof issues:


@Test
public void shouldThrowLazyInitializationExceptionWhenFetchingLazyOneToManyRelationship() throws Exception {
  //given
  final Book someBook = findAnyExistingBook();

  //when
  try {
    someBook.reviews().size();
    fail();
  } catch(LazyInitializationException e) {
    //then
  }
}

Thisis a known issue with Hibernate and spring integration testing. Bookis a database entity with one-to-many, lazy by default, relationshipto Reviews. findAnyExistingBook() simply reads a test book from atransactional service. Now a bit of theory: as long as an entity isbound to a session (EntityManager if using JPA), it can lazily andtransparently load relationships. In our case it means: as long as itis within a scope of a transaction. The moment an entity leaves atransaction, it becomes detached. At this lifecycle stage an entityis no longer attached to a session/EntityManager (which has beencommitted and closed already) and any approach to fetch lazyproperties throws the dreadful LazyInitializationException. Thisbehaviour is actually standardized in JPA (except the exception classitself, which is vendor specific).

Inour case we are callling .reviews() (Scala-style “getter”, wewill translate our test case to ScalaTest soon as well) and expectingto see the Hibernate exception. However the exception is not thrownand the application keeps going. That's because the whole test isrunning within a transaction and the Book entity never gets out oftransactional scope. Lazy loading alwaysworks in Spring integration tests.

Tobe fair, we will never see tests like this in real life (unless youare testing to make sure that a given collection is lazy –unlikely). In real life we are testing business logic which justworks in tests. However after deploying we start experiencingLazyInitializationException. But we tested it! Not only Springintegration testing support hidthe problem,but it also encourages the developer to throw in OpenSessionInViewFilteror OpenEntityManagerInViewFilter.In other words: our test not only didn't discover a bug in our code,but it also significantly worsen our overall architecture andperformance. Not what I would expect.

Mytypical workflow these days while implementing some end-to-endfeature is to write back-end tests, implement the back-end includingREST API and when everything runs smoothly deploy it and proceed withthe GUI. The latter is written using AJAX/JavaScript completely so Ionly need to deploy once and replace cheap client-side files often.At this stage I don't want to go back to the server to fixundiscovered bugs.

Suppressing LazyInitializationException is among the most knownproblems with Spring integration testing. But this is just a tip ofan iceberg. Here is a bit more complex example (it uses JPA again,but this problems manifests itself with plain JDBC and any otherpersistence technology as well):


@Test
public void externalThreadShouldSeeChangesMadeInMainThread() throws Exception {
  //given
  final Book someBook = findAnyExistingBook();
  someBook.setAuthor("Bruce Wayne");
  bookService.save(someBook);

  //when
  final Future<Book> future = executorService.submit(new Callable<Book>() {
    @Override
    public Book call() throws Exception {
      return bookService.findBy(someBook.id()).get();
    }
  });

  //then
  assertThat(future.get().getAuthor()).isEqualTo("Bruce Wayne");
}

In the first step we are loading some book from the database andmodifying the author, saving an entity afterwards. Then we load thesame entity by id in another thread. The entity is already saved soit is guaranteed that the thread should see the changes. This is notthe case however, which is proved by the failing assertion in thelast step. What happened?

Wehave just observed “I” in ACIDtransaction properties. Changes made by the test thread are notvisible to other threads/connections until the transaction iscommitted. But we know the test transaction commits! This smallshowcase demonstrates how hard it is to write multi-threadedintegration tests with transactional support. I learnt the hard wayfew weeks ago when I wanted to integration-test Quartzscheduler with JDBCJobStoreenabled. No matter how hard I tried the jobs were never fired. Itturned out that I was scheduling a job in Spring-managed test withinthe scope of a Spring transaction. Because the transaction was nevercommitted, the external scheduler and worker threads couldn't see thenew job record in the database. And how many hours have you spentdebugging such issues?

Talking about debugging, the same problem pop up whentrouble-shooting database-related test failures. I can add thissimple H2 web console (browse to localhost:8082) bean to my testconfiguration:


@Bean(initMethod = "start", destroyMethod = "stop")
def h2WebServer() = Server.createWebServer("-webDaemon", "-webAllowOthers")

But I will never see changes made by my test while stepping throughit. I cannot run the query manually to find out why it returns wrongresults. Also I cannot modify the data on-the-fly to have a fasterturn-around while trouble-shooting. My database lives in a differentdimension.

Please read the next test carefully, it's not long:


@Test
public void shouldNotSaveAndLoadChangesMadeToNotManagedEntity() throws Exception {
  //given
  final Book unManagedBook = findAnyExistingBook();
  unManagedBook.setAuthor("Clark Kent");

  //when
  final Book loadedBook = bookService.findBy(unManagedBook.id()).get();

  //then
  assertThat(loadedBook.getAuthor()).isNotEqualTo("Clark Kent");
}

Weare loading a book and modifying an author withoutexplicitly persisting it. Then we are loading it again from thedatabase and making sure that the change was notpersisted. Guess what, somehow we have updated the object!

Ifyou are experienced JPA/Hibernate user you know exactly how couldthat happen. Remember when I was describing attached/detachedentities above? When an entity is still attached to the underlyingEntityManager/session it has other powers as well. JPA provider isobligated to track the changes made to such entities andautomatically propagate them to the database when entity becomesdetached (so-called dirtychecking).

This means that an idiomatic way to work with JPA entitiesmodifications is to load an object from a database, perform necessarychanges using setters and... that's it. When the entity becomesdetached, JPA will discover it was modified and issue an UPDATE foryou. No merge()/update() needed, cute object abstraction. This worksas long as an entity is managed. Changes made to detached entity aresilently ignored because JPA provider knows nothing about suchentities. Now the best part – you almost never know if your entityis attached or not because transaction management is transparent andalmost invisible. This means that it is way too easy to only modifyPOJO instance in-memory while still believing that changes arepersistent and vice-versa!

Can we test it? Of course, we just did – and failed. In our testabove transaction spans across the whole test method, so every entityis managed. Also due to Hibernate L1 cache we get the exact same bookinstance back, even though no database update has been yet issued.This is another case where transactional tests are hiding problemsrather than revealing them (see LazyInitializationExceptionexample). Changes are propagated to the database as expected in thetest, but silently ignored after deployment...

BTWdid I mention that all tests so far are passing once you get rid of@Transactional annotation over test case class? Have a look, sourcesas always are available.

Thisone is exciting. I have a transactional deleteAndThrow(book) businessmethod that deletes given book and throws OppsException. Here is mytest that passes, proving the code is correct:


@Test
public void shouldDeleteEntityAndThrowAnException() throws Exception {
  //given
  final Book someBook = findAnyExistingBook();

  try {
    //when
    bookService.deleteAndThrow(someBook);
    fail();
  } catch (OppsException e) {
    //then
    final Option<Book> deletedBook = bookService.findBy(someBook.id());
    assertThat(deletedBook.isEmpty()).isTrue();
  }

}

TheScala's Option<Book>is returned (have you noticed how nicely Java code interacts withservices and and entities written in Scala?) instead of null.deletedBook.isEmpty() yielding true means that no result was found.So it seems like our code is correct: the entity was deleted and theexception thrown. Yes, you are correct, it fails silently afterdeployment again! This time Hibernate L1 cache knows that thisparticular instance of book was deleted so it returns null evenbefore flushing changes to the database. However OppsException thrownfrom the services rolls back the transaction, discarding DELETE! Butthe test passes, only because Spring manages this tiny extratransaction and the assertion happens within that transaction.Milliseconds later transaction rolls back, resurrecting deletedentity.

Obviouslythe solution was to add noRollbackFor attribute for OppsException(this is an actual bug I found in my code after droppingtransactional tests in favour to other solution which is yet to beexplained). But this is not the point. The point is – canyou really afford to write and maintain tests that are generatingfalse-positives, convincing you that your application is workingwhereas it's not?

Oh, and did I mention that transacational tests are actually leakinghere and there and won't prevent you from modifying the testdatabase? The second test fails, can you see why?


@Test
public void shouldStoreReviewInSecondThread() throws Exception {
  final Book someBook = findAnyExistingBook();

  executorService.submit(new Callable<Review>() {
    @Override
    public Review call() throws Exception {
      return reviewDao.save(new Review("Unicorn", "Excellent!!!1!", someBook));
    }
  }).get();
}

@Test
public void shouldNotSeeReviewStoredInPreviousTest() throws Exception {
  //given

  //when
  final Iterable<Review> reviews = reviewDao.findAll();

  //then
  assertThat(reviews).isEmpty();
}

Once again threading gets into the way. It gets even more interestingwhen you try to clean up after external transaction in backgroundthread that obviously was committed. The natural place would be todelete created Review in @After method. But @After is executed withinthe same test transaction, so the clean up will be... rolled back.

Of course I am not here to complain and grumble about my favouriteapplication stack weaknesses. I am here to give solutions and hints.Our goal is to get rid of transactional tests altogether and onlydepend on application transactions. This will help us to avoid allthe aforementioned problems. Obviously we cannot drop testindependence and repeatability features. Each test has to work on thesame database to be reliable. First, we will translate JUnit test toScalaTest. In order to have Spring dependency-injection support weneed this tiny trait:


trait SpringRule extends Suite with BeforeAndAfterAll { this: AbstractSuite =>

  override protected def beforeAll() {
    new TestContextManager(this.getClass).prepareTestInstance(this)
    super.beforeAll();
  }

}

Now it's about time to reveal my idea(if you are impatient, full sourcecode is here). It's far from being ingenious or unique, but Ithink it deserves some attention. Instead of running everything inone huge transaction and rolling it back, just let the tested code tostart and commit transactions wherever and whenever it needs and hasconfigured. This means that the data isactually written to the database and persistence works exactly thesame as it would after the deployment. Where's the catch? We mustsomehow clean up the mess after each test...

Turns out it's not that complicated. Just take a dump of a cleandatabase and import it after each test! The dump contains all thetables, constraints and records present right after the deploymentand application start-up but before the first test run. It's liketaking a backup and restoring from it! Look how simple it is with H2:


trait DbResetRule extends Suite with BeforeAndAfterEach with BeforeAndAfterAll { this: SpringRule =>

  @Resource val dataSource: DataSource = null

  val dbScriptFile = File.createTempFile(classOf[DbResetRule].getSimpleName + "-", ".sql")

  override protected def beforeAll() {
    new JdbcTemplate(dataSource).execute("SCRIPT NOPASSWORDS DROP TO '" + dbScriptFile.getPath + "'")
    dbScriptFile.deleteOnExit()
    super.beforeAll()
  }

  override protected def afterEach() {
    super.afterEach()
    new JdbcTemplate(dataSource).execute("RUNSCRIPT FROM '" + dbScriptFile.getPath + "'")

  }

}

trait DbResetSpringRule extends DbResetRule with SpringRule

TheSQL dump (see H2 SCRIPTcommand) is taken once and exported to temporary file. Then the SQLscript file is executed after each test. Believe it or not, that'sit! Our test is no longer transactional (so all Hibernate andmulti-threading corner-cases are discovered and tested) while wedidn't sacrifice the ease of transactional-tests setup (no extraclean up needed). Also I can finally look at the database contentswhile debugging! Here is one of the previous tests in action:


@RunWith(classOf[JUnitRunner])
@ContextConfiguration(classes = Array[Class[_]](classOf[SpringConfiguration]))
class BookServiceTest extends FunSuite with ShouldMatchers with BeforeAndAfterAll with DbResetSpringRule {

  @Resource
  val bookService: BookService = null

  private def findAnyExistingBook() = bookService.listBooks(new PageRequest(0, 1)).getContent.head

  test("should delete entity and throw an exception") {
    val someBook = findAnyExistingBook()

    intercept[OppsException] {
      bookService.deleteAndThrow(someBook)
    }

    bookService findBy someBook.id should be (None)
  }
}

Keep in mind that this is not a library/utility, but an idea. Foryour project you might choose slightly different approach and tools,but the general idea still applies: let your code run in the exactsame environment as after deployment and clean up the mess frombackup afterwards. You can achieve the exact same results with JUnit,HSQLDB or whatever you prefer. Of course you can add some cleveroptimizations as well – mark or discover tests that are notmodifying the database, choose faster dump, import approaches, etc.

To be honest, there are some downsides as well, here are a few fromtop of my head:

Performance. While it is not obvious that this approach is significantly slower than rolling back transactions all the time (some databases are particularly slow at rollbacks), it is safe to assume so. Of course in-memory databases might have some unexpected performance characteristics, but be prepared for a slowdown. However I haven't observed huge difference (maybe around 10%) per 100 tests in a small project.
Concurrency. You can no longer run tests concurrently. Changes made by one thread (test) are visible by others, making test execution unpredictable. This becomes even more painful with regards to aforementioned performance problems.

That would be it. If you are interested give this approach a chance.It may take some time to adopt your existing test base, butdiscovering even one hidden bug is worth it, don't you think? Andalso be aware of other springpitfalls.

Spring pitfalls: proxying

2011-10-29T11:10:00.000+02:00

Being a Spring framework user andenthusiast for many years I came across several misunderstandings andproblems with this stack. Also there are places where abstractionsleak terribly and to effectively and safely take advantage of all thefeatures developers need to be aware of them. That is why I amstarting a Spring pitfalls series. In the first part we willtake a closer look at how proxying works.

Bean proxying is an essential and oneof the most important infrastructure features provided by Spring. Itis so important and low-level that for most of the time we don't evenrealize that it exists. However transactions, aspect-orientedprogramming, advanced scoping, @Asyncsupport and various other domestic use-cases wouldn't be possiblewithout it. So what is proxying?

Here is an example: when you inject DAOinto service, Spring takes DAO instances and injects it directly.That's it. However sometimes Spring needs to be aware of each andevery call made by service (and any other bean) to DAO. For instanceif DAO is marked transactional it needs to start a transaction beforecall and commit or rolls back afterwards. Of course you can do thismanually, but this is tedious, error-prone and mixes concerns. That'swhy we use declarative transactions on the first place.

So how does Spring implement thisinterception mechanism? There are three methods from simplest to mostadvanced ones. I won't discuss their advantages and disadvantagesyet, we will see them soon on a concrete examples.

Java dynamic proxies

Simplest solution. If DAO implementsany interface, Spring will create a Java dynamicproxy implementing that interface(s) and inject it instead of thereal class. The real onestill exists and the proxy has reference to it, but to the outsideworld – the proxy is the bean. Now every time you call methods onyour DAO, Spring can intercept them, add some AOP magic and call theoriginal method.

CGLIB generatedclasses

The downside of Java dynamic proxies isa requirement on the bean to implement at least one interface. CGLIBworks around this limitation by dynamically subclassing the originalbean and adding interception logic directly by overriding everypossible method. Think of it as subclassing the original class andcalling super version amongst other things:


class DAO {
  def findBy(id: Int) = //...
}

class DAO$EnhancerByCGLIB extends DAO {
  override def findBy(id: Int) = {
    startTransaction
    try {
      val result = super.findBy(id)
      commitTransaction()
      result
    } catch {
      case e =>
        rollbackTransaction()
        throw e
    }
  }
}

However, this pseudocode does notillustrate howit works in reality – which introduces yet another problem, staytuned. BTW all examples will be in Scala, live with that and get usedto it.

AspectJ weaving

Thisis the most invasive but also the most reliable and intuitivesolution from the developer perspective. In this mode interception isapplied directly to your class bytecode which means the class yourJVM runs is not the same as the one you wrote. AspectJ weaver addsinterception logic by directly modifying your bytecode of your class,either during build – compiletime weaving(CTW)or when loading a class – loadtime weaving(LTW).

Ifyou are curious how AspectJ magic is implemented under the hood, hereis a decompiled and simplified .class file compiled with AspectJweaving beforehand:


public void inInterfaceTransactional()
{
  try
  {
    AnnotationTransactionAspect.aspectOf().ajc$before$1$2a73e96c(this, ajc$tjp_2);
    throwIfNotInTransaction();
  }
  catch(Throwable throwable)
  {
    AnnotationTransactionAspect.aspectOf().ajc$afterThrowing$2$2a73e96c(this, throwable);
    throw throwable;
  }
  AnnotationTransactionAspect.aspectOf().ajc$afterReturning$3$2a73e96c(this);
}

With load timeweaving the same transformation occurs at runtime, when the class isloaded. As you can see there is nothing disturbing here, in fact thisis exactly how you would program the transactions manually. Sidenote: do you remember the times when viruses were appending theircode into executable files or dynamically injecting themselves whenexecutable was loaded by the operating system?

Knowing proxytechniques is important to understand how proxying works and how itaffects your code. Let us stick with declarative transactiondemarcation example, here is our battlefield:


trait FooService {
  def inInterfaceTransactional()
  def inInterfaceNotTransactional();
}

@Service
class DefaultFooService extends FooService {

  private def throwIfNotInTransaction() {
    assume(TransactionSynchronizationManager.isActualTransactionActive)
  }

  def publicNotInInterfaceAndNotTransactional() {
    inInterfaceTransactional()
    publicNotInInterfaceButTransactional()
    privateMethod();
  }

  @Transactional
  def publicNotInInterfaceButTransactional() {
    throwIfNotInTransaction()
  }

  @Transactional
  private def privateMethod() {
    throwIfNotInTransaction()
  }

  @Transactional
  override def inInterfaceTransactional() {
    throwIfNotInTransaction()
  }

  override def inInterfaceNotTransactional() {
    inInterfaceTransactional()
    publicNotInInterfaceButTransactional()
    privateMethod();
  }
}

HandythrowIfNotInTransaction() method... throws exception when not invokedwithin a transaction. Who would have thought? This method is calledfrom various places and different configurations. If you examinecarefully how methods are invoked – this should all work. Howeverour developers' life tend to be brutal. First obstacle wasunexpected: ScalaTest does notsupport Spring integration testingvia dedicated runner. Luckily this can be easily ported with a simpletrait (handles dependency injection to test cases and applicationcontext caching):


trait SpringRule extends AbstractSuite { this: Suite =>

  abstract override def run(testName: Option[String], reporter: Reporter, stopper: Stopper, filter: Filter, configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker) {
    new TestContextManager(this.getClass).prepareTestInstance(this)
    super.run(testName, reporter, stopper, filter, configMap, distributor, tracker)
  }

}

Note that we arenot starting and rolling back transactions like the originaltesting framework. Not only because it would interfere with our demobut also because I find transactional tests harmful – but more onthat in the future. Back to our example, here is a smoke test. Thecomplete source code can be downloaded herefrom proxy-problembranch. Don't complain about the lack of assertions – here we areonly testing that exceptions are not thrown:


@RunWith(classOf[JUnitRunner])
@ContextConfiguration
class DefaultFooServiceTest extends FunSuite with ShouldMatchers with SpringRule{

  @Resource
  private val fooService: FooService = null

  test("calling method from interface should apply transactional aspect") {
    fooService.inInterfaceTransactional()
  }

  test("calling non-transactional method from interface should start transaction for all called methods") {
    fooService.inInterfaceNotTransactional()
  }

}

Surprisingly, thetest fails. Well, if you've been reading my articles for a while youshouldn't be surprised: SpringAOP riddle and SpringAOP riddle demystified. Actually, the Spring referencedocumentation explains this in greatdetail, also check out thisSO question. In short – non transactional method callstransactional one but bypassing the transactional proxy. Eventhough it seems obvious that when inInterfaceNotTransactional() callsinInterfaceTransactional() the transaction should start – it doesnot. The abstraction leaks. By the way also check out fascinatingTransaction strategies: Understanding transaction pitfalls article for more.

Remember ourexample showing how CGLIB works? Also knowing how polymorphism worksit seems like using class based proxies should help.inInterfaceNotTransactional() now calls inInterfaceTransactional()overriden by CGLIB/Spring, which in turns calls the original classes.Not a chance! This is the real implementation in pseudo-code:


class DAO$EnhancerByCGLIB extends DAO {

  val target: DAO = ...

  override def findBy(id: Int) = {
    startTransaction
    try {
      val result = target.findBy(id)
      commitTransaction()
      result
    } catch {
      case e =>
        rollbackTransaction()
        throw e
    }
  }
}

Instead ofsubclassing and instantiating subclassed bean Spring first createsthe original bean and then creates a subclass which wraps theoriginal one (somewhat Decoratorpattern) in one of the post processors. This means that – again –the self call inside bean bypasses AOP proxy around our class. Ofcourse using CGLIB changes how are bean behaves in few other ways.For instance we can now inject concrete class rather than aninterface, in fact the interface is not even needed and CGLIBproxying is required in this circumstances. There are also drawbacks– constructor injection is no longer possible, see SPR-3150,which is a shame.So what about some more thorough tests?


@RunWith(classOf[JUnitRunner])
@ContextConfiguration
class DefaultFooServiceTest extends FunSuite with ShouldMatchers with SpringRule {

  @Resource
  private val fooService: DefaultFooService = null

  test("calling method from interface should apply transactional aspect") {
    fooService.inInterfaceTransactional()
  }

  test("calling non-transactional method from interface should start transaction for all called methods") {
    fooService.inInterfaceNotTransactional()
  }

  test("calling transactional method not belonging to interface should start transaction for all called methods") {
    fooService.publicNotInInterfaceButTransactional()
  }

  test("calling non-transactional method not belonging to interface should start transaction for all called methods") {
    fooService.publicNotInInterfaceAndNotTransactional()
  }

}

Please pick teststhat will fail (pick exactly two). Can you explain why? Again commonsense would suggest that everything should pass, but that's not thecase. You can play around yourself, see class-based-proxybranch.

We are not here toexpose problems but to overcome them. Unfortunately our tangledservice class can only be fixed using heavy artillery – trueAspectJ weaving. Both compile- and load-time weaving makes the testpass. See aspectj-ctwand aspectj-ltwbranches accordingly.

You should now beasking yourself several question. Which approach should I take(or: do I really need to use AspectJ?) and why should Ieven bother? – amongst others. I would say – in most casessimple Spring proxying will suffice. But you absolutely have to beaware of how does the propagation work and when it doesn't. Otherwisebad things happen. Commits and rollbacks occurring in unexpectedplaces, spanning unexpected amount of data, ORM dirtychecking not working, invisible records – believe, this thingshappen on wild. And remember that topics we have covered here applyto all AOP aspects, not only transactions.

Logging exceptions root cause first

2011-09-23T22:43:00.000+02:00

The 0.9.30 releaseof Logback logging librarybrings new awesome feature: logging stack traces starting from root(innermost) exception rather than from the outermost one. Of coursemy excitement has nothing to do with the fact that Icontributed this feature...

To paraphrase Cecil B. de Mille: “The way to make a blog post isto begin with a stack trace and work up to a climax” - here itgoes:

The details aren't important yet, but from 100ft view you can seelong stack trace with several exceptions wrapping each other(causing). We'll go back tothis stack trace, but first some basics. If you throw an exception itwill be logged in a way showing how the stack was looking in themoment when the exception was from. At the very bottom you willeither see static main() or Thread.run() proceeded by methods invokedup to the first stack trace line indicating the place where theactual exception was thrown. This is very convenient since you cansee the whole control flow that resulted in the exception:


public class BookController {

  private final BookService bookService = new BookService();

  public void alpha() { beta(); }

  private void beta() { gamma(); }

  private void gamma() { bookService.delta(); }

  public static void main(String[] args) {
    new BookController().alpha();
  }
}

class BookService {

  private final BookDao bookDao = new BookDao();

  public void delta() { epsilon(); }

  private void epsilon() { zeta(); }

  private void zeta() { bookDao.eta(); }
}

class BookDao {

  public void eta() { theta(); }

  private void theta() { iota(); }

  public void iota() { throw new RuntimeException("Omega server not available"); }
}

If you don't know the Greekalphabet, you can start learning from the stack trace (remember,the control flow starts at the bottom and works its way up):


java.lang.RuntimeException: Omega server not available
  at BookDao.iota(BookController.java:50)
  at BookDao.theta(BookController.java:48)
  at BookDao.eta(BookController.java:46)
  at BookService.zeta(BookController.java:41)
  at BookService.epsilon(BookController.java:39)
  at BookService.delta(BookController.java:37)
  at BookController.gamma(BookController.java:22)
  at BookController.beta(BookController.java:20)
  at BookController.alpha(BookController.java:18)
  at BookController.main(BookController.java:26)

Wonderful, right? When readingfrom top to bottom you can say: iota() was called bytheta() was called by eta()...Clear and simple. However what if somebody decides to wrap theoriginal exception and re-throw it?


public class BookController {

  private static final Logger log = LoggerFactory.getLogger(BookController.class);

  private final BookService bookService = new BookService();

  public void alpha() { beta(); }

  private void beta() { gamma(); }

  private void gamma() {
    try {
      bookService.delta();
    } catch (Exception e) {
      throw new RuntimeException("Sorry, try again later", e);
    }
  }

  public static void main(String[] args) {
    try {
      new BookController().alpha();
    } catch (Exception e) {
      log.error("", e);
    }
  }
}

class BookService {

  private final BookDao bookDao = new BookDao();

  public void delta() { epsilon(); }

  private void epsilon() { zeta(); }

  private void zeta() {
    try {
      bookDao.eta();
    } catch (Exception e) {
      throw new RuntimeException("Unable to save order", e);
    }
  }
}

class BookDao {

  public void eta() { theta(); }

  private void theta() { iota(); }

  public void iota() {
    try {
      throw new RuntimeException("Omega server not available");
    } catch (Exception e) {
      throw new RuntimeException("Database problem", e);
    }
  }
}

Now quickly: find the root causein the stack trace!


java.lang.RuntimeException: Sorry, try again later
  at BookController.gamma(BookController.java:26)
  at BookController.beta(BookController.java:20)
  at BookController.alpha(BookController.java:18)
  at BookController.main(BookController.java:32)
Caused by: java.lang.RuntimeException: Unable to save order
  at BookService.zeta(BookController.java:51)
  at BookService.epsilon(BookController.java:45)
  at BookService.delta(BookController.java:43)
  at BookController.gamma(BookController.java:24)
  ... 8 common frames omitted
Caused by: java.lang.RuntimeException: Database problem
  at BookDao.iota(BookController.java:66)
  at BookDao.theta(BookController.java:60)
  at BookDao.eta(BookController.java:58)
  at BookService.zeta(BookController.java:49)
  ... 11 common frames omitted
Caused by: java.lang.RuntimeException: Omega server not available
  at BookDao.iota(BookController.java:64)
  ... 14 common frames omitted

Turns out that main() is nolonger the last line. Even worse, everything seems garbled, try toread the Greek alphabet again... Now let's go back to our originalstack trace. It comes from Spring framework startup failure, imagineit can be several pages long.

For you convenience I addedarrows to mark you the path you should follow to reconstruct thecontrol flow: starting from the red arrow's tail (Thread.run())somewhere in the middle you go up and then... jump to the tail oforange arrow. From the head of the orange arrow you jump to the tailof the green one and so on... Not very intuitive, don't you think?And what is this red ellipse showing? Yes, it is the root cause ofthe failure (the innermost exception). On the other hand theexception printed at the very beginning (the one you typically readon the first place) says something about an error creatingDefaultAnnotationHandlerMapping#0 (what?) The true error (No matchingbean of type...) is cleverly hidden...

So what is this newfeature all about? Again our simple example. After upgrading to0.9.30 just add %rEx(or equivalent %rootException) at the end of your logging pattern:

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%d %level %m%n%rEx</pattern>
  </encoder>
</appender>

This will replace the defaultstack trace printing routing with the one I humbly contributed. Thesame Greek program will now print:


java.lang.RuntimeException: Omega server not available
  at BookDao.iota(BookController.java:64)
Wrapped by: java.lang.RuntimeException: Database problem
  at BookDao.iota(BookController.java:66)
  at BookDao.theta(BookController.java:60)
  at BookDao.eta(BookController.java:58)
  at BookService.zeta(BookController.java:49)
Wrapped by: java.lang.RuntimeException: Unable to save order
  at BookService.zeta(BookController.java:51)
  at BookService.epsilon(BookController.java:45)
  at BookService.delta(BookController.java:43)
  at BookController.gamma(BookController.java:24)
Wrapped by: java.lang.RuntimeException: Sorry, try again later
  at BookController.gamma(BookController.java:26)
  at BookController.beta(BookController.java:20)
  at BookController.alpha(BookController.java:18)
  at BookController.main(BookController.java:32)

Please compare it carefully with the previous output. First ofall, the very first line points to the problem. No digging in the“Caused by” exceptions, most of the time you will probably skipthe rest. Secondly, the control flow is uninterrupted and continuous– you can still read it from top to bottom or vice-versa. And lastbut not least – the fact that exceptions were wrapped in themeantime is preserved but does not garble the stack trace.

Now you deserve to see the original Spring exception takingadvantage of %rEx printing:

The observations are exactly the same: root cause of the problemappears at the very beginning, shortening the time the problem needsto be investigated. Also when analysing the control flow there is notjumping – Thread.main() is at the bottom and you can read the tracefrom bottom to top continuously.

If you “work” a lot with stack traces (either in developmentor in production/support) – consider switching to root cause firstlogging. It will save you few seconds every time you analyseparticular exception. But I also noticed inexperienced developerssometimes aren't even aware of “Caused by” rule: find firstexception and look at the last Caused by – remaining clueless whatthe problem is, looking only at the outermost, least specific, mostgeneric error. This will help them as well.

By the way – all this hustle can be avoided if you avoidwrapping and re-throwing exception altogether. I know, all too oftenwe are forced to do so by checked exceptions...

The evolution of Spring dependency injection techniques

2011-09-01T22:01:00.000+02:00

Looking back at the history of Springframework you will find out that the number of ways you can implementdependency injection is growing in every release. If you've beenworking with this framework for more than a month you'll probablyfind nothing interesting in this retrospective article. Nothinghopefully except the last example in Scala, language thataccidentally works great with Spring.

First there was XML [fullsource]:


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

    <bean id="foo" class="com.blogspot.nurkiewicz.Foo">
        <property name="bar" ref="bar"/>
        <property name="jdbcOperations" ref="jdbcTemplate"/>
    </bean>

    <bean id="bar" class="com.blogspot.nurkiewicz.Bar" init-method="init"/>

    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="org.h2.Driver"/>
        <property name="url" value="jdbc:h2:mem:"/>
        <property name="username" value="sa"/>
    </bean>

    <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
        <constructor-arg ref="dataSource"/>
    </bean>
</beans>

This simple application only fetches H2database server time and prints it with full formatting:


public class Foo {

    private Bar bar;

    private JdbcOperations jdbcOperations;

    public String serverTime() {
        return bar.format(
                jdbcOperations.queryForObject("SELECT now()", Date.class)
        );
    }

    public void setBar(Bar bar) {
        this.bar = bar;
    }

    public void setJdbcOperations(JdbcOperations jdbcOperations) {
        this.jdbcOperations = jdbcOperations;
    }
}


public class Bar {

    private FastDateFormat dateFormat;

    public void init() {
        dateFormat = FastDateFormat.getDateTimeInstance(FULL, FULL);
    }

    public String format(Date date) {
        return dateFormat.format(date);
    }
}

There is something disturbing aboutthis code. First of all there is surprisingly a lot of XML. It isstill less compared to similar EJB 2.1 application (with minorchanges this code runs on Spring 1.2.6 dating back to 2006), butit just feels wrong. The public setters are even more disturbing –why are we forced to expose the ability to override objectdependencies at any time and by anyone? By the way I never reallyunderstood why Spring does not allow injecting dependencies directlyto private fields when <property> tag is used since it ispossible with...

Annotations [fullsource]

Java 5 and Spring 2.5 brought supportfor annotation-driven dependency injection:


<context:annotation-config/>

<!-- or even: -->

<context:component-scan base-package="com.blogspot.nurkiewicz"/>

Take the first line and you no longerhave to define <property> tags in your XML, only <bean>s.The framework will pick up standard @Resource annotations. Replace itwith the second line and you don't even have to specify beans in yourXML at all:


@Service
public class Foo {

    @Resource
    private Bar bar;

    @Resource
    private JdbcOperations jdbcOperations;

    public String serverTime() {
        return bar.format(
                jdbcOperations.queryForObject("SELECT now()", Date.class)
        );
    }
}


@Service
public class Bar {

    private FastDateFormat dateFormat;

    @PostConstruct
    public void init() {
        dateFormat = FastDateFormat.getDateTimeInstance(FULL, FULL);
    }

    public String format(Date date) {
        return dateFormat.format(date);
    }
}

Of course you are not impressed! Nihilnovi. Also we still have to live with XML because we have nocontrol over 3rd party classes (like data source and JdbcTemplate),hence we can't annotate them. But Spring 3.0 introduced:

@Configuration [fullsource]

I've been already exploring the@Configuration/@Beansupport, so this time please focus on how we start the applicationcontext. Do you see any reference to the XML file? TheapplicationContext.xml descriptor is gone completely:


@ComponentScan("com.blogspot.nurkiewicz")
public class Bootstrap {

    private static final Logger log = LoggerFactory.getLogger(Bootstrap.class);

    @Bean
    public DataSource dataSource() {
        final BasicDataSource dataSource = new BasicDataSource();
        dataSource.setDriverClassName("org.h2.Driver");
        dataSource.setUrl("jdbc:h2:mem:");
        dataSource.setUsername("sa");
        return dataSource;
    }

    @Bean
    public JdbcTemplate jdbcTemplate() {
        return new JdbcTemplate(dataSource());
    }

    public static void main(String[] args) {
        final AbstractApplicationContext applicationContext = new AnnotationConfigApplicationContext(Bootstrap.class);
        final Foo foo = applicationContext.getBean(Foo.class);

        log.info(foo.serverTime());

        applicationContext.close();
    }
}

As you can see Spring came quite a longroad from XML-heavy to XML-free framework. But the most exciting partis that you can you use whichever style you prefer or even mix them.You can take legacy Spring application and start using annotations orswitch to XML for god knows what reasons here or there.

One technique I haven't mentioned isconstructor injection. It has some great benefits (see DependencyInjection with constructors?), like ability to markdependencies as final and forbidding to create uninitialized objects:


@Service
public class Foo {

    private final Bar bar;

    private final JdbcOperations jdbcOperations;

    @Autowired
    public Foo(Bar bar, JdbcOperations jdbcOperations) {
        this.bar = bar;
        this.jdbcOperations = jdbcOperations;
    }

    //...

}

I would love constructor injection,however once again I feel a bit disappointed. Each and every objectdependency requires (a) constructor parameter, (b) final field and(c) assignment operation in constructor. We end up with ten lines ofcode that don't do anything yet. This chatty code overcomes all theadvantages. Of course no object should have more than (put yournumber here) dependencies – and thanks to constructor injectionyou immediately see that theobject has too many – but still I find this code introducing toomuch ceremony.

Spring constructor injection with Scala [fullsource]

One feature of Scala fits perfectly into Spring framework: eachargument of any Scala object by default creates final field named thesame as this argument. What does this mean in our case? Look at Fooclass translated to Scala:


@Service
class Foo @Autowired() (bar: Bar, jdbcOperations: JdbcOperations) {

    def serverTime() = bar.format(jdbcOperations.queryForObject("SELECT now()", classOf[Date]))

}

Seriously?But... how? Before we dive into advantages of Scala here, look at theequivalent Java code as generated by Java decompiler:


@Service
public class Foo implements ScalaObject
{
    private final Bar bar;
    private final JdbcOperations jdbcOperations;

    @Autowired
    public Foo(Bar bar, JdbcOperations jdbcOperations)
    {
        this.bar = bar;
        this.jdbcOperations = jdbcOperations;
    }

    public String serverTime()
    {
        return this.bar.format(this.jdbcOperations.queryForObject("SELECT now()", Date.class));
    }

}

Almost exactly the same code as wewould have written in Java. With all the advantages: dependencies arefinal making our services truly immutable and stateless; dependenciesare private and not exposed to the outside world; literally no extracode to manage dependencies: just add constructor argument, Scalawill take care of the rest.

To wrap things up – you have a widerange of possibilities. From XML, through Java code to Scala. Thelast approach is actually very tempting as it saves you from all theboilerplate and allows you to focus on business functionality. Thefull source codeis available under my GitHub repository, each step is tagged so youcan compare and choose whichever approach you like the most.

What features of Java have been dropped in Scala?

2011-08-07T18:15:00.002+02:00

Despite more complex and less intuitive syntax compared to Java, Scala actually drops several features of Java, sometimes for good, other times providing replacements on the standard library level. As you will see soon, Scala isn't a superset of Java (like Groovy) and actually removes a lot of noise. Below is a catalogue of the missing features.

break and continue in loops

Every time I see code like this:


while(cond1) {
    work();
    if(cond2)
        continue;
    rest();
}

I feel as if it has been written by a guy who truly misses the times when goto wasn't yet considered harmful. Hands up who finds this version more readable:


while(cond1) {
    work();
    if(!cond2)
        rest();
}

Getting rid of break requires a little more though, but generally extracting a loop to a separate method/function (or at least putting it at the end of existing method) and using return instead will do the trick. By the why Scala allows you to define functions inside other functions, so you won't pollute your global class namespace with plenty of small methods used only once – problem that sometimes arises when religiously extracting methods in Java.

break and continue – we thank you in the name of our fathers and grandfathers for your contribution to imperative programming. But we no longer need you and we won't miss you.

Arrays

It's amazing how many bad habits have we learnt by all these years and how we got used to idioms that are inconsistent and simply painful. You have covariant arrays in Java with square brackets syntax, length final property and ability to store primitive types. You also have Java collections framework with List&lt;T&gt; abstraction – that is not covariant, uses get() and size() methods and can't store primitives. The list of differences does not end here, however isn't every array just a special case of List? Why do we have a special syntax for arrays in the language while collections are implemented in on top of the language? And isn't a bit irritating to convert them from one to another all the time?


String[] array = new String[10];
List<String> list = Arrays.asList(array);
String[] array2 = list.toArray(new String[list.size()]);

Converting from collection to array is my favourite Java idiom... Why not just have same syntax, same methods, same abstraction, polymorphic behaviour – and only different implementation names?


val array = Array("ab", "c", "def")
println(array(1))
array filter (_.size > 1)

val list = List("ab", "c", "def")
println(list(1))
println(list filter (_.size > 1))

And don't worry, behind the scenes Scala compiler will use the same efficient array bytecode as if you were using plain arrays in Java. No magic abstractions and several layers of wrapping.

Primitives

Another weird Java inconsistency – why do we have a choice between primitive int and wrapping Integer? If the variable is of Integer type does this mean it is optional (null), or is it just that you can't use primitives in collections (but can in arrays, as pointed out above)? Is this unboxing safe (also known as: how on earth this can throw NullPointerException?) Can I compare these to integers using == operator? And can I simply call toString() to get string representation of this number?

In Scala you no longer have a choice, every primitive type is an object, while most of the time still being a primitive in memory and in bytecode. How is that possible? Have a look at the following popular example:


val x = 37     //x and y are objects of type Int
val y = 5
val z = x + y  //x.+(y) - yes, Int class has a "+" method
assert(z.toString == "42")

x, y and z are instances of type Int. They are all objects, even adding two integers is semantically a method + called on x with y argument. If you think it has to perform terribly – once again behind the scenes it is compiled into ordinary primitive addition. But now you can easily use primitives in collections, pass them when any type is required (Object in Java, Any in Scala) or simply create a text representation without awkward Integer.toString(7) idiom. Sooo many bad habits.

Checked exceptions

Another feature that I can hardly miss. Not much to be said here. Neither any mainstream language except Java have them, nor any mainstream JVM language (except Java). This topic is still relatively controversial, however if you've ever tried to deal with ubiquitous SQLException or IOException, you know how much boilerplate it introduces without good reason. Anyway, look at the next examples...

Interfaces

This one is good! Scala doesn't have interfaces. Instead it introduces traits – something in between abstract classes (some trait methods might have implementation) and interfaces (one can mix in more than one trait). So essentially traits enables you to implement multiple inheritance while avoiding dreadful diamond problem. How it is done requires an article on its own (in short: last trait wins), but I would rather show you an example how helpful traits are to reduce duplication.

Suppose you are writing an interface to abstract binary protocol. Most implementations take raw byte array, so in Java you would simply say:


public interface Marshaller {
    long send(byte[] content);
}

This is great from the implementation perspective – just implement a single method and the abstraction is ready. However users of the interface are complaining that it is cumbersome and not very convenient. They would like to send strings, binary and text streams, serialized objects and so on. They can either create a facade around this interface (and every user will create his/hers very own with a distinct set of bugs) or force the author of the API to extend it:


public interface Marshaller {

    long send(byte[] content);

    long send(InputStream stream);
 
    long send(Reader reader);
 
    long send(String s);

    long send(Serializable obj);

}

Now the API is a breeze, however every implementation has to implement five methods instead of one. Also note that since most abstracted protocols are based on byte arrays, all the methods can be implemented in terms of the first one. And only the first one contains the actual marshalling code. This in turns causes every implementation to have the exact same four methods – duplication didn't go away – it has just been moved. Actually this problem is known as a thin vs. rich interface and it has been described in great Programming in Scala book.
What I was typically doing was to give service providers an abstract class with typical implementations of all the methods except the root one, which was used by all other methods:


import org.apache.commons.io.IOUtils;

public abstract class MarshallerSupport implements Marshaller {

    @Override
    public abstract long send(byte[] content);

    @Override
    public long send(InputStream stream) {
        try {
            return send(IOUtils.toByteArray(stream));
        } catch (IOException e) {
            throw new RuntimeException(e);  //choose something more specific in real life
        }
    }

    @Override
    public long send(Reader reader) {
        try {
            return send(IOUtils.toByteArray(reader));
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public long send(String s) {
        try {
            return send(s.getBytes("UTF8"));
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public long send(Serializable obj) {
        try {
            final ByteArrayOutputStream bytes = new ByteArrayOutputStream();
            new ObjectOutputStream(bytes).writeObject(obj);
            return send(bytes.toByteArray());
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }

}

Now everyone is happy – instead of copying all the overloaded methods over and over, just subclass the MarshallerSupport and implement what you need. But what if your interface implementation also has to subclass some other class? You are out of luck then. In Scala however you change the interface to trait, opening the possibility to mix in (think something between extending and implementing) several other traits. By the way do you remember what I said about checked exceptions?


trait MarshallerSupport extends Marshaller {

    def send(content: Array[Byte]): Long

    def send(stream: InputStream): Long = send(IOUtils.toByteArray(stream))

    def send(reader: Reader): Long = send(IOUtils.toByteArray(reader))

    def send(s: String): Long = send(s.getBytes("UTF8"))

    def send(obj: Serializable): Long = {
        val bytes = new ByteArrayOutputStream
        new ObjectOutputStream(bytes).writeObject(obj)
        send(bytes.toByteArray)
    }
}

Switch statement

There is no switch statement in Scala. Calling pattern matching a better switch would be a blasphemy. Not only because pattern matching in Scala is an expression returning a value and also not because you can switch over literally any value if you want. Not even because there is no fall-through, break and default. It's because Scala's pattern matching enables you to match whole object structures and lists, even with wildcards. Consider this expression simplification method, originally taken from already mentioned Programming in Scala book:


abstract class Expr
case class Var(name: String) extends Expr
case class Number(num: Double) extends Expr
case class UnOp(operator: String, arg: Expr) extends Expr
case class BinOp(operator: String, left: Expr, right: Expr) extends Expr

//...

def simplify(expr: Expr): Expr = expr match {
    case UnOp("-", UnOp("-", e)) => e  //double negation
    case BinOp("+", e, Number(0)) => e //adding zero
    case BinOp("*", e, Number(1)) => e //multiplying by one
    case _ => expr
}

Look carefully how clever this code is! If our expression is unary “-” operation and the argument is a second unary “-” operation with any expression e as an argument (think: -(-e)), then simply return e. If you find this pattern matching example hard to read, check out the roughly equivalent Java code. However please remember: size doesn't matter (one could probably do the same with Perl one-liner) – it's about readability and maintainability:


public Expr simplify(Expr expr) {
    if (expr instanceof UnOp) {
        UnOp unOp = (UnOp) expr;
        if (unOp.getOperator().equals("-")) {
            if (unOp.getArg() instanceof UnOp) {
                UnOp arg = (UnOp) unOp.getArg();
                if (arg.getOperator().equals("-"))
                    return arg.getArg();
            }
        }
    }
    if (expr instanceof BinOp) {
        BinOp binOp = (BinOp) expr;
        if (binOp.getRight() instanceof Number) {
            Number arg = (Number) binOp.getRight();
            if (binOp.getOperator().equals("+") && arg.getNum() == 0 ||
                    binOp.getOperator().equals("*") && arg.getNum() == 1)
                return binOp.getLeft();
        }
    }
    return expr;
}

UPDATE:In one of the comments Yassine Elouaficlaims this example is too limited as it can not simplify nestedexpressions like: BinOp("+", Var("x"), BinOp("*",Var("y"), Number(0))) which reads: x + y * 0. Indeed thisalgorithm assumes nested terms are already simplified. But it shouldbe pretty obvious to improve this code to work with arbitrary complexexpressions – without loosing readability. Recursion with bottom-upapproach seems perfect: simplify the leaves first (simplest terms)and go up. Here is the improved code:


def simplify(expr: Expr): Expr = expr match {
    case UnOp("-", UnOp("-", e)) => simplify(e)
    case BinOp("+", e, Number(0)) => simplify(e)
    case b@BinOp("+", _, _) => simplify(BinOp(b.operator, simplify(b.left), simplify(b.right)))
    case BinOp("*", e, Number(1)) => simplify(e)
    case BinOp("*", e, Number(0)) => Number(0)
    case _ => expr
}

Not that bad, don't you think? Ofcourse there are still several improvements that might be applied (0+ e, 1 * e, operations on constants, etc.), but thanks to the powerof recursion the results are already quite impressive:


//x + y * 0
assert(simplify(BinOp("+", Var("x"), BinOp("*", Var("y"), Number(0)))) === Var("x"))

//(x + y) * 0
assert(simplify(BinOp("*", BinOp("+", Var("x"), Var("y")), Number(0))) === Number(0.0))

//-(-(-(-5)))
assert(simplify(UnOp("-", UnOp("-", UnOp("-", UnOp("-", Number(5)))))) === Number(5.0))

//y * 1 + (x + z) * 0
assert(
    simplify(
        BinOp(
            "+",
            BinOp(
                "*",
                Var("y"),
                Number(1)
            ),
            BinOp(
                "*",
                BinOp(
                    "+",
                    Var("x"),
                    Var("z")
                ),
                Number(0)
            )
        )
    ) === Var("y")
)

So isScala scalable?

instanceof/casting

As with many other features, Scala does not have a built-in syntax for instanceof and downcasting. Instead the language provides you methods on actual objects:


val b: Boolean = expr.isInstanceOf[UnOp]
val unOp: UnOp = expr.asInstanceOf[UnOp]

In Scala a lot of features normally considered as part of the language are actually implemented in the language itself or at least they don't require a special syntax. I like this idea, in fact I find Ruby's way of creating objects (Foo.new – method instead of new operator) very attractive and even unusual lack of if conditionals in Smalltalk requires some attention.

Enums

Scala doesn't have built-in support for enums. Enumerations in Java are known to have several fancy features which other languages envy like type safety and ability to add methods to each enum. There are at least two ways to emulate enums in Scala:


object Status extends Enumeration {
   type Status = Value

   val Pending = Value("Pending...")
   val Accepted = Value("Accepted :-)")
   val Rejected = Value("Rejected :-(")
}

assume(Status.Pending.toString == "Pending...")
assume(Status.withName("Rejected :-(") == Status.Rejected)

Or if you don't care about textual enum representation:


object Status extends Enumeration {
   type Status = Value

   val Pending, Accepted, Rejected = Value
}

However the second and the most comprehensive way to emulate enums is to use case classes. Side note: name is actually an abstract method defined in base class. When you declare a method without defining the method body it is implicitly assumed to be abstract – no need to mark the obvious with extra keywords:


sealed abstract class Status(val code: Int) {
 def name: String
}

case object Pending extends Status(0) {
 override def name = "?"
}

case object Accepted extends Status(1) {
 override def name = "+"
}

case object Rejected extends Status(-1) {
 override def name = "-"
}

//...

val s: Status = Accepted

assume(s.name == "+")
assume(s.code == 1)

s match {
    case Pending =>
    case Accepted =>
    case Rejected =>  //comment this line, you'll see compiler warning
}

This approach, although has nothing to do with enums per se, has many advantages. The biggest one is that the compiler will warn you when performing non exhaustive pattern matching – think: switch over an enum in Java without explicitly referencing each and every value or default block.

Static methods/fields

Scala doesn't have a notion of static fields and methods. Instead it has a feature named objects as opposed to classes. When you define a class using object keyword, Scala runtime will eagerly create one instance of this class and make it available under class name. This is essentially a singleton pattern built into the language but the most important is the mindset shift introduced by this approach. Instead of a bunch of static functions artificially gathered together inside a class (which is only a de facto namespace in this case) you have a singleton with true methods:


sealed abstract class Status
case object Pending extends Status
case object Accepted extends Status
case object Rejected extends Status

case class Application(status: Status, name: String)

object Util {

    def groupByStatus(applications: Seq[Application]) = applications groupBy {_.status}

}

Here is how the syntax works (and nice ScalaTest DSL example):


@RunWith(classOf[JUnitRunner])
class UtilTest extends FunSuite with ShouldMatchers {

   type ? = this.type

   test("should group applications by status") {
      val applications = List(
         Application(Pending, "Lorem"),
         Application(Accepted, "ipsum"),
         Application(Accepted, "dolor")
      )

      val appsPerStatus = Util.groupByStatus(applications)

      appsPerStatus should have size (2)
      appsPerStatus(Pending) should (
            have size (1) and
            contain (Application(Pending, "Lorem"))
      )
      appsPerStatus(Accepted) should (
            have size (2) and
            contain (Application(Accepted, "ipsum")) and
            contain (Application(Accepted, "dolor"))
      )
   }
}

volatile/transient/native and serialVersionUID are gone

The language designers decided to convert the first three keywords into annotations. Both approaches have pros and cons, hard to find the clear winner. However turning serialVersionUID into a class level annotation is a pretty good choice. I know this field existed long before annotations were introduced to the Java language, so we shouldn't blame it. But I always hated when in statically typed languages some names/fields have special meaning not reflected anywhere except the language specification itself (magic numbers?) Unfortunately there are examples of this unpleasant behaviour in Scala as well, namely special treatment of apply() method and methods ending with colon. Too bad.

Pre/post-increment

You cannot do i++ and ++i in Scala. Period. You need a bit more verbose i += 1 – and to make matters worse this expression return Unit (think: void). How can we deal with this noticeable feature missing? Turns out that very often this type of constructs are imperative style legacy and they can easily be avoided by using more functional and pure constructs. Take the following problem as an example:

You have two same sized arrays: one with names and a second one with ages. Now you want to display each name with a corresponding age – somehow iterating over both arrays in parallel. In Java this is surprisingly tough to implement cleanly:


String[] names = new String[]{"Alice", "Bobby", "Eve", "Jane"};
Integer[] ages = new Integer[]{27, 31, 29, 25};

int curAgeIdx = 0;
for (String name : names) {
    System.out.println(name + ": " + ages[curAgeIdx]);
    ++curAgeIdx;
}

//or:

for(int idx = 0; idx < names.length; ++idx)
    System.out.println(names[idx] + ": " + ages[idx]);
}

In Scala maybe it is shorter, but very mysterious at first:


var names = Array("Alice", "Bobby", "Eve", "Jane")
var ages = Array(27, 31, 29, 25)

names zip ages foreach {p => println(p._1 + ": " + p._2)}

zip? I encourage you play a bit with this example. If you don't feel like starting up the whole IDE, try it with Scala REPL:


$ scala
scala> Array("one", "two", "three") zip Array(1, 2, 31)   
res1: Array[(java.lang.String, Int)] = Array((one,1), (two,2), (three,31))

Look carefully, do you see the result array containing pairs of corresponding elements from the first and the second arrays “zipped” together? One simple experiment and now suddenly it should be clear and much more readable than ordinary imperative solution.

Scala inventors looked very thoroughly on Java language and they didn't just add syntactic sugar (like function literals or implicit conversions). They discovered plenty of inconsistencies and annoyances in Java, getting rid of them and providing more concise and deliberate replacements. Despite higher level constructs like primitive and array objects, under the hood the same fast and straightforward bytecode is generated.

EJB 3.1 Cookbook by Richard Reese review

2011-07-21T21:15:00.002+02:00

Recently I received a copy of EJB 3.1 Cookbook (courtesy to Packt Publishing) with a kind request to prepare a review. And since I have just got my new Kindle reader, this was a great opportunity to test them together.

EJB3.1 Cookbook by Richard Reese aims to provide “a collectionof simple but incredibly effective recipes” – quoting thesubtitle. The book covers expected part of the EJB stack: session andmessage-driven beans, JPA, security, interceptors, timer service andweb services. Contents are

organized around so called recipes – short (no more than three pages long) micro-chapters focused on one specific issue. This is the most advantageous feature of this publication: all recipes all self-contained most of the time, so one can jump between them and apply the most suitable in given scenario. This makes the book suitable for both the beginners, which should read it from cover to cover and slightly more experienced developers. However the latter ones will probably prefer more comprehensive sources and skip significant parts of the book.

Although I found the book structure very convenient, contents (both granularity and volume) are highly subjective and controversial. On the one hand the author devotes five recipes to describe separately each JMS message type (string, byte, stream, map and object) – each one is almost identical. Whilst he could only list different types, he fills half of the JMS chapter this way (sic!) On the other hand, there is only one recipe explaining new JPA 2.0 Criteria API – to make matters worse, only using weakly typed queries. Probably one of the most important new features in EJB 3.1 stack has been covered on two pages. And this API is not particularly easy to grasp. To depict you the scale – the art of adding Bean Validation annotations (@NotNull etc.) on fields required ten pages and eight recipes... Where a half-page bullet-list would suffice.

The last chapter – EJB Techniques – is very intriguing. Lots of valuable and accurate tips have been given, like the difference between Date and Calendar, logging and dealing with exceptions, effective String manipulations. Despite appearances, this is not the basic Java knowledge and many experienced programmers still don't know that SimpleDateFormat is not thread-safe and that Date class does not store time zone. I am really happy that this kind of knowledge found its way in the book. Unfortunately – in the wrong one. That being said, there are more appropriate books, not focused on EJB or even Java EE. Here it just looks like putting anything useful to reach dozen chapters in total.

There are however bright sides as well. I particularly enjoyed Transaction Processing and Interceptors chapters. In the former one the author briefly but succinctly explains different transaction propagation and error handling behaviours, very important topics. Table on page 210 captures the essence of transaction demarcation in few simple rules, brilliant in its simplicity. In the interceptors chapter the recipes are focused on typical cross-cutting concerns, forming handy starting point. Also pretty informative.

When in comes to code examples and use-cases, they were generally interesting and well thought. Nevertheless, I am still awfully confused after reading a recipe on @Singleton: “We will assume that our game will never have more than one player so a singleton is an appropriate choice ” - says the author to justify the usage of singleton to store user attributes. Yes, I think we are all using Enterprise Java Beans and Application Servers to develop systems that would never have more than one user at a time... (Hint: statefull session bean) The same thing with the usage of Facade pattern throughout the book. First the author quotes the exact definition of this design pattern and then names a class wrapping EntityManager and providing convenient, strongly typed create(), remove(), findAll(), etc. - PatientFacade. No, this class is not hiding the complexity of Patient entity, and all programmers all over the world would call this abstraction a Repository or DAO. Not here.

By the way in the same recipe one-to-many relationship is introduced between a patient and medication, where clearly many-to-many is required. Curiously enough, in the next recipe DISTINCT SQL statement is used to filter out duplications that have appeared due to denormalization. Well, if the database was designed properly, there wouldn't be any duplicates on the first place... After all these misleading and sometimes harmful advices, typos and errors in source codes (ClassNoDefException? - never heard of it...) are not that irritating.

In conclusion, despite all the deficiencies and inconsistencies, I mostly enjoyed reading this book. Once again I will highlight the very elegant chapter-recipe structure and the fixed layout inside each recipe. I believe it is suitable for people that suddenly inherited an EJB application and need an immediate help and suggestions. However on the long run, they should invest in more comprehensive publication. Few years back I managed to pass SCBCD exam (EJB 3.0 by that time) after reading Enterprise JavaBeans 3.0. With the book in question it would be virtually impossible. If you need a quick and dirty, yet entertaining source of ready solutions, go ahead. Otherwise, definitely look for something broader and less verbose.

Poor man's CRUD: jqGrid, REST, AJAX, and Spring MVC in one house

2011-07-03T19:15:00.001+02:00

More than two years back I wrote an article on how two implement elegant CRUD in Struts2. Actually I had to devote two articles on that subject because the topic was so broad. Today I have taken much more lightweight and modern approach with a set of popular and well established frameworks and libraries. Namely, we will use Spring MVC on the back-end to provide REST interface to our resources, fabulous jqGrid plugin for jQuery to render tabular grids (and much more!) and we will wire up everything with a pinch of JavaScript and AJAX.

Back-end is actually the least interesting part of this showcase, it could have been implemented using any server-side technology capable of handling RESTful requests, probably JAX-RS should now be considered standard in this field. I have chosen Spring MVC without any good reason, but it's also not a bad choice for this task. We will expose CRUD operations over REST interface; the list of best selling books in history will be our domain model (can you guess who is on the podium?)


@Controller
@RequestMapping(value = "/book")
public class BookController {

  private final Map<Integer, Book> books = new ConcurrentSkipListMap<Integer, Book>();

  @RequestMapping(value = "/{id}", method = GET)
  public @ResponseBody Book read(@PathVariable("id") int id) {
    return books.get(id);
  }

  @RequestMapping(method = GET)
  public @ResponseBody Page<Book> listBooks(
      @RequestParam(value = "page", required = false, defaultValue = "1") int page,
      @RequestParam(value = "max", required = false, defaultValue = "20") int max) {
    final ArrayList<Book> booksList = new ArrayList<Book>(books.values());
    final int startIdx = (page - 1) * max;
    final int endIdx = Math.min(startIdx + max, books.size());
    return new Page<Book>(booksList.subList(startIdx, endIdx), page, max, books.size());
  }
}

Few things need explanation. First of all for the purposes of this simple showcase I haven't used any database, all the books are stored in an in-memory map inside a controller. Forgive me. Second issue is more subtle. Since there seems to be no agreement on how to handle paging with RESTful web services, I used simple query parameters. You may find it ugly, but I find abusing Accept-Ranges and Range headers together with 206 HTTP response code even uglier.

Last notable detail is the Page<Book> wrapper class:


@XmlRootElement
public class Page<T> {

  private List<T> rows;

  private int page;
  private int max;
  private int total;

  //...

}

I could have return raw list (or, more precisely, requested part of the list), but I also need a way to provide convenient metadata like total number of records to the view layer, not to mention some difficulties while marshalling/unmarshalling raw lists.

We are now ready to start our application and do a little test drive with curl:


<!-- $ curl -v "http://localhost:8080/books/rest/book?page=1&max=2" -->

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page>
  <total>43</total>
  <page>1</page>
  <max>3</max>
  <rows xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="book">
    <author>Charles Dickens</author>
    <available>true</available>
    <cover>PAPERBACK</cover>
    <id>1</id>
    <publishedYear>1859</publishedYear>
    <title>A Tale of Two Cities</title>
  </rows>
  <rows xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="book">
    <author>J. R. R. Tolkien</author>
    <available>true</available>
    <cover>HARDCOVER</cover>
    <id>2</id>
    <publishedYear>1954</publishedYear>
    <title>The Lord of the Rings</title>
  </rows>
  <rows xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="book">
    <author>J. R. R. Tolkien</author>
    <available>true</available>
    <cover>PAPERBACK</cover>
    <id>3</id>
    <publishedYear>1937</publishedYear>
    <title>The Hobbit</title>
  </rows>
</page>

Response type defaults to XML if none is specified but if we add Jackson library to the CLASSPATH, Spring will pick it up and enable us to use JSON as well:


// $ curl -v -H "Accept: application/json" "http://localhost:8080/books/rest/book?page=1&max=3"

{
    "total":43,
    "max":3,
    "page":1,
    "rows":[
        {
            "id":1,
            "available":true,
            "author":"Charles Dickens",
            "title":"A Tale of Two Cities",
            "publishedYear":1859,
            "cover":"PAPERBACK",
            "comments":null
        },
        {
            "id":2,
            "available":true,
            "author":"J. R. R. Tolkien",
            "title":"The Lord of the Rings",
            "publishedYear":1954,
            "cover":"HARDCOVER",
            "comments":null
        },
        {
            "id":3,
            "available":true,
            "author":"J. R. R. Tolkien",
            "title":"The Hobbit",
            "publishedYear":1937,
            "cover":"PAPERBACK",
            "comments":null
        }
    ]
}

Nice, now we can work on the front-end, hopefully not making our hands too dirty. With regards to HTML markup, this is all we need, seriously:


<table id="grid"></table>
<div id="pager"></div>

Keep in mind that we will implement all CRUD operations, but still, this is all we need. No more HTML. Rest of the magic happens thanks to marvellous jqGrid library. Here is a basic setup:


$("#grid")
    .jqGrid({
      url:'rest/book',
      colModel:[
        {name:'id', label: 'ID', formatter:'integer', width: 40},
        {name:'title', label: 'Title', width: 300},
        {name:'author', label: 'Author', width: 200},
        {name:'publishedYear', label: 'Published year', width: 80, align: 'center'},
        {name:'available', label: 'Available', formatter: 'checkbox', width: 46, align: 'center'}
      ],
      caption: "Books",
      pager : '#pager',
      height: 'auto'
    })
    .navGrid('#pager', {edit:false,add:false,del:false, search: false});

Technically, this is all we need. URL to fetch the data, pointing to our controller (jqGrid will perform all the AJAX magic for us) and the data model (you may recognize book fields and their descriptions). However, since jqGrid is highly customizable, I applied few tweaks to make the grid look a bit better. Also I didn't like suggested names of metadata, for instance total field returned from the server is suppose to be the total number of pages, not records – highly counter-intuitive. Here are my tweaked options:


$.extend($.jgrid.defaults, {
  datatype: 'json',
  jsonReader : {
    repeatitems:false,
    total: function(result) {
      //Total number of pages
      return Math.ceil(result.total / result.max);
    },
    records: function(result) {
      //Total number of records
      return result.total;
    }
  },
  prmNames: {rows: 'max', search: null},
  height: 'auto',
  viewrecords: true,
  rowList: [10, 20, 50, 100],
  altRows: true,
  loadError: function(xhr, status, error) {
    alert(error);
  }
  });

Eager to see the results? Here is a browser screenshot:

Good looking, with customizable paging, lightweight refreshing... And our hands are still relatively clean! But I promised CRUD... If you were careful, you have probably noticed few navGrid attributes, dying to be turned on:


var URL = 'rest/book';
var options = {
  url: URL,
  editurl: URL,
  colModel:[
    {
      name:'id', label: 'ID',
      formatter:'integer',
      width: 40,
      editable: true,
      editoptions: {disabled: true, size:5}
    },
    {
      name:'title',
      label: 'Title',
      width: 300,
      editable: true,
      editrules: {required: true}
    },
    {
      name:'author',
      label: 'Author',
      width: 200,
      editable: true,
      editrules: {required: true}
    },
    {
      name:'cover',
      label: 'Cover',
      hidden: true,
      editable: true,
      edittype: 'select',
      editrules: {edithidden:true},
      editoptions: {
        value: {'PAPERBACK': 'paperback', 'HARDCOVER': 'hardcover', 'DUST_JACKET': 'dust jacket'}
      }
    },
    {
      name:'publishedYear',
      label: 'Published year',
      width: 80,
      align: 'center',
      editable: true,
      editrules: {required: true, integer: true},
      editoptions: {size:5, maxlength: 4}
    },
    {
      name:'available',
      label: 'Available',
      formatter: 'checkbox',
      width: 46,
      align: 'center',
      editable: true,
      edittype: 'checkbox',
      editoptions: {value:"true:false"}
    },
    {
      name:'comments',
      label: 'Comments',
      hidden: true,
      editable: true,
      edittype: 'textarea',
      editrules: {edithidden:true}
    }
  ],
  caption: "Books",
  pager : '#pager',
  height: 'auto'
};
$("#grid")
    .jqGrid(options)
    .navGrid('#pager', {edit:true,add:true,del:true, search: false});

The configuration is getting dangerously verbose, but there's nothing complicated out there – for each field we have added few additional attributes controlling how this field should be treated in edit mode. This includes what type of HTML input should represent it, validation rules, visibility, etc. But honestly, I believe it was worth it:

This nicely looking edit window has been fully generated by jqGrid based on our edit options mentioned above, including validation logic. We can make some of the fields visible in the grid hidden/inactive in edit dialog (like id) and vice-versa (cover and comments are not present in the grid, however you can modify them). Also notice few new icons visible in bottom-left corner of the grid. Adding and deleting is possible as well – and we haven't written a single line of HTML/JSP/JavaScript (excluding jqGrid configuration object).

Of course we all know that The User Interface Is The Application, and our interface is pretty good, however sometimes we really want a beautiful and working application. And currently the latter requirement is our Achilles' heel. Not because the back-end isn't ready, this is rather trivial:


@Controller
@RequestMapping(value = "/book")
public class BookController {

  private final Map<Integer, Book> books = new ConcurrentSkipListMap<Integer, Book>();

  @RequestMapping(value = "/{id}", method = GET)
  public @ResponseBody Book read(@PathVariable("id") int id) {
    //...
  }

  @RequestMapping(method = GET)
  public
  @ResponseBody
  Page<Book> listBooks(
      @RequestParam(value = "page", required = false, defaultValue = "1") int page,
      @RequestParam(value = "max", required = false, defaultValue = "20") int max) {
    //...
  }

  @RequestMapping(value = "/{id}", method = PUT)
  @ResponseStatus(HttpStatus.NO_CONTENT)
  public void updateBook(@PathVariable("id") int id, @RequestBody Book book) {
    //...
  }

  @RequestMapping(method = POST)
  public ResponseEntity<String> createBook(HttpServletRequest request, @RequestBody Book book) {
    //...
  }

  @RequestMapping(value = "/{id}", method = DELETE)
  @ResponseStatus(HttpStatus.NO_CONTENT)
  public void deleteBook(@PathVariable("id") int id) {
    //...
  }

}

Server-side is ready, but when it comes to data manipulation on the client-side, jqGrid reveals its dirty secret – all the traffic to the server is sent using POST like this:


Content-Type: application/x-www-form-urlencoded in the following format:

id=&title=And+Then+There+Were+None&author=Agatha+Christie&cover=PAPERBACK&publishedYear=1939&available=true&comments=&oper=add

The last attribute (oper=add) is crucial. Not really idiomatic REST, don't you think? If we could only use POST/PUT/DELETE appropriately and serialize data using JSON or XML... Modifying my server so that it is compliant with some JavaScript library (no matter how cool it is), seems like a last resort. Thankfully, everything can be customized with a moderate amount of work.


$.extend($.jgrid.edit, {
      ajaxEditOptions: { contentType: "application/json" },
      mtype: 'PUT',
      serializeEditData: function(data) {
        delete data.oper;
        return JSON.stringify(data);
      }
    });
$.extend($.jgrid.del, {
      mtype: 'DELETE',
      serializeDelData: function() {
        return "";
      }
    });

var URL = 'rest/book';
var options = {
  url: URL,
  //...
}

var editOptions = {
  onclickSubmit: function(params, postdata) {
    params.url = URL + '/' + postdata.id;
  }
};
var addOptions = {mtype: "POST"};
var delOptions = {
  onclickSubmit: function(params, postdata) {
    params.url = URL + '/' + postdata;
  }
};


$("#grid")
    .jqGrid(options)
    .navGrid('#pager',
    {}, //options
    editOptions,
    addOptions,
    delOptions,
    {} // search options
);

We have customized HTTP method per operation, serialization is handled using JSON and finally URLs for edit and delete operations are now suffixed with /record_id. Now it not only looks, it works! Look at the browser interaction with the server (note different HTTP methods and URLs):

Here is an example of creating a new resource on browser side:

To follow REST principles as closely as possible I return 201 Created response code together with Location header pointing to newly created resource. As you can see data is now being sent to the server in JSON format.

To summarize, such an approach has plenty of advantages:

GUI is very responsive, page appears instantly (it can be a static resource served from CDN), while data is loaded asynchronously via AJAX in lightweight JSON format
We get CRUD operations for free
REST interface for other systems is also for free

Compare this with any web framework out there. And did I mention about this little cherry on our JavaScript frosting: jqGrid is fully compliant with jQuery UI themes and also supports internationalization. Here is the same application with changed theme and language:

Full source code is available on my GitHub account. The application is self contained, just build it and deploy it to some servlet container.

Enabling load balancing and failover in Apache CXF

2011-05-30T23:47:00.000+02:00

A while ago we've faced the requirement of load-balancing web services clients based on Apache CXF. Also the clients should automatically fail-over when some of the servers are down. To make it even worse, the list of servers target addresses was to be obtained from external service and updated at runtime. Eventually we ended up with home-grown load-balancing micro-library (ESB/UDDI/WS-Addressing seemed like an interesting alternatives, but they were an overkill in our situation). If we only knew Apache CXF already supports all these features (almost) out of the box?

Don't blame us though, only reference to this feature points to a very poor documentation page (if you call 404 “poor”). If it's not in official documentation, I would expect to find it in Apache CXF Web Service Development book – unfortunately, bad luck there as well. But hey, isn't exploring such features yourself even greater fun? This is the client configuration we are starting with:


<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xmlns:clustering="http://cxf.apache.org/clustering"
       xmlns:util="http://www.springframework.org/schema/util">

    <jaxws:client id="testServiceClient"
                  serviceClass="com.blogspot.nurkiewicz.cxfcluster.SimpleService"
                  address="http://serverA/simple">
    </jaxws:client>

</beans>

Endpoint interface is not important here, enough to know the testServiceClient is being injected to some other services and load balancing and failover features shouldn't affect existing code. Note the service address is fixed and hard-coded (of course it can be externalized and read upon startup).

Surprisingly enabling failover alone is pretty simple, straightforward and self-explanatory (despite being XML):


<jaxws:client id="testServiceClient"
              serviceClass="com.blogspot.nurkiewicz.cxfcluster.SimpleService"
              address="http://serverA/simple">

    <jaxws:features>
        <clustering:failover>
            <clustering:strategy>
                <bean class="org.apache.cxf.clustering.RandomStrategy">
                    <property name="alternateAddresses">
                        <util:list>
                            <value>http://serverB/simple</value>
                            <value>http://serverC/simple</value>
                            <value>http://serverD/simple</value>
                        </util:list>
                    </property>
                </bean>
            </clustering:strategy>
        </clustering:failover>
    </jaxws:features>

</jaxws:client>

The serverA address is used as a primary endpoint, but when it fails all failover endpoints (serverB, serverC and serverD) are examined in random order. To play a bit with this configuration I advice you to turn on Apache CXF logging of requests and responses:


 <cxf:bus>
    <cxf:features>
        <cxf:logging/>
    </cxf:features>
</cxf:bus>

Once again (!) official documentation does not mention about very convenient configuration parameter prettyLogging that can be applied to logging feature in order to make XML requests and responses being properly formatted (new lines and indentation) before being logged. I wouldn't recommend it for production setup, but during development and testing having SOAP messages formatted is invaluable:


<bean id="abstractLoggingInterceptor" abstract="true">
    <property name="prettyLogging" value="true"/>
</bean>
<bean id="loggingInInterceptor" class="org.apache.cxf.interceptor.LoggingInInterceptor" parent="abstractLoggingInterceptor"/>
<bean id="loggingOutInterceptor" class="org.apache.cxf.interceptor.LoggingOutInterceptor" parent="abstractLoggingInterceptor"/>

<cxf:bus>
    <cxf:inInterceptors>
        <ref bean="loggingInInterceptor"/>
    </cxf:inInterceptors>
    <cxf:outInterceptors>
        <ref bean="loggingOutInterceptor"/>
    </cxf:outInterceptors>
    <cxf:outFaultInterceptors>
        <ref bean="loggingOutInterceptor"/>
    </cxf:outFaultInterceptors>
    <cxf:inFaultInterceptors>
        <ref bean="loggingInInterceptor"/>
    </cxf:inFaultInterceptors>
</cxf:bus>

So our service nicely fails over to backup endpoints if primary one is not available. But we have four equivalent servers and we want our client to treat them equally hitting each one with similar probability (round robin? random?). Here is when load-balancing is entering the stage:


<jaxws:client id="testServiceClient" serviceClass="com.blogspot.nurkiewicz.cxfcluster.SimpleService">

    <jaxws:features>
        <clustering:loadDistributor>
            <clustering:strategy>
                <bean class="org.apache.cxf.clustering.SequentialStrategy">
                    <property name="alternateAddresses">
                        <util:list>
                            <value>http://serverA/simple</value>
                            <value>http://serverB/simple</value>
                            <value>http://serverC/simple</value>
                            <value>http://serverD/simple</value>
                        </util:list>
                    </property>
                </bean>
            </clustering:strategy>
        </clustering:loadDistributor>
    </jaxws:features>

</jaxws:client>

Please note that the client itself does no longer define the address attribute. This suggests that alternateAddresses list is used exclusively throughout all the invocations and no primary address exists – which is actually the case. SequentialStrategy will use one endpoint after another providing nice round robin implementation (RandomStrategy is available as well). Also in this configuration you will get failover for free – if any endpoint fails, all endpoints starting from the first one will be examined (obviously except the one that has just failed).

Great! Now are CXF clients are much more rigid and fault-tolerant. But in our journey for higher availability and minimizing downtimes having alternate nodes being loaded only at application startup (in other words – adding a new server requires all clients restart) is too limiting. Fortunately we can make our load-balancing a bit more dynamic in two simple steps.


<jaxws:client id="testServiceClient" serviceClass="com.blogspot.nurkiewicz.cxfcluster.SimpleService">

    <jaxws:features>
        <clustering:loadDistributor>
            <clustering:strategy>
                <bean class="org.apache.cxf.clustering.SequentialStrategy">
                    <property name="alternateAddresses" ref="alternateAddresses"/>
                </bean>
            </clustering:strategy>
        </clustering:loadDistributor>
    </jaxws:features>

</jaxws:client>

<util:list id="alternateAddresses" list-class="java.util.concurrent.CopyOnWriteArrayList">
    <value>http://serverA/simple</value>
    <value>http://serverB/simple</value>
    <value>http://serverC/simple</value>
    <value>http://serverD/simple</value>
</util:list>

Nothing fancy, extracting nested anonymous bean. But having access to this list (please note I used java.util.concurrent.CopyOnWriteArrayList) enables us to inject it to any other service, possibly changing its state. How do I know this will work? Well, I spent few afternoons debugging Apache CXF to finally discover load-balancing algorithm: at first invocation CXF asks strategy for a list of possible nodes. Then it passes this list back to the strategy asking to pick one (small wtf here...) The strategy decides which address to use and removes picked address from the list (another small one here...) When CXF discovers the list is empty, story repeats itself. So if we replace the list of alternate addresses at runtime, after one round new list will be returned to the core CXF infrastructure.

Because I'm a huge JMX advocate, here is how we are going to modify the addresses list (you can use whatever mechanism you like):


@Service
@ManagedResource
public class AlternateAddressesManager {

    @Resource
    private List<String> alternateAddresses;

    @ManagedOperation
    public void addAlternateAddress(String address) {
        alternateAddresses.add(address);
    }

    @ManagedOperation
    public boolean removeAlternateAddress(String address) {
        return alternateAddresses.remove(address);
    }

    @ManagedAttribute
    public List<String> getAlternateAddresses() {
        return Collections.unmodifiableList(alternateAddresses);
    }

}

Yep, it's the very same alternateAddresses list used by SequentialStrategy, so by simply modifying it we are altering CXF addressing behaviour. Arguably we could extend CopyOnWriteArrayList adding few extra JMX-enabled methods (or, exploting Springs' flexibility, expose List methods directly via JMX!), but this would decrease maintainability and I would consider this as poor design.

Finally, we can launch jconsole or JVisualVM as on the screenshots below and enjoy our load-balancing infrastructure:

Happy? Not really. While studying CXF source code I came across this dreadful JavaDoc comment on LoadDistributorFeature and FailoverTargetSelector classes which take significant part in load-balancing process:

/**

 * [...]

 * Note that this feature changes the conduit on the fly and thus makes

 * the Client not thread safe.

*/

Focus on the text in bold (OK, honestly, I don't understand the rest). If you've worked with Spring for some time you know that testServiceClient bean is a shared singleton used by multiple threads concurrently (no, making it prototype scope won't help; why?), in contrary to default EJB stateless session beans, which are pooled. Fortunately Spring has a built-in solution for that as well. But before I finally came up with a right solution, several obstacles arose.

First, jaxws:client tag from CXF namespace does not allow to define bean scope, defaulting to singleton, while we want to pool our clients. So I had to fall back to good old bean definition with org.apache.cxf.jaxws.JaxWsProxyFactoryBean. No problem, slightly more verbose, although if you can't/don't want to use custom Spring namespaces, you might have used it from the very beginning. Now the best part: I can simply wrap any bean with prototype scope in a special proxy and Spring will automagically create an object pool (based on commons-pool library) and create as many bean instances as necessary to keep each bean used by only one thread. Here is the configuration:


<bean id="testServiceClientFactoryBean" class="org.apache.cxf.jaxws.JaxWsProxyFactoryBean">
    <property name="serviceClass" value="com.blogspot.nurkiewicz.cxfcluster.SimpleService"/>
    <property name="features">
        <util:list>
            <bean class="org.apache.cxf.clustering.LoadDistributorFeature">
                <property name="strategy">
                    <bean class="org.apache.cxf.clustering.SequentialStrategy">
                        <property name="alternateAddresses" ref="alternateAddresses"/>
                    </bean>
                </property>
            </bean>
        </util:list>
    </property>
</bean>

<bean id="testServiceClientTarget" factory-bean="testServiceClientFactoryBean" factory-method="create" scope="prototype" lazy-init="true"/>

<bean id="testServiceClient" class="org.springframework.aop.framework.ProxyFactoryBean">
    <property name="targetSource">
        <bean class="org.springframework.aop.target.CommonsPoolTargetSource">
            <property name="targetClass" value="com.blogspot.nurkiewicz.cxfcluster.SimpleService"/>
            <property name="targetBeanName" value="testServiceClientTarget"/>
            <property name="maxSize" value="10"/>
            <property name="maxWait" value="5000"/>
        </bean>
    </property>
</bean>

Have you noticed maxSize and maxWait pool attributes? They are insanely cool! You can tell Spring not to create more than 10 clients in the pool and if the pool is empty (all the beans are currently in use), we should wait no more than 5000ms (and what happens afterwards is configurable!) This is actually a very simple yet powerful throttling mechanism, much simpler than JMS or explicit thread pools, we get absolutely for free! E.g. don't want to serve more than 20 concurrent web service clients? Make your server endpoint access service bean being pooled with size limited to 20. Client above this limit will be rejected as no service bean is available.

Of course in adults world nothing works as expected. I quickly discovered that JaxWsProxyFactoryBean.create is not thread-safe and reported CXF-3558. As a workaround I had to synchronize the client factory used by CommonsPoolTargetSource simply by subclassing it:


import org.apache.commons.pool.ObjectPool;
import org.apache.commons.pool.PoolUtils;
import org.springframework.aop.target.CommonsPoolTargetSource;

public class SynchCommonsPoolTargetSource extends CommonsPoolTargetSource {

    @Override
    protected ObjectPool createObjectPool() {
        return PoolUtils.synchronizedPool(super.createObjectPool());
    }

}

Synchronizing the factory seems like a common need so I created SPR-8382 – maybe it will find its way to official release. BTW while working on this article I also reported IDEA-70365 – Spurious "Could not autowire" error reported for beans of List type.

Finally! Our load-balancing and failover works like a charm. Next step would be to temporarily discard nodes that are down for couple of seconds and increase this time if the endpoint is still down afterwards. But Apache CXF has so terrible API in this area that I had to leave this topic for a while. Maybe YOU can help?

MongoDB and recording appenders for Logback

2011-04-08T19:50:00.003+02:00

Today I am giving you two new appenders for Logback: one for MongoDB and one which I called recording appender. Just as a reminder, appenders (both in Log4J and Logback) are an abstraction of your application logs destination. The most common are file and console appenders, followed by several others built-in. MongoDB appender is pretty straightforward, so I will start by describing the recording appender.

Recording appender

As you already know, one of the biggest benefits of using logging frameworks are logging levels. By carefully choosing levels for each logging statement we can easily filter which logs should be present in our log files and which shouldn't. Also we can apply different logging strategies for different environments. This is in theory. In practice we often face the choice between: log everything just in case and handle gigabytes of meaningless log files or log only warnings and errors but when they actually occur, they are meaningless as well, lacking important debugging context. The idea isn't new (see [1], [2] and [3] for example), but somehow decent implementation is missing in both Log4J and Logback. And the idea is simple – as long as there is nothing wrong happening with the system: do not log anything or log very little – but silently memorize all debug logs in some cyclic buffer. And whenever disaster occurs (any log with ERROR level, probably an exception), dump the buffer first to provide meaningful context.

Writing custom logging appenders is pretty straightforward. Following is the essence of my recording appender:


public class RecordingAppender extends UnsynchronizedAppenderBase<ILoggingEvent> {

  private ThreadLocal<CyclicBuffer<ILoggingEvent>> recordedEvents = new ThreadLocal<CyclicBuffer<ILoggingEvent>>() {
    @Override
    protected CyclicBuffer<ILoggingEvent> initialValue() {
      return new CyclicBuffer<ILoggingEvent>(maxEvents);
    }
  };

  @Override
  protected void append(ILoggingEvent eventObject) {
    if (triggersDump(eventObject)) {
      dumpRecordedEvents();
      dump(eventObject);
    } else
      recordedEvents.get().add(eventObject);
  }

  //...

}

I hope the code is self-explanatory, if not – I failed as a developer, not you as a reader. The only detail worth explaining is the usage of ThreadLocal. Logging history is stored ThreadLocal, so only logs from current thread will be dumped in case of error. This seems reasonable in most cases (and eliminates the need for synchronization). Why the appender is parametrized with generic ILoggingEvent type will be described later. The full source code of this appender is, as always, available on my Logback fork at GitHub (recording-appender branch).

Using this appender is really simple – just declare ch.qos.logback.classic.RecordingAppender and define one or more delegating appenders to be used when dump is required. As a side note: which GoF pattern is it?

With the configuration below every log statement with level WARN or higher will trigger dump. The configuration also states that up to 1000 records will be kept in memory, unless some of them are older than 15 seconds. When warning or error is encountered, it will be printed on the console, preceded by more detailed logs. It really works (in addition of having 100% code coverage).


<?xml version="1.0" encoding="UTF-8" ?>
<configuration>
  <appender name="REC" class="ch.qos.logback.classic.RecordingAppender">
    <appender-ref ref="STDOUT"/>

    <maxEvents>1000</maxEvents>
    <dumpThreshold>WARN</dumpThreshold>
    <expiryTimeMs>15000</expiryTimeMs>
  </appender>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%-4relative [%thread] %-5level - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="REC"/>
  </root>
</configuration>

MongoDB appender

MongoDB, being document oriented database focused on performance and scalability seems like a great storage for application and server logs – much better than DbAppender using traditional relational database. Why? Quickly count how many tables and rows you need to store normalized logging event containing stack trace with several frames and MDC map? And what if you just want to store some properties, leaving others as optional? Sacrificing absolute durability and ACID constraints, in MongoDB you just store document – with nested properties, skipping optional parameters – and extremely fast. Also, once again, the idea isn't new.

But again, why would you like to store application or web server HTTP access logs (be patient!) in database altogether? Well, with a little help of sharding and MapReduce, searching, aggregating and transforming a lot of data is a pleasure.

The implementation is trivial (excerpt from MongoDBAppenderBase.java, see mongo-appender branch):


public abstract class MongoDBAppenderBase<E> extends UnsynchronizedAppenderBase<E> {

  //...

  @Override
  public void start() {
    try {
      connectToMongoDB();
      super.start();
    } catch (UnknownHostException e) {
      addError("Error connecting to MongoDB server: " + host + ":" + port, e);
    }
  }

  private void connectToMongoDB() throws UnknownHostException {
    mongo = new Mongo(new ServerAddress(host, port), buildOptions());
    DB db = mongo.getDB(dbName);
    if (username != null && password != null)
      db.authenticate(username, password.toCharArray());
    eventsCollection = db.getCollection(collectionName);
  }

  protected abstract BasicDBObject toMongoDocument(E event);

  @Override
  protected void append(E eventObject) {
    eventsCollection.insert(toMongoDocument(eventObject));
  }

  //...

}

Appender doesn't have to be synchronized (it only uses native MongoDB Java driver, which is thread safe and even handles connection pooling) and all it does is connecting to MongoDB server/cluster and insert logging events as documents in the database. Abstract toMongoDocument() method and E generic type? - looks suspicious... Logback has a pretty clever architecture. In logback-core you place general logging logic, like connecting and storing documents in MongoDB in our case. Then one can simply subclass the base appender to define logic specific to a given logging object type.

So what object types does Logback support? The traditional (classic) logging is what we are familiar with. logback-access on the other hand allows us to log web container access logs using Logback infrastructure. And because MongoDB has no schema and creates collections (table-like structures) the first time they are used, we can essentially store anything. Following is the toMongoDocument() implementation excerpt for classic logs (note the generic type):


public class MongoDBAppender extends MongoDBAppenderBase<ILoggingEvent> {

  public MongoDBAppender() {
    super("loggingEvents");
  }

  @Override
  protected BasicDBObject toMongoDocument(ILoggingEvent event) {
    final BasicDBObject doc = new BasicDBObject();
    doc.append("timeStamp", new Date(event.getTimeStamp()));
    doc.append("level", event.getLevel().levelStr);
    doc.append("thread", event.getThreadName());
    if (event.getMdc() != null && !event.getMdc().isEmpty())
      doc.append("mdc", event.getMdc());
    //...
    return doc;
    }
}

...and here is what you can expect to find your MongoDB database:


{
    "_id" : ObjectId("4d9cbcbf7abb3abdaf9679cd"),
    "timeStamp" : ISODate("2011-04-06T19:19:27.006Z"),
    "level" : "ERROR",
    "thread" : "main",
    "logger" : "ch.qos.logback.classic.db.mongo.MongoDBAppenderTest",
    "message" : "D" 
}

Very similar implementation for access logs follows. Once again look carefully – both appenders are extending MongoDBAppenderBase with different generic type, only implementing log-to-document logic, whereas common database connection logic is handled once in base class. Pretty elegant design (it's Logback design, not mine, I am just following it), seems like OOP is not dead after all:


public class MongoDBAppender extends MongoDBAppenderBase<IAccessEvent> {

  public MongoDBAppender() {
    super("accessEvents");
  }

  @Override
  protected BasicDBObject toMongoDocument(IAccessEvent event) {
    final BasicDBObject doc = new BasicDBObject();
    doc.append("timeStamp", new Date(event.getTimeStamp()));
    if(server)
      doc.append("server", event.getServerName());
    //...
    return doc;
  }
}

You can compare classic and access implementations to see how similar they are, although they cope with really different data. Here is what you might find in accessEvents collections in MongoDB:


{
    "_id" : ObjectId("4d98cc4f7abb95e59279e183"),
    "timeStamp" : ISODate("2011-04-03T19:36:47.339Z"),
    "server" : "localhost",
    "remote" : {
        "host" : "0:0:0:0:0:0:0:1",
        "user" : "tomcat",
        "addr" : "0:0:0:0:0:0:0:1" 
    },
    "request" : {
        "uri" : "/manager/images/tomcat.gif",
        "protocol" : "HTTP/1.1",
        "method" : "GET",
        "sessionId" : "1C6357816D9EEFD31F6D9D154D87308A",
        "userAgent" : "Mozilla/5.0 (X11; U; Linux i686; pl-PL; rv:1.9.2.16) Gecko/20110323 Ubuntu/10.10 (maverick) Firefox/3.6.16",
        "referer" : "http://localhost:8080/manager/html" 
    },
    "response" : {
        "contentLength" : NumberLong(1934),
        "statusCode" : 200 
    } 
}

You might ask yourself a question: why would I store access logs in crazy, JSON-like documents stored in database driven by C++? The answer is: scalability. MongoDB speed and sharding capabilities make it a great choice for storing lots of free-form data. Now, using built-in MapReduce framework you might search, aggregate, or maybe even look for suspicious usage patterns across thousands of servers in parallel. Be warned thou that timeStamp, although looks promising, isn't very good candidate for sharding key. Assuming all your web servers have similar system clock, at a given point in time all of them will be writing to the same shard. After a moment or two, they will all switch to a different one. At the same time, all other shards are dying of boredom. But timeStamp+serverName looks nice (order of keys in compound key is really important, just like with indexes in RDBMS).

Another tip is using capped collections in MongoDB. There is no obvious natural key for logging events (both classic and access), so we need to use generated keys, which aren't useful as they don't form any particular order. But if you use capped collections, order of records in the database is guaranteed to be the same as insertion order. Also, capped collections are limited in size and automatically remove the oldest entries, which seems like a great fit for logging use case.

MongoDBAppender has many other features, including:

Fully configurable MongoDB connection
For access logger you can define which access parameters (like response status code, URI, session id, etc.) should be persisted
For classic logger: should caller data be persisted

See for yourself how many optional parameters are provided. If you like the idea of recording appender (your application very own flight data recorder), please take a look and vote for LBCLASSIC-260. I also filed an issue for MongoDB appender, LBCLASSIC-261. Oh, if I'm into advertising myself already, maybe this will catch your attention as well. Have a great time playing with my appenders (you can even combine them) and I'm waiting for your comments.

Jolokia + Highcharts = JMX for human beings

2011-03-20T19:46:00.001+01:00

Java Management Extensions (JMX) is a well established, but not widespread technology allowing to monitor and manage every JVM. It provides tons of useful information, like CPU, thread and memory monitoring. Also every application can register its own metrics and operations in so called MBeanServer. Several libraries take advantage of JMX: Hibernate, EhCache and Logback and servers like Tomcat or Mule ESB, to name a few. This way one can monitor ORM performance, HTTP worker threads utilization, but also change logging levels, flush caches, etc. If you are creating your own library or container, JMX is a standard for monitoring, so please don't reinvent a wheel. Also Spring has a wonderful support for JMX.

If this standard is so wonderful, why aren't we using it all day long? Well, history of JMX reaches the dark ages of J2EE. Although the specification isn't that complicated, there are at least two disadvantages of JMX effectively discouraging people from using it. First one lies on the server side. At the foundation of Java Management Extensions is an MBeanServer where you register MBeans. Each MBean exposes its properties (attributes) and operations for external access. This is fine (especially when Spring is used: 1 line of XML + two annotations), but there's a catch. By default the MBeanServer exposes itself via RMI, which is certainly not the top XXI century protocol...

The second drawback of JMX lies on the client side. JConsole, although not terrible, has very limited functionality. If we want to present our JMX-enabled application to the customer, showing JConsole as a client is a bit embarrassing. It is capable of showing graphs, but you cannot display more than one attribute at the same composite graph and you also can't observe attributes from different MBeans at the same time. Last but not least, again, we're living in the XXI century, Swing client? Weird RMI port? What about Web 2.0 rave? Knowing how much I love charts (and how data visualization is important for diagnosing and correlating facts) I felt really disappointed by JConsole capabilites. And the only rival of JConsole seems dead.

Jolokia – bridge JMX over HTTP

I knew exactly what I wanted: HTTP transport for JMX server, so that I can easily access MBeanServer from outside without the RMI mess. Jolokia meets my expectations perfectly. This small library (about 170 kiB) connects to a given MBeanServer and exposes it via REST-like interface. Just deploy the jolokia.war file on your servlet container and use whatever HTTP client you want to monitor your JVM!


$ curl localhost:8080/jolokia
{
  "request" : { "type" : "version" },
  "status" : 200,
  "timestamp" : 1300561261,
  "value" : {
      "agent" : "0.83",
      "info" : {
          "product" : "tomcat",
          "vendor" : "Apache",
          "version" : "7.0.10"
        },
      "protocol" : "4.1"
    }
}


$ curl localhost:8080/jolokia/read/java.lang:type=Memory/HeapMemoryUsage
{
  "request" : {
      "attribute" : "HeapMemoryUsage",
      "mbean" : "java.lang:type=Memory",
      "type" : "read"
    },
  "status" : 200,
  "timestamp" : 1300561367,
  "value" : {
      "committed" : "169607168",
      "init" : "49404160",
      "max" : "702808064",
      "used" : "16635472"
    }
}

You must be aware that Jolokia has a handful of other features. It can work on ordinary JVMs (not only servlet containers) starting dedicated web server, it can also connect to external MBeanServer, so you don't have to add any new WAR files as long as you have JMX external access. But the killer feature I quickly discovered was:

Jolokia + AJAX – a perfect couple

HTTP, JSON... AJAX? Accessing MBeans directly using JavaScript on the client side would be huge. But I haven't even written a single line of code yet when I spotted Jolokia Javascript Client Library. Wow, I really love this project! So I took the token bucket application developed last time and quickly added simple server polling for current heap memory usage. Boring. Chart displaying memory usage over time would be much sexier...

Jolokia, AJAX and Highcharts – exciting threesome

First, I owe you some explanation. Why am I entering the dirty playground of the most hated web 2.0 child – JavaScript? Let me reveal my goal: fast and snappy, good looking JMX visualization with real-time updates in the browser rather than in the obscure jconsole. The solution should be simple, shouldn't require major server side changes (preferably: none) and should be highly configurable and flexible. Leveraging JFreeChart (Java de facto standard for charting) to produce new version of the chart each second or even more frequently was out of the question.

But if we already have access to JMX metrics on the client (browser) side, why not generating the charts there as well, only quickly updating data series when new data arrives. Be pragmatic. First I tried jqPlot – works great for static charts, but sucks completely when trying to update them. Unless you can live with 10 MiB of memory leaking in the browser every second per chart... Seems like many JavaScript charting libraries suffer the same problem – except Highcharts – library of my choice. Here is how easily one can plot memory usage chart only on the client side using Jolokia JMX library:


$(document).ready(function() {
    new Monitor();
});

function Monitor() {
    var jmx = new Jolokia("/jolokia");

    var chart = new Highcharts.Chart({
        chart: {
            renderTo: 'memoryChart',
            defaultSeriesType: 'spline',
            events: {
                load: function() {
                    var series = this.series[0];
                    setInterval(function() {
                        var x = (new Date()).getTime();
                        var memoryUsed = jmx.getAttribute("java.lang:type=Memory", "HeapMemoryUsage", "used");
                        series.addPoint({
                            x: new Date().getTime(),
                            y: parseInt(memoryUsed)
                        }, true, series.data.length >= 50);
                    }, 1000);
                }
            }
        },
        xAxis: {
            type: 'datetime'
        },
        series: [{
                data: [],
            }
        ]
    });
}

Few less important lines were skipped (mainly chart cosmetics), as always full source is available on GitHub. And this is the result so far:

BTW I bit reluctantly switched to Google Chrome browser while writing this article. JavaScript-heavy applications are insanely slow on Firefox, work fine on Opera but Google Chrome beats them together.

Having one chart, why not add several others? Luckily Jolokia supports bulk requests (also in JavaScript client library), so we will poll server only once a second, no matter how many charts are displayed.

Since we are doing so well, why not allow user to rearrange charts so that he can put most relevant ones next to each other (portlets? iGoogle? Anyone?) Luckily, jQuery UI library (Jolokia JavaScript client is built on top of jQuery) ships with portlet-like support built-in.


function JmxChartsFactory(keepHistorySec, pollInterval, columnsCount) {
    var jolokia = new Jolokia("/jolokia");
    var series = [];
    var monitoredMbeans = [];
    var chartsCount = 0;

    columnsCount = columnsCount || 3;
    pollInterval = pollInterval || 1000;
    var keepPoints = (keepHistorySec || 600) / (pollInterval / 1000);

    setupPortletsContainer(columnsCount);

    setInterval(function() {
        pollAndUpdateCharts();
    }, pollInterval);

    this.create = function(mbeans) {
        mbeans = $.makeArray(mbeans);
        series = series.concat(createChart(mbeans).series);
        monitoredMbeans = monitoredMbeans.concat(mbeans);
    };

    function pollAndUpdateCharts() {
        var requests = prepareBatchRequest();
        var responses = jolokia.request(requests);
        updateCharts(responses);
    }

    function createNewPortlet(name) {
        return $('#portlet-template')
                .clone(true)
                .appendTo($('.column')[chartsCount++ % columnsCount])
                .removeAttr('id')
                .find('.title').text((name.length > 50? '...' : '') + name.substring(name.length - 50, name.length)).end()
                .find('.portlet-content')[0];
    }

    function setupPortletsContainer() {
        var column = $('.column');
        for(var i = 1; i < columnsCount; ++i){
            column.clone().appendTo(column.parent());
        }
        $(".column").sortable({
            connectWith: ".column"
        });

        $(".portlet-header .ui-icon").click(function() {
            $(this).toggleClass("ui-icon-minusthick").toggleClass("ui-icon-plusthick");
            $(this).parents(".portlet:first").find(".portlet-content").toggle();
        });
        $(".column").disableSelection();
    }

    function prepareBatchRequest() {
        return $.map(monitoredMbeans, function(mbean) {
            return {
                type: "read",
                mbean: mbean.name,
                attribute: mbean.attribute,
                path: mbean.path
            };
        });
    }

    function updateCharts(responses) {
        var curChart = 0;
        $.each(responses, function() {
            var point = {
                x: this.timestamp * 1000,
                y: parseFloat(this.value)
            };
            var curSeries = series[curChart++];
            curSeries.addPoint(point, true, curSeries.data.length >= keepPoints);
        });
    }

    function createChart(mbeans) {
        return new Highcharts.Chart({
            chart: {
                renderTo: createNewPortlet(mbeans[0].name),
                animation: false,
                defaultSeriesType: 'area',
                shadow: false
            },
            title: { text: null },
            xAxis: { type: 'datetime' },
            yAxis: {
                title: { text: mbeans[0].attribute }
            },
            legend: {
                enabled: true,
                borderWidth: 0
            },
            credits: {enabled: false},
            exporting: { enabled: false },
            plotOptions: {
                area: {
                    marker: {
                        enabled: false
                    }
                }
            },
            series: $.map(mbeans, function(mbean) {
                return {
                    data: [],
                    name: mbean.path || mbean.attribute
                }
            })
        })
    }
}

Sure, 110 lines is a lot of code, but you must admit that it's not that much when feature set is considered: configurable chart history length, polling interval and number of columns in portlet layout. Also, the set of visible JMX charts are fully customizable. If you want, you might easily add the possibility to add and remove charts at runtime when needed or even browsing MBeanServer exposed beans. The usage is of this class is very simple:


$(document).ready(function() {
    var factory = new JmxChartsFactory();
    factory.create([
        {
            name: 'java.lang:type=Memory',
            attribute: 'HeapMemoryUsage',
            path: 'committed'
        },
        {
            name: 'java.lang:type=Memory',
            attribute: 'HeapMemoryUsage',
            path: 'used'
        }
    ]);
    factory.create([
        {
            name: 'java.lang:type=OperatingSystem',
            attribute: 'SystemLoadAverage'
        }
    ]);
    factory.create({
        name:     'java.lang:type=Threading',
        attribute: 'ThreadCount'
    });
    factory.create([
        {
            name: 'Catalina:name="http-bio-8080",type=ThreadPool',
            attribute: 'currentThreadsBusy'
        },
        {
            name: 'Catalina:name=executor,type=Executor',
            attribute: 'queueSize'
        }
    ]);
    factory.create([
        {
            name: 'com.blogspot.nurkiewicz.download.tokenbucket:name=perRequestTokenBucket,type=PerRequestTokenBucket',
            attribute: 'OngoingRequests'
        },
        {
            name: 'com.blogspot.nurkiewicz.download:name=downloadServletHandler,type=DownloadServletHandler',
            attribute: 'AwaitingChunks'
        }
    ]);
});

Tired of code? HTML for this article can be found here, and as Chinese used to say, a picture is worth a thousand lines of code:

But because our monitoring dashboard is so dynamic, to quote Nicolaus Copernicus “A YouTube video is worth a thousand pictures”* (somewhere in the middle you'll see the system reacting after heavy load was simulated):

Now these 100+ lines of JavaScript code aren't that overwhelming, don't you think? To summarize, using JavaScript and handful of readily available libraries we added interactive, refreshable, Web 2.0-ish monitoring dashboard. It integrates seamlessly with every JVM using JMX, and if we would use Jolokia proxy mode, no changes would be required in monitored application/server. Because the client asks JMX server in batch and updates charts on the client side, everything works with minimal delay.

So the next time your customer asks for a monitoring solution or you want to enrich existing application without modifying it too much – consider the simplest solution, as it might be the best one as well. And maybe this tiny dashboard code is a valuable milestone of a decent successor of aforementioned JManage?

* Other famous quote by Nicolaus Copernicus: “Don't believe in everything you read in the Internet”...

Tenfold increase in server throughput with Servlet 3.0 asynchronous processing

2011-03-11T23:22:00.004+01:00

It is not a secret that Java servlet containers aren't particularly suited for handling large amount of concurrent users. Commonly established thread-per-request model effectively limits the number of concurrent connections to the number of concurrently running threads JVM can handle. And because every new thread introduces significant increase of memory footprint and CPU utilization (context switches), handling more than 100-200 concurrent connections seems like a ridiculous idea in Java. At least it was in pre-Servlet 3.0 era.

In this article we will write scalable and robust file download server with throttled speed limit. Second version, leveraging Servlet 3.0 asynchronous processing feature, will be able to handle ten times bigger load using even less threads. No additional hardware required, just few wise design decisions.

Token bucket algorithm

Building a file download servers we have to consciously manage are our resources, especially network bandwidth. We don't want a single client to consume the whole traffic, we might even want to throttle the download limit dynamically at runtime, based on user, time of the day, etc. - and of course everything happens during heavy load. Developers love reinventing the wheel, unfortunately all our requirements are already addressed by absurdly simple token bucket algorithm.

The explanation in Wikipedia is pretty good, but since we'll adjust the algorithm a bit for our needs, here's even simpler description. First there was a bucket. In this bucket there were uniform tokens. Each token is worth 20 kiB (I will be using real values from our application) of raw data. Every time a client ask for a file, the server tries to take one token from the bucket. If it succeeds, he sends 20 kiB to the client. Repeat last two sentences. What if the server fails to obtain the token because the bucket is already empty? He waits.

So where are the tokens coming from? Background process fill the bucket from time to time. Now it becomes clear. If this background process adds 100 new tokens every 100 ms (10 times per second), each worth 20 kiB, the server is capable of sending 20 MiB/s (100 times 20 kiB times 10) max, shared amongst all the clients. Of course if the bucket is full (1000 tokens), new tokens are ignored. This works amazingly well – if bucket is empty, clients are waiting for next bucket filling cycle; and by controlling the bucket capacity we can limit total bandwidth.

Enough of talking, our simplistic implementation of token bucket starts with an interface (whole source code is available on GitHub in global-bucket branch):


public interface TokenBucket {

    int TOKEN_PERMIT_SIZE = 1024 * 20;

    void takeBlocking() throws InterruptedException;
    void takeBlocking(int howMany) throws InterruptedException;

    boolean tryTake();
    boolean tryTake(int howMany);

}

takeBlocking() methods are waiting synchronously for the token to become available, while tryTake() are taking token only if it is available, returning true immediately if taken, false otherwise. Fortunately the term bucket is just an abstraction: because tokens are indistinguishable, all we need to implement bucket is an integer counter. But because the bucket is inherently multi-threaded and some waiting is involved, we need more sophisticated mechanism. Semaphore seems to be almost ideal:


@Service
@ManagedResource
public class GlobalTokenBucket extends TokenBucketSupport {

    private final Semaphore bucketSize = new Semaphore(0, false);

    private volatile int bucketCapacity = 1000;

    public static final int BUCKET_FILLS_PER_SECOND = 10;

    @Override
    public void takeBlocking(int howMany) throws InterruptedException {
        bucketSize.acquire(howMany);
    }

    @Override
    public boolean tryTake(int howMany) {
        return bucketSize.tryAcquire(howMany);
    }

}

Semaphore fits exactly to our requirements. bucketSize represents current amount of tokens in the bucket. bucketCapacity on the other hand limits the bucket maximum size. It is volatile because it can be modified via JMX (visibility):


@ManagedAttribute
public int getBucketCapacity() {
    return bucketCapacity;
}

@ManagedAttribute
public void setBucketCapacity(int bucketCapacity) {
    isTrue(bucketCapacity >= 0);
    this.bucketCapacity = bucketCapacity;
}

As you can see I am using Spring and its support for JMX. Spring framework isn't absolutely necessary in this application, but it brings some nice features. For instance implementing a background process that periodically fills the bucket looks like this:


@Scheduled(fixedRate = 1000 / BUCKET_FILLS_PER_SECOND)
public void fillBucket() {
    final int releaseCount = min(bucketCapacity / BUCKET_FILLS_PER_SECOND, bucketCapacity - bucketSize.availablePermits());
    bucketSize.release(releaseCount);
}

For the record: (1) tiny XML snippet is required to make @Scheduled annotation working and (2) – this code contains major multi-threading bug that we can ignore for the purposes of this article. It is suppose to fill the bucket up to the maximum value – will it always work?

Having token bucket abstraction and very basic implementation we can develop the actual servlet returning files. I am always returning the same fixed file with size of almost 200 kiB):


@WebServlet(urlPatterns = "/*", name="downloadServletHandler")
public class DownloadServlet extends HttpRequestHandlerServlet {}


@Service
public class DownloadServletHandler implements HttpRequestHandler {

    private static final Logger log = LoggerFactory.getLogger(DownloadServletHandler.class);

    @Resource
    private TokenBucket tokenBucket;

    @Override
    public void handleRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        final File file = new File("/home/dev/tmp/ehcache-1.6.2.jar");
        final BufferedInputStream input = new BufferedInputStream(new FileInputStream(file));
        try {
            response.setContentLength((int) file.length());
            sendFile(request, response, input);
        } catch (InterruptedException e) {
            log.error("Download interrupted", e);
        } finally {
            input.close();
        }

    }

    private void sendFile(HttpServletRequest request, HttpServletResponse response, BufferedInputStream input) throws IOException, InterruptedException {
        byte[] buffer = new byte[TokenBucket.TOKEN_PERMIT_SIZE];
        final ServletOutputStream outputStream = response.getOutputStream();
        for (int count = input.read(buffer); count > 0; count = input.read(buffer)) {
            tokenBucket.takeBlocking();
            outputStream.write(buffer, 0, count);
        }
    }
}

HttpRequestHandlerServlet was used here. As simple as can be: read 20 kiB of file, take the token from the bucket (waiting if unavailable), send chunk to the client, repeat until the end of file.

Believe it or not, this actually works! No matter how many (or how few) clients are concurrently accessing this servlet, total outgoing network bandwidth never exceeds 20 MiB! The algorithm works and I hope you get some basic feeling how to use it. But let's face it – global limit is way too inflexible and kind of lame – single client can actually consume your whole bandwidth.

So what if we had a separate bucket for each client? Instead of one semaphore – a map? Each client has a separate independent bandwidth limit, so there is no risk of starvation. But there is even more:

some clients might be more privileged, having bigger or no limit at all,
some might be black listed, resulting in connection rejection or very low throughput
banning IPs, requiring authentication, cookie/user agent verification, etc.
we might try to correlate concurrent requests coming from the same client and use the same bucket for all of them to avoid cheating by opening several connections. We might also reject subsequent connections
and much more...

Our bucket interface grows allowing the implementation to take advantage of the new possibilities (see branch per-request-synch):


public interface TokenBucket {

    void takeBlocking(ServletRequest req) throws InterruptedException;
    void takeBlocking(ServletRequest req, int howMany) throws InterruptedException;

    boolean tryTake(ServletRequest req);
    boolean tryTake(ServletRequest req, int howMany);

    void completed(ServletRequest req);
}



public class PerRequestTokenBucket extends TokenBucketSupport {

    private final ConcurrentMap<Long, Semaphore > bucketSizeByRequestNo = new ConcurrentHashMap<Long, Semaphore >();

    @Override
    public void takeBlocking(ServletRequest req, int howMany) throws InterruptedException {
        getCount(req).acquire(howMany);
    }

    @Override
    public boolean tryTake(ServletRequest req, int howMany) {
        return getCount(req).tryAcquire(howMany);
    }

    @Override
    public void completed(ServletRequest req) {
        bucketSizeByRequestNo.remove(getRequestNo(req));
    }

    private Semaphore getCount(ServletRequest req) {
        final Semaphore semaphore = bucketSizeByRequestNo.get(getRequestNo(req));
        if (semaphore == null) {
            final Semaphore newSemaphore = new Semaphore(0, false);
            bucketSizeByRequestNo.putIfAbsent(getRequestNo(req), newSemaphore);
            return newSemaphore;
        } else {
            return semaphore;
        }
    }

    private Long getRequestNo(ServletRequest req) {
        final Long reqNo = (Long) req.getAttribute(REQUEST_NO);
        if (reqNo == null) {
            throw new IllegalAccessError("Request # not found in: " + req);
        }
        return reqNo;
    }

}

The implementation is very similar (full class here) except that the single semaphore was replaced by map. I am not using request object itself as a map key for various reasons but a unique request number that I am assigning manually when receiving new connection. Calling completed() is very important, otherwise the map would grow continuously leading to memory leak. All in all, the token bucket implementation haven't changed a lot, also the download servlet is almost the same (except passing request to token bucket). We are now ready for some stress testing!

Throughput testing

For the testing purposes we will use JMeter with this wonderful set of plugins. During the 20-minute testing session we warm up our server firing up one new thread (concurrent connection) every 6 seconds to reach 100 threads after 10 minutes. For the next ten minutes we will keep 100 concurrent connections to see how stable the server works:

Important note: I artificially lowered the number of HTTP worker threads to 10 in Tomcat (7.0.10 tested). This is a far from real configuration, but I wanted to emphasize some phenomena that occur with high load compared to server capabilities. With default pool size I would need several client machines running distributed JMeter session to generate enough traffic. If you have a server farm or couple of servers in the cloud (as opposed to my 3-year-old laptop), I would be delighted to see the results in more realistic environment.

Remembering how many HTTP worker threads are available in Tomcat, response times over time are far from satisfactory:

Please note the plateau at the beginning of the test: after about a minute (hint: when the number of concurrent connections exceeds 10) response times are skyrocketing to stabilize at around 10 seconds after 10 minutes (number of concurrent connections reaches one hundred). Once again: the same behavior would occur with 100 worker threads and 1000 concurrent connections – it's just a matter of scale. The response latencies graph (time between sending request and receiving first lines of response) clears any doubts:

Below magical 10 threads our application responds almost instantly. This is really important for clients as receiving only headers (especially Content-Type and Content-Length) allows them to more accurately inform the user what is going on. So what is the reason of Tomcat waiting with the response? No magic here really. We have only 10 threads and each connection requires one thread, so Tomcat (and any other pre-Servlet 3.0 container) handles 10 clients while the remaining 90 are... queued. The moment one of the 10 lucky ones is done, one connection from the queue is taken. This explains average 9 second latency whilst the servlet needs only 1 second to serve the request (200 kiB with 20 kiB/s limit). If you are still not convinced, Tomcat provides nice JMX indicators showing how many threads are occupied and how many requests are queued:

With traditional servlets there is nothing we can do. Throughput is horrible but increasing the total number of threads is not an option (think: from 100 to 1000). But you don't actually need a profiler to discover that threads aren't the true bottleneck here. Look carefully at DownloadServletHandler, where do you think most of the time is spent? Reading a file? Sending data back to the client? No, the servlet waits... And then waits even more. Non-productively hanging on semaphore – thankfully CPU is not harmed, but what if it was implemented using busy waiting? Luckily Tomcat 7 finally supports...

Servlet 3.0 asynchronous processing

We are this close to increase our server capacity by an order of magnitude, but some non-trivial changes are required (see master branch). First, download servlet needs to be marked as asynchronous (OK, this is still trivial):


@WebServlet(urlPatterns = "/*", name="downloadServletHandler", asyncSupported = true)
public class DownloadServlet extends HttpRequestHandlerServlet {}

The main change occurs in download handler. Instead of sending the whole file in a loop with lots of waiting (takeBlocking()) involved, we are splitting the loop into separate iterations, each wrapped inside Callable. Now we will utilize a small thread pool that will be shared by all awaiting connections. Each task in the pool is very simple: instead of waiting for a token, it asks for it in a non-blocking fashion (tryTake()). If the token is available, piece of the file is sent to the client (sendChunkWorthOneToken()). If the token is not available (bucket is empty), nothing happens. No matter whether the token was available or not, the task resubmits itself to the queue for further processing (this is essentially very fancy, multi-threaded loop). Because there is only one pool, the task lands at the end of the queue allowing other connections to be served.


@Service
public class DownloadServletHandler implements HttpRequestHandler {

    @Resource
    private TokenBucket tokenBucket;

    @Resource
    private ThreadPoolTaskExecutor downloadWorkersPool;

    @Override
    public void handleRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        final File file = new File("/home/dev/tmp/ehcache-1.6.2.jar");
        response.setContentLength((int) file.length());
        final BufferedInputStream input = new BufferedInputStream(new FileInputStream(file));
        final AsyncContext asyncContext = request.startAsync(request, response);
        downloadWorkersPool.submit(new DownloadChunkTask(asyncContext, input));
    }

    private class DownloadChunkTask implements Callable<Void> {

        private final BufferedInputStream fileInputStream;
        private final byte[] buffer = new byte[TokenBucket.TOKEN_PERMIT_SIZE];
        private final AsyncContext ctx;

        public DownloadChunkTask(AsyncContext ctx, BufferedInputStream fileInputStream) throws IOException {
            this.ctx = ctx;
            this.fileInputStream = fileInputStream;
        }

        @Override
        public Void call() throws Exception {
            try {
                if (tokenBucket.tryTake(ctx.getRequest())) {
                    sendChunkWorthOneToken();
                } else
                    downloadWorkersPool.submit(this);
            } catch (Exception e) {
                log.error("", e);
                done();
            }
            return null;
        }

        private void sendChunkWorthOneToken() throws IOException {
            final int bytesCount = fileInputStream.read(buffer);
            ctx.getResponse().getOutputStream().write(buffer, 0, bytesCount);
            if (bytesCount < buffer.length)
                done();
            else
                downloadWorkersPool.submit(this);
        }

        private void done() throws IOException {
            fileInputStream.close();
            tokenBucket.completed(ctx.getRequest());
            ctx.complete();
        }
    }

}

I am leaving the details of Servlet 3.0 API, there are plenty of less sophisticated examples throughout the Internet. Just remember to call startAsync() and work with returned AsyncContext instead of plain request and response.

BTW creating a thread pool using Spring is childishly easy (and we get nice thread names as opposed to Executors and ExecutorService):


<task:executor id="downloadWorkersPool" pool-size="1"/>

That's right, one thread is enough to serve one hundred concurrent clients. See for yourself (the amount of HTTP worker threads is still 10 and yes, the scale is in milliseconds):

As you can see, response times when one hundred clients are downloading a file concurrently are only about 5% higher compared to the system with almost no load. Also response latencies aren't particularly harmed by increasing load. I can't push the server even further due to my limited hardware resources, but I have reasons to believe that this simple application would handle even twice as more connection: both HTTP threads and download worker thread weren't fully utilized during the whole test. This also means that we have increased our server capacity 10 times without even using all the threads!

Hope you enjoyed this article. Of course not every use case can be scaled so easily, but next time you'll notice your servlet is mainly waiting – don't waste HTTP threads and consider servlet 3.0 asynchronous processing. And test, measure and compare! The complete application source codes are available (look at different branches), including JMeter test plan.

Areas of improvement

There are still several places that require attention and improvement. If you want to, don't hesitate, fork, modify and test:

While profiling I discovered that in more than 80% of executions DownloadChunkTask does not acquire a token and only reschedules itself. This is an awful waste of CPU time that can be fixed quite easily (how?)
Consider opening a file and sending content length in a worker thread rather than in an HTTP thread (before starting asynchronous context)
How can one implement global limit on top of bandwidth limits per request? You have at least couple of choice: either limit the size of download workers pool queue and reject executions or wrap PerRequestTokenBucket with reimplemented GlobalTokenBucket (decorator pattern)
TokenBucket.tryTake() method does clearly violate Command-query separation principle. Could you suggest how it should look like to follow it? Why it is so hard?
I am aware that my test constantly reads the same small file, so the I/O performance impact is minimal. But in real life scenario some caching layer would have certainly be applied on top of disk storage. So the difference is not that big (now the application uses very small amount of memory, lots of place for cache)

Lessons learned

Loopback interface is not infinitely fast. In fact on my machine localhost was incapable of processing more than 80 MiB/s.
I don't use plain request object as a key in bucketSizeByRequestNo. First of all, there are no guarantees on equals() and hashCode() for this interface. And more importantly – read the next point...
With servlets 3.0 when processing the request you have to call completed() explicitly to flush and close the connection. Obviously after calling this method request and response objects are useless. What wasn't obvious (and I learned that the hard why) is that Tomcat reuses request objects (pooling) and some of their contents for subsequent connections. This means that the following code is incorrect and dangerous, possibly resulting in accessing/corrupting other requests' attributes or even session (?!?)


ctx.complete();
ctx.getRequest().getAttribute("SOME_KEY");

EDIT: Watch out for asynchronous executions timeouts. After creating an asynchronous invocation using startAsync() on Tomcat by default you have 30 seconds. After that Tomcat will kill your connection and getRequest() will suddenly start returning null (not very helpful). Luckily timeout can be customized and you can listen for timeout events easily (see this commit).

Spring framework without XML... At all!

2011-01-11T23:13:00.004+01:00

First, there was EJB 2.1 with countless XML files all over. It won't be such a big exaggeration to say that for every line of business code you had to create at least 10 lines of framework code and two pages of XML. Local and remote interfaces, manual JNDI lookup, triply nested try-catches, checked RemoteExceptions everywhere... this was enterprise. There were even tools to generate some of this boilerplate automatically.

Then couple of guys came and created Spring framework. After being forced to cast by obscure PortableRemoteObject.narrow() it was like taking a deep breath of fresh air, like writing poetry after working in coal mine. Time went by (BTW do you remember how many years ago was the last major JRE release?) and Sun learnt their lesson. EJB 3.0 was even simpler compared to Spring, XML-free, annotations, dependency injection. 3.1 was another great step toward simplicity, being more and more often compared to Spring. Logically current state of the art EJB specification might be considered as a subset of what Spring offers, I am actually surprised why there is no EJB spec. implementation in plain Spring (oh, wait...), considering its out-of-the-box support for JPA 1.0/2.0, JSR-250, JSR-330, JAX-WS/RS compatible solutions and others. But even though, Spring framework is nowadays perceived as a slow, heavyweight and hard to maintain, mainly due to reliance on XML descriptors. Once simple, now Spring is a whipping boy in the JEE framework battle.

I don't like politics, I won't defend my beloved framework writing lengthy essays. Instead I will take simple, but not trivial Spring application and quickly rewrite it so that it won't use XML. Not reduce the amount of XML, not leave only few untouchable lines. No XML - at all.

For the purposes of this article I created very simple Spring web application (base version under xml branch, final on master on my GitHub account) using JDBC, JMS and JMX, just not to make things trivial. Every change I made to the source code will be reflected in a separate commit to this repository. Step by step I will be removing XML configuration until there will be no Spring XML left. This is where we start:


<?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:tx="http://www.springframework.org/schema/tx"
       xmlns:amq="http://activemq.apache.org/schema/core"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
             http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.2.xsd
             http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:mbean-export />

    <bean id="fooService" class="com.blogspot.nurkiewicz.FooService">
        <property name="jmsOperations" ref="jmsTemplate" />
    </bean>

    <bean id="fooRequestProcessor" class="com.blogspot.nurkiewicz.FooRequestProcessor">
        <property name="fooRepository" ref="fooRepository" />
    </bean>

    <bean id="fooRepository" class="com.blogspot.nurkiewicz.FooRepository" init-method="init">
        <property name="jdbcOperations" ref="jdbcTemplate" />
    </bean>


    <!-- JDBC -->
    <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:~/workspace/h2/spring-noxmal;DB_CLOSE_ON_EXIT=FALSE;TRACE_LEVEL_FILE=4;AUTO_SERVER=TRUE" />
        <property name="username" value="sa" />
        <property name="password" value="" />
    </bean>

    <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
        <constructor-arg ref="dataSource" />
    </bean>

    <bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <constructor-arg ref="dataSource" />
    </bean>

    <tx:annotation-driven />


    <!-- JMS -->
    <bean id="jmsConnectionFactory" class="org.apache.activemq.pool.PooledConnectionFactory">
        <constructor-arg>
            <bean class="org.apache.activemq.ActiveMQConnectionFactory">
                <property name="brokerURL" value="tcp://localhost:61616" />
            </bean>
        </constructor-arg>
    </bean>

    <amq:queue id="requestsQueue" physicalName="requests" />

    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <constructor-arg ref="jmsConnectionFactory" />
        <property name="defaultDestination" ref="requestsQueue" />
    </bean>

    <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
        <property name="connectionFactory" ref="jmsConnectionFactory" />
        <property name="destination" ref="requestsQueue" />
        <property name="sessionTransacted" value="true"/>
        <property name="concurrentConsumers" value="5"/>
        <property name="messageListener">
            <bean class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
                <constructor-arg ref="fooRequestProcessor" />
                <property name="defaultListenerMethod" value="process"/>
            </bean>
        </property>
    </bean>

</beans>

Few user beans, JDBC including transaction support and utilizing JMS, both sending and receiving. The details of this application aren't that important: one of the beans is exposed via JMX, it sends JMS message, then that message is received and persisted in database.

The most commonly used and well established approach to reduce XML boilerplate in Spring is to use @Service and @Resource annotations together with introducing <context:component-scan/> for user beans (show changes):


<?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:tx="http://www.springframework.org/schema/tx"
       xmlns:amq="http://activemq.apache.org/schema/core"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
             http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.2.xsd
             http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:mbean-export />

    <context:component-scan base-package="com.blogspot.nurkiewicz"/>

    <!-- JDBC -->
    <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:~/workspace/h2/spring-noxmal;DB_CLOSE_ON_EXIT=FALSE;TRACE_LEVEL_FILE=4;AUTO_SERVER=TRUE" />
        <property name="username" value="sa" />
        <property name="password" value="" />
    </bean>

    <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
        <constructor-arg ref="dataSource" />
    </bean>

    <bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <constructor-arg ref="dataSource" />
    </bean>

    <tx:annotation-driven />


    <!-- JMS -->
    <bean id="jmsConnectionFactory" class="org.apache.activemq.pool.PooledConnectionFactory">
        <constructor-arg>
            <bean class="org.apache.activemq.ActiveMQConnectionFactory">
                <property name="brokerURL" value="tcp://localhost:61616" />
            </bean>
        </constructor-arg>
    </bean>

    <amq:queue id="requestsQueue" physicalName="requests" />

    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <constructor-arg ref="jmsConnectionFactory" />
        <property name="defaultDestination" ref="requestsQueue" />
    </bean>

    <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
        <property name="connectionFactory" ref="jmsConnectionFactory" />
        <property name="destination" ref="requestsQueue" />
        <property name="sessionTransacted" value="true"/>
        <property name="concurrentConsumers" value="5"/>
        <property name="messageListener">
            <bean class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
                <constructor-arg ref="fooRequestProcessor" />
                <property name="defaultListenerMethod" value="process"/>
            </bean>
        </property>
    </bean>

</beans>

10 lines less of XML, not very impressive... And what about user beans?


@Service
public class FooRepository {

    @Resource
    private JdbcOperations jdbcOperations;

    @PostConstruct
    public void init() {
        log.info("Database server time is: {}", jdbcOperations.queryForObject("SELECT CURRENT_TIMESTAMP", Date.class));
    }
    
    //...
    
}

Setters were replaced by annotations, init-method as well. Now what? Majority of annotation-enthusiasts stop here, but as you can see, there is plenty of XML left... The only problem is – how to annotate third-party classes like connection pools, Spring-provided support classes, etc.?

The real fun begins here. First we will get rid of the data source XML and replace it with... (show changes):


import javax.sql.DataSource;
import org.apache.commons.dbcp.BasicDataSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ContextConfiguration {

    @Bean
    public DataSource dataSource() {
        final BasicDataSource ds = new BasicDataSource();
        ds.setDriverClassName("org.h2.Driver");
        ds.setUrl("jdbc:h2:~/workspace/h2/spring-noxmal;DB_CLOSE_ON_EXIT=FALSE;TRACE_LEVEL_FILE=4;AUTO_SERVER=TRUE");
        ds.setUsername("sa");
        return ds;
    }

}

@Configuration, @Bean, dataSource(), what the...?!? It works exactly the way you think: Spring finds the ContextConfiguration class and examines all methods annotated with @Bean. Each and every method like that is treated equally to <bean...> XML declaration (there are even @Scope, @DependsOn and @Lazy annotations), so we can remove the dataSource bean declaration from XML. Actually, we can get rid of JdbcTemplate and transaction manager as well (show changes):


@Bean
public JdbcOperations jdbcOperations() {
    return new JdbcTemplate(dataSource());
}

@Bean
public PlatformTransactionManager transactionManager() {
    return new DataSourceTransactionManager(dataSource());
}

Look closely how easily one can inject data source bean to other beans. You have a method that creates data source on one hand, on the other hand two methods require data source to be injected (JdbcTemplate and transaction manager). It can't be easier, this is probably the way your girlfriend would implement dependency injection (Guice, anyone?)

One thing should bother you though... If you call dataSource() twice, wouldn't this mean that you have just created two separate, independent DataSource instances? Clearly not what was intended... Well, it bothered me (see comments), but it seems that once again Spring is a one clever beast. Not finding @Scope annotation it assumes data source should be a singleton. So it applies some CGLIB-proxying-magic around dataSource() method transparently and protects it from being called more than once. Or, more precisely, you think you can call it many times, but all subsequent calls will return already factored bean, not even reaching the actual implementation. Nice!

All in all, this shortened our XML configuration to this:


<?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:tx="http://www.springframework.org/schema/tx"
       xmlns:amq="http://activemq.apache.org/schema/core"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
             http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.2.xsd
             http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:mbean-export />

    <context:component-scan base-package="com.blogspot.nurkiewicz"/>

    <!-- JDBC -->
    <tx:annotation-driven />

    <!-- JMS -->
    <bean id="jmsConnectionFactory" class="org.apache.activemq.pool.PooledConnectionFactory">
        <constructor-arg>
            <bean class="org.apache.activemq.ActiveMQConnectionFactory">
                <property name="brokerURL" value="tcp://localhost:61616" />
            </bean>
        </constructor-arg>
    </bean>

    <amq:queue id="requestsQueue" physicalName="requests" />

    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <constructor-arg ref="jmsConnectionFactory" />
        <property name="defaultDestination" ref="requestsQueue" />
    </bean>

    <bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
        <property name="connectionFactory" ref="jmsConnectionFactory" />
        <property name="destination" ref="requestsQueue" />
        <property name="sessionTransacted" value="true"/>
        <property name="concurrentConsumers" value="5"/>
        <property name="messageListener">
            <bean class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
                <constructor-arg ref="fooRequestProcessor" />
                <property name="defaultListenerMethod" value="process"/>
            </bean>
        </property>
    </bean>

</beans>

You my stop now and think how would you rewrite the remaining XML-defined beans into Java. Don't worry, there is no catch here – it as straightforward as it should be (see changes).


@Bean
public ConnectionFactory jmsConnectionFactory() {
    final ActiveMQConnectionFactory factory = new ActiveMQConnectionFactory();
    factory.setBrokerURL("tcp://localhost:61616");
    return new PooledConnectionFactory(factory);
}

@Bean
public Queue requestsQueue() {
    return new ActiveMQQueue("requests");
}

@Bean
public JmsOperations jmsOperations() {
    final JmsTemplate jmsTemplate = new JmsTemplate(jmsConnectionFactory());
    jmsTemplate.setDefaultDestination(requestsQueue());
    return jmsTemplate;
}

Declaration of DefaultMessageListenerContainer contains some anonymous inner bean, that is being used only once within parent bean. So private method is OK (see changes):


@Bean
public AbstractJmsListeningContainer jmsContainer() {
    final DefaultMessageListenerContainer container = new DefaultMessageListenerContainer();
    container.setConnectionFactory(jmsConnectionFactory());
    container.setDestination(requestsQueue());
    container.setSessionTransacted(true);
    container.setConcurrentConsumers(5);
    container.setMessageListener(messageListenerAdapter());
    return container;
}

private MessageListenerAdapter messageListenerAdapter() {
    final MessageListenerAdapter adapter = new MessageListenerAdapter(fooRequestProcessor);
    adapter.setDefaultListenerMethod("process");
    return adapter;
}

Not much to be said, mainly because Spring plain Java configuration is so trivial and straightforward – and the code may speak for itself. In case you've got lost, after so many transformations we are now here:


<?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:tx="http://www.springframework.org/schema/tx"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd
             http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:mbean-export />

    <context:component-scan base-package="com.blogspot.nurkiewicz"/>

    <tx:annotation-driven />

</beans>

To be honest, it wasn't very hard, but the remaining few lines of XML were especially difficult to remove. Believe me, you don't want to go the same path I had to choose to replace these nice little namespace-powered declarations. But after several minutes, few unsuccessful experiments and lots of Spring code reviewed I finally removed JMX (see changes) and transaction (see changes) declarations. Looks innocent and I am glad you won't have to dig through Spring code base to reinvent it:


@Bean
public AnnotationMBeanExporter annotationMBeanExporter() {
    return new AnnotationMBeanExporter();
}

@Bean
public TransactionAttributeSource annotationTransactionAttributeSource() {
    return new AnnotationTransactionAttributeSource();
}

@Bean
public TransactionInterceptor transactionInterceptor() {
    return new TransactionInterceptor(transactionManager(), annotationTransactionAttributeSource());
}

This would be it. All we have left is this tiny XML bootstrap declaration that instructs Spring where to find all of the beans and web.xml snippet making web container to actually start the Spring application context:


<context:component-scan base-package="com.blogspot.nurkiewicz"/>


<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

</web-app>

There is no other way to start Spring properly in web-environment, after all you have to make the web-container aware of the Spring framework somehow. I know, I know, I promised no XML at all. So I lied, I'm sorry, OK? Big deal... Wait, wait, just kidding :-), we will get rid of this bootstrap XML completely in seconds. Well, depending how fast can you download the newest Tomcat 7 or other JSR 315 (among insiders known as Servlet 3.0) capable web container...

Web fragments is a technology allowing seamless integration of various web frameworks with servlet containers. If you worked with several frameworks, they all require registering specific servlet, filter or listener in web.xml. Most of the time this is the only servlet dependency and Spring is no exception. The idea behind web fragments tries to liberate the end developers from this requirement. Servlet 3.0 compatible container should scan all JARs within /WEB-INF/lib directory in WAR artifact and if any JAR contains web-fragment.xml file inside its /META-INF directory, it will be included in final web.xml.

You realize where I am going? What if we could create such a small web-fragment JAR only for XML-free Spring startup? This is the typical, far from complete WAR file structure:


.
|-- META-INF
`-- WEB-INF
    |-- classes
    |   |-- com
    |   |   `-- blogspot
    |   |       `-- nurkiewicz
    |   |           |-- ContextConfiguration.class
    |   |           |-- FooRepository.class
    |   |           |-- FooRequestProcessor.class
    |   |           |-- FooService$1.class
    |   |           `-- FooService.class
    |   `-- logback.xml
    |-- lib
    |   |-- spring-web-3.0.5.RELEASE.jar
    |   |-- spring-web-fragment-0.0.1-SNAPSHOT.jar
    |   |   `-- META-INF
    |   |       |-- MANIFEST.MF
    |   |       |-- web-fragment-context.xml
    |   |       `-- web-fragment.xml
    |   `-- spring-beans-3.0.5.RELEASE.jar
    `-- web.xml

The sole purpose of spring-web-fragment-*.jar is to provide web-fragment.xml file for the container, being the bootstrap between servlet environment and Spring framework:


<web-fragment xmlns="http://java.sun.com/xml/ns/javaee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
              version="3.0">

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath*:/META-INF/web-fragment-context.xml</param-value>
    </context-param>

</web-fragment>

One new element is the explicitly defined web-fragment-context.xml Spring context file. We cannot use the default location in the WAR file (/WEB-INF/applicationContext.xml), as this file no longer exists (!) But our tiny fragment JAR seems to be the best place for it:


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       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.xsd
       ">

    <context:component-scan base-package="." />

</beans>

Package declaration "." looks disturbing. This is very unfortunate but I tried to workaround the requirement of defining at least one package there. This requirement is probably for a reason (I guess scanning the full CLASSPATH takes some time), but I couldn't just put my own package, as I would have to change this declaration for every single project. But this would violate the biggest advantage of web-fragment approach – once you create this empty JAR with two tiny XML files, you can use it for all your projects. All you have to do is to add this JAR into your WAR's libraries and start annotating POJOs with @Service (and/or use @Configuration).

If such an utility artefact is going to be ever available out-of-the-box along other Spring dependencies (if you like the idea, vote), beginners might enjoy their Spring-journey right from the moment of adding Spring in pom.xml. In fact, pom.xml can now be written in different languages, as well as logback.xml. Look ma, no XML! Are you convinced? Do you prefer XML or Java? Or Groovy? Please, don't answer. Spring gives you the choice to be as lightweight and as simple as you want it to be. Without oversimplification and cutting off more advanced functionalities.

Update [25.01.2011]: Russian translation by Alexander Belotserkovsky is available.

Activiti processes and executions explained

2011-01-08T17:45:00.001+01:00

I was interested in Activiti process engine long before it reached its first stable 5.0 version. Now, when 5.1 was released, I decided to play a bit with this framework, especially paying attention to Spring and JUnit support. But one of the first impediments encountered was the difference between process instance and execution, as well as between sub process and call activity. I am hoping after reading this article you won't encounter the same problems when starting with Activiti.

As you know, even a monkey can learn a new Java framework after reading documentation, but the real fun comes when you meet the technology by studying its source code (often tracking bugs and looking for solutions). And I must admit that Activiti code-base was a pleasure to read, nicely structured and designed. For some reason it is not deployed to Alfresco's repository, so to take full advantage of your BPMN journey, start by:


svn co http://svn.codehaus.org/activiti/activiti/tags/activiti-5.1
cd activiti-5.1
mvn install source:jar -DskipTests -Pdistro

OK, for starters take a look at this process:

As you can probably guess, + signs symbolize places where process splits up (forks) into two or more concurrent paths or joins concurrent paths back. All you need to know is that until every path created in fork activity reaches corresponding join activity, all the paths that reached the join earlier must wait for the last one to come. If you thought about barrier pattern in thread synchronization, you got the idea. You might also wonder why forks and joins in this process are asymmetric (there is no Join B corresponding to Fork B). First of all, I wanted to show that the process will still work with such a flow. And actually, it won't work with obvious symmetric approach, see bug ACT-482.

Never mind, let's do some coding! Activiti has excellent support for JUnit (but don't you dare calling this unit testing!) thanks to @Deployment annotation. But I can't imagine running processes without Spring support (also very good in Activiti), so I started directly from Spring integration test. First context file:


<bean id="dataSource" class="org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy">
    <property name="targetDataSource">
        <bean class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
            <property name="driverClassName" value="org.h2.Driver" />
            <property name="url" value="jdbc:h2:~/workspace/h2/activiti;DB_CLOSE_ON_EXIT=FALSE;TRACE_LEVEL_FILE=4" />
            <property name="username" value="sa" />
            <property name="password" value="" />
        </bean>
    </property>
</bean>

<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource" />
</bean>

<!-- Workaround to http://jira.codehaus.org/browse/ACT-473 -->
<bean id="initProcessEngines" class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
    <property name="staticMethod" value="org.activiti.engine.ProcessEngines.init"/>
</bean>
<bean id="processEngine" class="org.activiti.spring.ProcessEngineFactoryBean" depends-on="initProcessEngines">
    <property name="processEngineConfiguration">
        <bean class="org.activiti.spring.SpringProcessEngineConfiguration">
            <property name="databaseType" value="h2" />
            <property name="dataSource" ref="dataSource" />
            <property name="transactionManager" ref="transactionManager" />
            <property name="databaseSchemaUpdate" value="none" />
            <property name="jobExecutorActivate" value="false" />
            <property name="deploymentResources" value="classpath*:/com/blogspot/nurkiewicz/tryipad2/bpmn20/*.bpmn20.xml" />
        </bean>
    </property>
</bean>

For unit testing you should rather use in-memory database and set databaseSchemaUpdate to create; fortunately H2 works perfectly as in-memory, standalone and TCP-enabled server. Also it's the default database for Activiti and Grails projects is moving onto it. So what are you waiting for?

The configuration is anything but complicated, just creating ProcessEngine instance using factory bean. This is the central engine class, exposing several convenient services to the user. To make access to them easier, add the following beans as well:


<bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
<bean id="runtimeService" factory-bean="processEngine" factory-method="getRuntimeService" />
<bean id="taskService" factory-bean="processEngine" factory-method="getTaskService" />
<bean id="historyService" factory-bean="processEngine" factory-method="getHistoryService" />
<bean id="managementService" factory-bean="processEngine" factory-method="getManagementService" />

Did you noticed deploymentResources attribute of factory bean? It instruct process engine to search given directory and automatically open, parse and deploy processes found there. Unfortunately Activiti can't handle PNG process diagrams, but it speaks BPMN 2.0 natively. Here is the same process in this language:


<process name="ForkJoin" id="ForkJoin" isExecutable="false">
    <startEvent id="Start" name="Start"/>
    <userTask id="Task_0" name="Task 0"/>
    <parallelGateway gatewayDirection="Diverging" id="Fork_AB" name="Fork AB"/>
    <userTask id="Task_A" name="Task A"/>
    <userTask id="Task_B" name="Task B"/>
    <parallelGateway gatewayDirection="Diverging" id="Fork_B" name="Fork B"/>
    <userTask id="Task_B1" name="Task B1"/>
    <parallelGateway gatewayDirection="Converging" id="Join_B" name="Join B"/>
    <userTask id="Task_B2" name="Task B2"/>
    <parallelGateway gatewayDirection="Converging" id="Join_AB" name="Join AB"/>
    <userTask id="Task_C" name="Task C"/>
    <endEvent id="End" name="End"/>

    <sequenceFlow id="Flow_2" name="" sourceRef="Fork_AB" targetRef="Task_A" />
    <sequenceFlow id="Flow_5" name="" sourceRef="Fork_AB" targetRef="Task_B" />
    <sequenceFlow id="Flow_7" name="" sourceRef="Task_B" targetRef="Fork_B" />
    <sequenceFlow id="Flow_0" name="" sourceRef="Fork_B" targetRef="Task_B1" />
    <sequenceFlow id="Flow_1" name="" sourceRef="Fork_B" targetRef="Task_B2" />
    <sequenceFlow id="Flow_11" name="" sourceRef="Task_B1" targetRef="Join_AB" />
    <sequenceFlow id="Flow_10" name="" sourceRef="Task_B2" targetRef="Join_AB" />
    <sequenceFlow id="Flow_4" name="" sourceRef="Task_A" targetRef="Join_AB" />
    <sequenceFlow id="Flow_8" name="" sourceRef="Join_AB" targetRef="Task_C" />
    <sequenceFlow id="Flow_12" name="" sourceRef="Task_C" targetRef="End" />
    <sequenceFlow id="Flow_9" name="" sourceRef="Start" targetRef="Task_0" />
    <sequenceFlow id="Flow_6" name="" sourceRef="Task_0" targetRef="Fork_AB" />
</process>

Maybe it's not that kind of format you'd love, but on the other hand I won't insult your intelligence explaining it. It becomes even more obvious when compared with process diagram above. By the way keep this diagram and BPMN description open on your second display (I bet you have it!), it will be easier to follow the test case.


import static org.fest.assertions.Assertions.assertThat;
import org.activiti.engine.RuntimeService;
import org.activiti.engine.runtime.ProcessInstance;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:/com/blogspot/nurkiewicz/tryipad2/activiti/ActivitiTestCase-context.xml")
public class ForkJoinTest {

    @Resource
    private RuntimeService runtimeService;

    @Test
    public void shouldRunConcurrently() throws Exception {
        final ProcessInstance process = runtimeService.startProcessInstanceByKey("ForkJoin");
        final String pid = process.getId();
        //...
    }
}

Using RuntimeService, one of the services provided by ProcessEngine, we start new process instance. You can use either process key (name) or process id. The latter allows you to specify exact process definition version, while using process key will always result in starting the latest version. Yes, Activiti supports seamless process versioning. And yes, it's similarities to jBPM are almost to evident – but that's not a secret.

Now when our process is started, we might manipulate it and perform some assertions. And remember: the process was not only created, but it started. This means that calling startProcessInstanceByKey() is blocking and it will return only when process engine has nothing more to do (for instance, it reached user task which requires user interaction). This is the case in our project, the first activity after start is user Task 0:


log.debug("Waiting in Task 0");
assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_0");

Now Activiti waits for user confirmation (this might be a particular user, group or anyone) to proceed further. But before doing so, let's go one step back. We have created one process instance, and every process instance is some type of execution. This terminology will be extremely important when we go into Activiti querying API:


//only one execution
assertThat(
        runtimeService
                .createExecutionQuery()
                .processInstanceId(pid)
                .list()
).hasSize(1);

We were looking here for all executions belonging to process with given id. Now when we are sure that there is only one execution (it is the process itself), we should quickly move forward:


log.debug("Signaling advances to Task A and B concurrently");
runtimeService.signal(pid);
assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_A", "Task_B");

//three execution
assertThat(
        runtimeService
                .createExecutionQuery()
                .processInstanceId(pid)
                .list()
).hasSize(3);

Are you looking at the process graph on the second display like I told you to do? After signalling the process it moved forward to Task A and Task B. And, same as with Task 0, it waits for our interactions. But also notice, that we already have three executions! Two executions are representing two concurrent paths (nomen est omen!) of execution, while the remaining third execution is the process itself. And the process waits until Join AB is reached to get the control back.

So let's push Task A further. By the way don't get the false impression that process engine is only about stopping and waiting for being pushed manually – it's just silly hello forked world example, we'll dive deeper into more comprehensive examples later. Now we must learn the basics. Where was I?


final Execution forkA = runtimeService
        .createExecutionQuery()
        .activityId("Task_A")
        .processInstanceId(pid)
        .singleResult();
log.debug("Found forked execution {} in Task A activity for process {}", forkA, pid);

runtimeService.signal(forkA.getId());
log.debug("Advanced fork A, waiting in Join AB");
assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_B");

//no active activities in fork A since waiting in join
assertThat(runtimeService.getActiveActivityIds(forkA.getId())).isEmpty();

Lots of exciting things happen here (unless, which I can hardly believe, you don't find Java BPMN process engine in action exciting). First we found (via Activiti ExecutionQuery) exactly one execution that belongs to given process and waits in activity Task A. Then we pushed it further as previously. But what about active activities? Seems like execution representing Task A doesn't have any (?), while the whole process has only one (Task B) active activity available. How come? The Javadocs state precisely, that executions becomes inactive (i.e. it has no active activity) when one of the following occurs:

an execution enters a nested scope

an execution is split up into multiple concurrent executions, then the parent is made inactive.

an execution has arrived in a parallel gateway or join and that join has not yet activated/fired.

an execution is ended.

Because the execution after leaving Task A activity reached Join AB as first out of three parties, it waits for the remaining two, making its execution inactive. The main process execution is inactive as well, waiting for Join AB. Understanding this behaviour is essential when it comes to testing parallel process executions. If you aren't convinced, look at Activiti logs:


Leaving activity 'Task_A'
ConcurrentExecution[12256734] takes transition (Task_A)--Flow_4-->(Join_AB)
ConcurrentExecution[12256734] executes Activity(Join_AB): org.activiti.engine.impl.bpmn.ParallelGatewayActivity
parallel gateway 'Join_AB' does not activate: 1 of 3 joined

Let us make branch A wait no more and advance branch B the same way we already exercised. Look at the process graph and think for a while, how many executions will exist then? How many of them are active? And which activities are active?


final Execution forkB = runtimeService.createExecutionQuery()
        .activityId("Task_B")
        .processInstanceId(pid)
        .singleResult();
log.debug("Found forked execution {} in Task B activity for process {}", forkB, pid);

runtimeService.signal(forkB.getId());
log.debug("Advanced fork B, waiting in concurrent activities B1 and B2");

assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_B1", "Task_B2");

Now we will push forward executions waiting in Task B1 and B2:


final Execution forkB1 = runtimeService
        .createExecutionQuery()
        .processInstanceId(pid)
        .activityId("Task_B1")
        .singleResult();
assertThat(forkB1).isNotNull();
assertThat(runtimeService.getActiveActivityIds(forkB1.getId())).containsOnly("Task_B1");

final Execution forkB2 = runtimeService
        .createExecutionQuery()
        .processInstanceId(pid)
        .activityId("Task_B2")
        .singleResult();
assertThat(forkB2).isNotNull();
assertThat(runtimeService.getActiveActivityIds(forkB2.getId())).containsOnly("Task_B2");

log.debug("Found forked executions {} and {} in B1/B2 activities accordingly ", forkB1, forkB2);

...signalling:


runtimeService.signal(forkB1.getId());
assertThat(runtimeService.getActiveActivityIds(forkB1.getId())).isEmpty();
assertThat(runtimeService.getActiveActivityIds(forkB2.getId())).containsExactly("Task_B2");
assertThat(runtimeService.getActiveActivityIds(forkA.getId())).isEmpty();

log.debug("Signalling fork B2 will activate Join AB");
runtimeService.signal(forkB2.getId());

assertThat(
        runtimeService
                .createExecutionQuery()
                .executionId(forkA.getId())
                .singleResult()
).isNull();
assertThat(
        runtimeService
                .createExecutionQuery()
                .executionId(forkB1.getId())
                .singleResult()
).isNull();
assertThat(
        runtimeService
                .createExecutionQuery()
                .executionId(forkB2.getId())
                .singleResult()
).isNull();
assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_C");

...and logs:


final Execution forkB = runtimeService.createExecutionQuery()
        .activityId("Task_B")
        .processInstanceId(pid)
        .singleResult();
log.debug("Found forked execution {} in Task B activity for process {}", forkB, pid);

runtimeService.signal(forkB.getId());
log.debug("Advanced fork B, waiting in concurrent activities B1 and B2");

assertThat(runtimeService.getActiveActivityIds(pid)).containsOnly("Task_B1", "Task_B2");

As you can see when execution containing Task B1 reached join activity, nothing happened since the join waits for three executions to join. But when the remaining execution (the one containing Task B2) finally made it, Join AB breaks and after so many tiring steps we are waiting at the last Task C.

Now there is only one execution associated with the process back again. Finishing the process while waiting in Task C is trivial


assertThat(
        runtimeService
                .createExecutionQuery()
                .processInstanceId(pid)
                .list()
).hasSize(1);
log.debug("Signalling Task C to finish the process");
runtimeService.signal(pid);

assertThat(
        runtimeService
                .createProcessInstanceQuery()
                .processInstanceId(pid)
                .singleResult()
).isNull();

Fully understanding the difference between process and execution is essential to understand and take advantage of fork/join parallelism. Also it is important to use runtime querying API effectively. You must remember that ProcessInstanceQuery is used to query process instances (duh!) (we've created only a single process instance throughout this test) by process id, while ExecutionQuery allows to find executions (we've created several executions during the test, including the process itself). Execution query is more powerful, as it enables you to find all executions associated with the given process (and also the process itself), executions in a given activity, etc. Both queries can be created using RuntimeService.

I hope you have a general idea how Activiti manages process execution and how to test it. Full source code of the test case is available, as well as the whole working Maven project. In the next article I will explain call activities and sub processes, but prepare to dive into much more interesting case studies soon.

Speeding up Spring integration tests

2010-12-19T21:32:00.001+01:00

The biggest problem with unit testing using Spring testing support* is the time it takes to initialize the Spring framework context. Every new test case adds precious seconds to overall build time. After a while it will take minutes or even hours to fully build the application, while most of this time is consumed by Spring itself. But we'll start from the basics.

In order to make JUnit aware of Spring framework test support, simply add these annotations on test case class:


@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@Transactional
public class MainControllerTest {
    //...
}

While @Transactional is not necessary, it will greatly simplify testing when database is involved (details here). In IntelliJ IDEA 10 (I just took this brand new version for a test drive) these annotations will raise the following error to occur:

And suggested solution:

You now have two options: either create the file named the same as your test case with -context.xml suffix (and in the same package) as suggested or use different file and specify its name explicitly using locations attribute to @ContextConfiguration. Following convention over configuration for now I recommend you to follow the Spring naming convention. When using Maven, your class under test should reside in src/main/java, test case in src/test/java and Spring configuration file in src/test/resources (but see IDEA-61829):


pom.xml
src
|-- main
|    -- java
|       `-- com
|           `-- blogspot
|               `-- nurkiewicz
|                   `-- spring
|                       `-- test
|                           `-- web
|                               `-- MainController.java
`-- test
    |-- java
    |   `-- com
    |       `-- blogspot
    |           `-- nurkiewicz
    |               `-- spring
    |                   `-- test
    |                       `-- web
    |                           `-- MainControllerTest.java
    `-- resources
         -- com
            `-- blogspot
                `-- nurkiewicz
                    `-- spring
                        `-- test
                            `-- web
                                `-- MainControllerTest-context.xml

In case you'll get lost, IDEA provides magnificent Packages view in Project explorer:

As you can see files in different physical directories are all located in the same logical directory corresponding to the package. This is especially useful when working with Wicket web framework, where each page class must have equivalent HTML file, preferably in src/main/resources.

Coming back to Spring. When running the test case, Spring runner will automatically open the *-context.xml file and initialize the application context described in this file. The context will typically contain class under test bean definition along with its direct dependencies. Now you can inject every bean from the context directly to your test case class:


@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class MainControllerTest {

 @Resource
 private MainController mainController;

 @Test
 public void smokeTest() throws Exception {
  //mainController...
 }

}

The important thing to remember is that spring context will be initialized prior the first test method is executed and (unless you use @DirtiesContext annotation) will be reused (rather than recreated) for every subsequent test method in this test case. This is a way of decreasing the test execution time. Although it is a myth that Spring context initialization takes so much time, but some of your own beans might increase this time significantly. For instance Hibernate/JPA persistence providers or embedded ActiveMQ server are huge facilities taking several seconds to boot up. This is the major drawback of Spring tests, making many developers reluctant to them.

What we recently discovered is that Spring out of the box supports reusing once initialized context even in different test case classes across your artifact. This means that in best case scenario you pay the price of context startup only once and use the same context across all your tests, making startup time less relevant and insignificant compared to the overall build time.

In order to benefit from this feature, you must forget everything I said about convention over configuration. Now every test case has its own context configuration file, treated as independent application context. But if you reuse the same file in every test case, Spring will figure out that every test case points to the same file and simply reuse the context as well, for example:


@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:test-context.xml")
@Transactional
public class MainControllerTest {
    //...
}

//...

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:test-context.xml")
@Transactional
public class BarRepositoryTest {
    //...
}

//...

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:test-context.xml")
@Transactional
public class BarServiceTest {
    //...
}

//...

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:test-context.xml")
@Transactional
public class FooRepositoryTest {
    //...
}

//...

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:test-context.xml")
@Transactional
public class FooServiceTest {
    //...
}

By the way if you are disgusted by the annotations repetition, inheritance comes to the rescue.

There are few consequences of single vs. specialized context for every test case. First of all, the single context must be suitable for each and every test case, which means it must contain all beans being tested (effectively: almost whole application). This means that even though the complete build will be much faster, running a separate test case will cost you much more time. But there is a workaround for that as well. In your complete test context simply declare:


<beans default-lazy-init="true">

This will cause loading only these beans, that are necessary in this particular test. And when running a full test suite, all beans will be lazily initialized one after another. In one context per test case approach each test context has only carefully chosen, fine grained beans. In single context you must have all the beans declared, but thanks to lazy loading not all of them will be created when not needed.

To sum things up. In order to get the most of your Spring integration testing, take your production application context, mocking only necessary dependencies like database or JMS. Thanks to that you will avoid repeating the bean definitions in production and test XML context files. Once having one, master test context, point to it in every test case to make efficient use of Spring context caching. Happy testing!

* Even bigger problem is that such tests shouldn't be considered as unit tests at all, as they test system as a whole rather than separate class (unit). That is why you should consider Spring-powered tests as integration tests and treat them as complementary to unit tests rather than their substitution.

Functional Java Developers’ Day 2010

2010-10-17T16:39:00.001+02:00

Ted Newards’ talk about functional programming in Java and his workshop on Scala (hence the article title) were the most memorable events during the third JDD conference that I attended last week. Sadly most memorable, and almost the only ones. But first things first.

After spending endless hours with great Enterprise JavaBeans 3.0 book by Bill Burke I’ve expected something fabulous, but Bills’ lecture about JAX-RS was just average, with no coding, only plain API introduction. Scott Davis' presenting REST and ROA last year was way much better. Thankfully Angelika Langer talk about Java concurrency pitfalls was much more interesting, although one might argue that she just gave a summary of marvelous Java Concurrency in Practice book, that I have recommended long time ago. One new thing I’ve learnt is that updating volatile variable guarantees all other non-volatile variable updated earlier by the same thread to be visible by other threads, as if they were volatile as well (are you following?) After Angelika there was a talk about Java performance testing, but I had a copy of The Art of Application Performance Testing book in my knapsack, so the presentation didn’t caught a lot of my attention.

After delicious lunch Ted Neward gave a talk on functional programming concepts in Java. Charismatic, entertaining, surprising – I knew he will make a great show. In the middle of third or fourth slide he asked innocently who prefers slides to live coding and after finding no such person on the audience, he instantly closed the presentation and opened notepad, writing some Java code from scratch. It looked so natural that I almost believed that he actually had any slides further – but of course this was all set up. Ted mentioned Functional Java library as a way to enable functional style of programming in plain old Java. Another libraries I can point out if you have to stick with this language are: Fun4J, Google's Guava and LambdaJ. Also take a look at Lombok to write more concise POJOs.

I’ve seen Piotr Walczyszyn several times evangelizing Flex and AIR so it came a bit of a surprise that I really enjoyed his talk, even though I don’t like front-end programming. But a real surprise was the Linda Rising presentation dealing with the problem of introducing change and convincing our coworkers to it. From time to time we need to look at our job from 10,000 ft perspective, see how ridiculously we sometimes behave and how irrational our choices are. See Pragmatic Thinking and Learning... for a more in-depth analysis on this. Also I recently read marvelous Dreaming in Code by Scott Rosenberg. Linda’s talk complemented these books excellently.

On the next day I sacrificed three presentations to participate in Ted Neward’s workshop on Scala – continuing the subject of functional programming. He introduced Scala language step by step, emphasizing the differences and commons misconceptions. I will repeat after him: Scala is compiled, statically typed, consistent language, don’t compare it with Groovy, these are completely different tools. I was doing my best to follow Ted’s examples on my computer and finally I wrote few simple (compiling!) lines of Scala code. Too bad my first presentation on Scala (during GeeCON 2009) by Luc Duponcheel wasn’t that good and simply beyond my comprehension. Here are few examples of Scala concepts that significantly caught my attention. POJO in Scala:


import org.apache.commons.lang.builder._

class Book(author: String, title: String, year: Int) {

  override def toString =
    new ToStringBuilder()
      .append("author", author)
      .append("title", title)
      .append("year", year)
      .toString()
}

Please note few things. Firstly, interacting with Java libraries (Apache Commons Lang in this example) is straightforward. Secondly all the types are objects, including primitives (Int – consistency!) But the most important issue is: where are the fields?!? Scala compiler (scalac) is a one clever beast: after finding constructor arguments and variables used in toString() method matching them it figured out that the programmer’s intention was to assign constructor arguments to fields so that toString() can use these fields afterwards. Here is the proof:


//javap -private Book

Compiled from "Book.scala"
public class Book extends java.lang.Object implements scala.ScalaObject{
    private final java.lang.String author;
    private final java.lang.String title;
    private final int year;
    public java.lang.String toString();
    public Book(java.lang.String, java.lang.String, int);
}

And a better proof if you are bytecode-capable:


//javap -c Book
//...

public Book(java.lang.String, java.lang.String, int);
  Code:
   0:   aload_0
   1:   aload_1
   2:   putfield        #28; //Field author:Ljava/lang/String;
   5:   aload_0
   6:   aload_2
   7:   putfield        #35; //Field title:Ljava/lang/String;
   10:  aload_0
   11:  iload_3
   12:  putfield        #38; //Field year:I
   15:  aload_0
   16:  invokespecial   #49; //Method java/lang/Object."<init>":()V
   19:  return

}

Need getters? Prepend every constructor argument with val keyword. Setters as well? Replace val (value) with var (variable). No boilerplate code, no code generation needed. Second more comprehensive example is Scala’s match operator:


def capitalizeAfterHash(list: List[Char]): List[Char] =
  list match {
    case '#' :: rest =>
      rest.map(_.toUpper)
    case _ :: rest =>
      capitalizeAfterHash(rest)
    case Nil =>
      Nil
  }

println(capitalizeAfterHash('a' :: 'b' :: '#' :: 'c' :: 'd' :: Nil))
println(capitalizeAfterHash('#' :: 'c' :: 'd' :: Nil))
println(capitalizeAfterHash('a' :: 'b' :: Nil))

Match is like switch on steroids. In this example it is used to match list of characters against some patterns. The last case means: "if list is empty (Nil), return empty list." The first case states: "if the first element of the list is ‘#’, take the rest of the list and call toUpper() on every item ("_" placeholder)". Finally the second case is: "if the first element of the list has any value (except ‘#’ examined earlier), call recursively capitalizeAfterHash with the rest of the list (effectively: repeat without the first element)". Can you guess what does this function do?

Scala is not for everybody and you need to have some solid programming background to fully appreciate its expressiveness. I don’t think I will choose Scala from my toolbox anytime soon, but I will definitely follow this language development. Actually, after observing what is currently happening with JDK 7 (and 8...) I will say loudly: "Java (the language) is dead, long live Java (the JVM)". Some time ago Sun was waiting for so long to develop new, easier and more productive version of their EJB 2.1 standard that competitors came up with much better, although non-standard solutions (think: Spring). Now the same thing is happening with Java (the language) and other JVM languages. That’s why interoperability between new JVM languages and Java code is so important: one day we will end up with tons of legacy code in (dead) Java language (because Sun/Oracle was too reluctant to update the language; see F#, LINQ, etc.), adding new features and rewriting parts of old systems in new, dynamic and more productive languages. JVM is great, but one day Java will become only a historic language, reference and exemplary implementation, not used anymore. Like reference counting as a way of implementing garbage collection.

Where was I? Oh, JDD 2010. To be honest, nothing interesting happened after marvelous Ted Neward’s workshop. At least two presentations were extremely boring, but I had no choice, as there was only one track. Actually, if we exclude workshops, the amount of presentations was comparable to last year, even though the conference lasted for 2 days in the contrary to one day in 2009. But last year there were two independent tracks. So the conference was two times longer (which was the biggest demand of the participants last year, including myself) but introduced similar number of presentations – nice marketing trick! The second demand was to change the place where the conference was taking place last year (sports hall with plastic chairs? C'mon!) Seems like this suggestion was somehow missed...

Thankfully I attended very interesting presentations by Ted Neward, Linda Rising and Angelika Langer. Without them I would be somewhat disappointed by this year’s Java Developers’ Day. Main tips for organizers: find a comfortable conference centre and don’t force people to attend sponsored talks. And don’t stop! As still JDD is a great event with lots of potential.

Testing for exceptions in JUnit revised

2010-09-25T21:13:00.004+02:00

In his recent post the author of fantastic mocking framework Mockito collected few rules about testing exceptions. What caught my attention is the advice to use JUnit rules (nomen est omen!) for testing exceptions. ExpectedException rule gathers advantages of both expected @Test attribute clarity and try-catch strictness. Here is the example:


public class DefaultFooServiceTest {

 private FooService fooService = new DefaultFooService();

 @Rule
 public ExpectedException exception = new ExpectedException();

 @Test
 public void shouldThrowNpeWhenNullName() throws Exception {
  //given
  String name = null;

  //when
  exception.expect(NullPointerException.class);
  fooService.echo(name);

  //then
 }

}

Szczepan claims that ExpectedException fits into given/when/then test template nicely. I disagree! Look at the code snippet above – what is the most natural place to put assertions on exception being thrown? From the obvious reasons it must be the last line before the line that actually throws the exceptions. So you have a choice to put assertion as the last statement in given block or as first in when block. You are right, this is how this test should look like in an ideal world:


@Test
public void shouldThrowNpeWhenNullName() throws Exception {
 //given
 String name = null;

 //when
 fooService.echo(name);

 //then
 exception.expect(NullPointerException.class);
}

No we’re talking! There’s just this tiny problem with example above – we expect code in when block to throw an exception and put assertions afterwards in then block. See the problem? If we could somehow transparently catch the exception, store it somewhere, return normally and let assertions to run against it... With AOP it is actually pretty easy, but I wanted to implement this feature using pure Java and with JUnit framework. First, I will introduce @UnderTest marker annotation:


@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface UnderTest {
}

Now put this annotation above the field in your test case corresponding to class under test:


@UnderTest
private FooService fooService = new DefaultFooService();

Although the annotation brings some value itself, marking which object is actually being tested, it is not meant for documentation and test readability, I am going to use it together with some Java reflection. I mentioned that AOP would solve our problems. JUnit 4.7 ships with AOP-like mechanism called rules. By writing a rule (ExpectedException is an example of a JUnit built-in rule) you simply create an interceptor around every test method. With this interceptor you can, for instance, run test method in separate thread, do some setup and cleanup, etc. My custom rule will do two things:

wrap class under test in Java proxy to catch every exception, store it and return normally
verify thrown exception against assertions introduced in then block

Skeleton of the rule code is as follows:


package com.blogspot.nurkiewicz.junit.exceptionassert;

public class ExceptionAssert implements MethodRule {

 @Override
 public Statement apply(Statement base, FrameworkMethod method, Object testCase) {
  this.testCase = testCase;
  return new ExceptionAssertStatement(base);
 }

 private class ExceptionAssertStatement extends Statement {

  private final Statement base;

  private Throwable exceptionThrownFromClassUnderTest;
  private Field underTestField;

  public ExceptionAssertStatement(Statement base) {
   this.base = base;
   underTestField = findClassUnderTestField(testCase);
  }

  @Override
  public void evaluate() throws Throwable {
   final Object originalClassUnderTest = wrapClassUnderTest(testCase);
   try {
    base.evaluate();
   } finally {
    setUnderTestField(originalClassUnderTest);
   }
   verifyException();
  }

}

ExceptionAssertStatement is an example of Decorator pattern: it takes original Statement instance (representing test method execution) and replaces it with wrapped (decorated) custom class, also implementing Statement. ExceptionAssertStatement adds some additional logic and calls original’s statement evaluate() method. This additional logic is pretty straightforward:

first, take class under test and wrap it (wrapping again!) in a proxy
execute the test method (evaluate())
(revert to original class under test)
when test method exits, verify exception throw from class under test (if any)

The last interesting piece is the proxy wrapping class under test itself:


private Object wrapWithProxy(final Object classUnderTest) {
 return Proxy.newProxyInstance(classUnderTest.getClass().getClassLoader(), new Class[]{underTestField.getType()}, new InvocationHandler() {
  @Override
  public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
   try {
    return method.invoke(classUnderTest, args);
   } catch (InvocationTargetException e) {
    exceptionThrownFromClassUnderTest = e.getCause();
    return null;
   }
  }
 });
}

Nothing fancy: if class under test throws an exception, store it somewhere and return normally. Not that hard. Enough of the internals, let’s look at our brand new rule in action:


public class DefaultFooServiceTest {

 @UnderTest
 private FooService fooService = new DefaultFooService();

 @Rule
 public ExceptionAssert exception = new ExceptionAssert();

 @Test
 public void shouldReturnHelloString() throws Exception {
  //given
  String name = "Tomek";

  //when
  final String result = fooService.echo(name);

  //then
  assertEquals("Hello, Tomek!", result);
 }

 @Test
 public void shouldThrowNpeWhenNullName() throws Exception {
  //given
  String name = null;

  //when
  fooService.echo(name);

  //then
  exception.expect(NullPointerException.class);
 }

 @Test
 public void shouldThrowIllegalArgumentWhenNameJohn() throws Exception {
  //given
  String name = "John";

  //when
  fooService.echo(name);

  //then
  exception.expect(IllegalArgumentException.class)
    .expectMessage("Name: 'John' is not allowed");
 }

}

First test method does not expect any exception to be thrown – it if will, test will fail. Second test expects NullPointerException. Please note that if the exception will be thrown from any other line than fooService.echo() (or fooService.echo() won’t throw NullPointerException), test will fail. The last test shows that you can also assert exception message as well.

Few things are still missing in 0.0.1 "version", mainly proxying classes (CGLIB, anyone?); also, some syntactic sugar together with DSL-like (FEST-like) assertions could be introduced:


@Test
public void shouldThrowIllegalArgumentWhenNameJohn() throws Exception {
 //given
 String name = "John";

 //when
 fooService.echo(name);

 //then
 expect(IllegalArgumentException.class)
   .withMessage("Name: 'John' is not allowed");
}

Also I had to copy&paste big parts of JUnit’s ExpectedException, as most obvious inheritance was not possible due to private constructor. But still, take a look at ExceptionAssert rule and see for yourself how readable exception testing can be. As always, source code can be cloned and downloaded from my GitHub account. Any comments and contributions are welcome!

JavaScript dynamic language support in Spring framework

2010-09-24T20:12:00.002+02:00

Miško Hevery’s blog post about JavaScript opened my eyes and changed the way I thought about this language completely. Miško practices TDD and advices this technique at every occasion. JavaScript, being dynamic language, needs tests even more than statically and strongly typed languages. This immediately invalidates main objections against JavaScript and dynamic languages at all – that lack of compile time checks inevitably lead to poor quality and runtime bugs instead of compile time. But what is more convincing to you: that your code passes very strict compile time rules or that it passes unit tests covering all the use cases?

After going through the first few chapters of Object-Oriented JavaScript... I couldn’t help myself to try this new, very productive language with functional aspirations. But then I realized that, unlike Java, JavaScript misses:

good runtime environment: it’s hard to name handful of web browsers, each implementing different dialect of the language, decent runtime
good development environment: debugger, editor with code completion, profiler – I mean, Firebug is wonderful, but...
testing capabilities – aforementioned vast number of web browser in countless versions, actually, how to run such tests on your continuous integration server?
server-side attitude. C’mon, I’m a back-end guy, running my code inside a web browser to manipulate page DOM and debug using browser plugin? This just doesn’t feel right. Let me run this script clustered on a farm of 16-core servers to make me excited!

And when I say server-side, I mean Spring Framework. The idea to run JavaScript on server-side isn’t new, so it would be nice to introduce JavaScript in Spring. Since version 2.0 Spring supports developing beans using few dynamic languages, namely Groovy, JRuby and BeanShell. The support includes:

Implementing given Java interface using one of the dynamic languages above
Injecting beans implemented in dynamic language to standard Java beans (other beans simply use Java interface as their client view)
...and vice-versa – injecting standard Spring beans into dynamic language scripts
Automatic refresh of script source with configured frequency – sources can be located somewhere on the file system or over the network , allowing hot-deployment and reevaluation without Spring context restart
Scripted beans can participate in Spring aspects, transactions, etc.

The list of features (and possible use cases) for scripted beans is impressive and the whole concept is very powerful. But the list of languages supported is somewhat limited, and – you’ve guessed, but no prize this time – I will add JavaScript to this list in the next few pages. This isn’t going to be very hard since Rhino, JavaScript engine for Java, is now embedded in JRE.

Please at least take a look at Spring dynamic languages support documentation before proceeding, as I will start from the example how I wish the JavaScript support would look like in TDD spirit. Let’s start from simple Java interface:


package org.springframework.scripting.js;

public interface HelloService {

 String hello(String name);

 String helloParameterized(String name, Date effectiveDate, int age, Locale locale);

}

This is the client view of our bean, the implementation is completely transparent to the users of this interface. What we would like to achieve is to be able to implement this interface using JavaScript similar to Groovy or JRuby support in Spring:


<?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:lang="http://www.springframework.org/schema/lang"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang-3.0.xsd">

 <lang:js id="javaScriptHelloService" script-interfaces="org.springframework.scripting.js.HelloService">
  <lang:inline-script>
   function hello(name) {
    return "Hello, " + name + "!"
   }

   function helloParameterized(name, effectiveDate, age, locale) {
    return "" + effectiveDate + ": " + name + " (" + (age + 1) + ", " +
     locale.getDisplayCountry(java.util.Locale.US) + ")" 
   }

  </lang:inline-script>
 </lang:js>

</beans>

And finally the test case stub:


package org.springframework.scripting.js;


@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class JavaScriptScriptFactoryHelloTest {

 @Resource
 private HelloService helloService;

 @Test
 public void shouldReturnHelloStringFromJs() throws Exception {
  //given
  final String name = "Tomek";

  //when
  final String result = helloService.hello(name);

  //then
  assertThat(result).isEqualTo("Hello, Tomek!");
 }

 //other tests

}

Typical Spring integration test looks for file named after the test case name with “-context.xml” suffix (see above). As you can see, no JavaScript is visible, test case (being HelloService client) uses injected interface and calls its operations. The fact that this works and runs JavaScript using Rhino behind the scenes is completely hidden by Spring Framework. Maybe hidden – but not yet implemented. Test fails, we must provide the implementation.

First, one line must be added to LangNamespaceHandler, simply mapping <lang:js> tag to so-called script factory.


package org.springframework.scripting.config;

public class LangNamespaceHandler extends NamespaceHandlerSupport {

 public void init() {
  registerScriptBeanDefinitionParser("groovy", "org.springframework.scripting.groovy.GroovyScriptFactory");
  registerScriptBeanDefinitionParser("jruby", "org.springframework.scripting.jruby.JRubyScriptFactory");
  registerScriptBeanDefinitionParser("bsh", "org.springframework.scripting.bsh.BshScriptFactory");
  registerScriptBeanDefinitionParser("js", "org.springframework.scripting.js.JavaScriptScriptFactory");
  registerBeanDefinitionParser("defaults", new ScriptingDefaultsParser());
 }

}

The purpose of JavaScriptScriptFactory is pretty straightforward: it gets set of Java interfaces (have you mentioned the script-interfaces attribute?) and script source and is suppose to return some implementation of all these interfaces, of course utilizing script source provided:


package org.springframework.scripting.js;

public class JavaScriptScriptFactory implements ScriptFactory {

 public boolean requiresConfigInterface() {
  return true;
 }

 public Object getScriptedObject(ScriptSource scriptSource, Class[] actualInterfaces) throws IOException, ScriptCompilationException {
  return //It's a kind of magic
 }

}

Actually, there is no magic out there, just plain JSR-223 API abstracting Rhino engine. But still dynamic proxies, reflection and creating Java interfaces from scratch using CGLIB is taking place out there (luckily Spring manages most of this), so if you are really curious, take a look at my GitHub account.

What have we achieved? Take for instance this JavaScript Spring bean declaration:


<lang:js id="javaScriptUserService"
 script-interfaces="org.springframework.scripting.js.UserService"
 script-source="http://somehost:8080/scripts/UserService.js"
 refresh-check-delay="15000"/>

Enough to make Spring download UserService.js file from external HTTP server and reload its contents every 15 seconds. Now in order to change UserService behavior simply put new version of .js file on your web server (or FTP folder, or file system directory, or...) – no restarts, no class-loaders juggling, no OSGi – unbelievably flexible, deadly simple and terribly dangerous toy – but that’s a different story.

We, programmers, love Hello World examples. Some of us even judge technologies based on their “hello” incarnation. But how could you use scripted bean in a real world application? The last feature we haven’t covered yet is dependency injection into JavaScript bean (not injecting the bean somewhere else). Spring already provides syntax for that:


<bean id="resourceBundleMessageSource" class="org.springframework.context.support.ResourceBundleMessageSource">
 <property name="basename" value="org.springframework.scripting.js.i18n.hello"/>
</bean>

<bean id="greatBritainLocale" class="java.util.Locale">
 <constructor-arg value="en_GB"/>
</bean>

<lang:js id="javaScriptHelloService"
  script-interfaces="org.springframework.scripting.js.HelloService"
  script-source="/org/springframework/scripting/js/HelloService.js">
 <lang:property name="city" value="Warsaw"/>
 <lang:property name="locale" ref="greatBritainLocale"/>
 <lang:property name="messages" ref="resourceBundleMessageSource"/>
</lang:js>

As you can see we ask Spring to inject three properties (Spring bean, Java built-in object and primitive) into the script. How can the script use this dependencies? I have decided to enable them directly as implicit variables:


function hello(name) {
 return messages.getMessage("hello", [name, city], locale);
}

name is hello’s argument, but where does the messages, city and locale come from? Scripted bean can easily interact with other Spring beans (not necessarily written in Java nor JavaScript!), for example asking ResourceBundleMessageSource to return internationalized message. I have a test case for that (actually, I started from it), believe me, it works!

Finally I can get my hands dirty wit JavaScript. Writing unit tests using JUnit feels much more natural than observing web browser output. Also Spring-enabled scripted beans give me much richer environment to work with. From my complete novice point of view JavaScript isn’t as good as Groovy, but still it’s worth trying, especially when embedding few MiB groovy.jar is out of the question in your Java 6 app. If you want to experiment with JavaScript support in Spring Framework, just clone my GitHub’s spring-js repository. And you really like concept of JavaScript running from within Spring, vote for SPR-7592.

Creating prototype Spring beans on demand using lookup-method

2010-08-05T23:44:00.006+02:00

The strength of the Spring Framework is its emphasis on stateless services. Being totally against OOP, this approach has many pragmatic advantages, with low memory consumption, no cost of pooling and multithreaded safety at the top of the list. But sometimes you really need the context and having non-singleton beans with different state attached to each instance makes your code a lot cleaner and easier to read. Let’s start from stateless code and do some consecutive refactorings.

Every time a new flight is entered into the system, we validate it with multiple business rules using FlightValidator class (please forgive my complete absence of domain knowledge):

public class FlightValidator {

@Resource
//Many services

public boolean validate(Flight flight) {
return validateSourceAndTarget(flight) &&
isAirplaneAvailable(flight) &&
isAirportFree(flight) &&
!buyerBlackListed(flight) &&
reservationLimitReached(flight);
}

//Many more methods

}

There is something really disturbing in this code. The context (Flight instance being validated) is passed over and over through subsequent method invocations. On the other hand, because the context exists on the stack (which is thread local in the contrary to the heap), the class is thread safe by its definition. But still the code is so awkward that having flight field accessible to every method in the class (and sacrificing thread safety) is very tempting*. The easiest solution is to have a new, separate instance of FlightValidator every time we need to validate a flight. So we create FlightValidator bean with prototype scope:

<bean id="flightValidator" class="com.blogspot.nurkiewicz.lookup.FlightValidator" scope="prototype" lazy-init="true"/>

Now, every time there is a need for flight validation, we should ask Spring to create a new instance of FlightValidator (imagine the class has multiple dependencies on other beans, has some aspects woven, etc. – we can’t simply use new operator). The easiest way to do this is to implement BeanFactoryAware and use injected BeanFactory to fetch any bean from the client code:

public class SomeSpringBean implements BeanFactoryAware {
private BeanFactory beanFactory;

@Override
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
this.beanFactory = beanFactory;
}

//client code:
FlightValidator validator = beanFactory.getBean("flightValidator", FlightValidator.class);

}

Every time the code in line 10 is executed, new instance (prototype scope) of FlightValidator is created and returned. Maybe the goal is achieved, but the solution is pretty cumbersome. Not only we tie ourselves with the Spring API, but also we fetch bean by name (which is very verbose). Last but not least, prior to Spring 3.0 the getBean() always returned Object instance, forcing client code to downcast the result.

I used this pattern several times, always being disgusted. But then, by accident, I found lookup-method feature in Spring docs. BTW Spring documentation is a gift... and a curse (like detective Monk used to say) - so exhaustive and comprehensive that it’s hard to read it and get to know with everything. But back to Spring – the idea behind the lookup method is to drop BeanFactoryAware interface and simply create abstract no-arg method that returns bean of type we are willing to create (i.e. FlightValidator). Now the best part: we just tell Spring declaratively we want this abstract method to create FlightValidator instance every time it is called and Spring will implement this method at runtime (using CGLIB) for us! Just look how easy it is comparing to BeanFactory approach:

public abstract class SomeSpringBean {

protected abstract FlightValidator createValidator();

//client code somewhere in the class:
FlightValidator validator = createValidator();
}

<bean id="flightValidator" class="com.blogspot.nurkiewicz.lookup.FlightValidator" scope="prototype" lazy-init="true"/>

<bean id="someBean" class="com.blogspot.nurkiewicz.lookup.SomeSpringBean">
<lookup-method name="createValidator" bean="flightValidator"/>
</bean>

The 4th line of Spring XML is essential. We basically say: hey, createValidator method is abstract and every time it is called, return new instance (using lookup-method and BeanFactory with singleton beans doesn’t make any sense) of bean named flightValidator. And Spring is clever enough to harness CGLIB and dynamically implement createValidator() method instead of trying to instantiate abstract class. Pretty awesome!

This approach looks much nicer, does not involve the Spring API or force us to hardcode bean name in Java code. Now, when we have a fresh new instance of FlightValidator, we can perform some refactorings to take advantage of class instance variables:

private Flight flight;

public boolean validate(Flight flight) {
this.flight = flight;
return validateSourceAndTarget() &&
isAirplaneAvailable() &&
isAirportFree() &&
!buyerBlackListed() &&
reservationLimitReached();
}

First, we assign flight to a private field available for all validating methods. Now, every method can access this field and there’s no need for passing arguments all over. But sadly, it is just the beginning. One day we had to make all validating methods publicly accessible in order to call them separately. But now we need some way to initialize flight field and we certainly don’t want to go back to flight parameter in every method and flight field assignment at the beginning of each one. There is another accidental disadvantage of our solution: if particular instance of FlightValidator leaks to some other thread, this thread can call validate() method with other Flight causing race condition. If only we could make FlightValidator immutable by passing flight only once, binding FlightValidator permanently with this flight and being able to easily call every public validation method...

private final Flight flight;

public FlightValidator(Flight flight) {
this.flight = flight;
}

public boolean validate() {
return validateSourceAndTarget() &&
isAirplaneAvailable() &&
isAirportFree() &&
!buyerBlackListed() &&
reservationLimitReached();
}

This is it! Our Holy Object Oriented Grail! Compiler forces us to pass valid flight instance (you may add validation to assert that) and after the FlightValidator is created, it will always reference the same flight. API is simple, class is thread safe, everybody is happy... Except our favorite framework... According to the documentation, lookup method discussed above mustn’t have any arguments. But suppose I don’t read the docs and simply add Flight parameter to lookup method and expect the magic to happen:

protected abstract FlightValidator createValidator(Flight flight);

I thought to myself that Spring will transparently pass lookup method parameter(s) to the FlightValidator constructor matching its declaration – and we have just created such a constructor. I run the application and it starts fine, but when I try to call lookup method I get:

java.lang.AbstractMethodError: com.blogspot.nurkiewicz.lookup.SomeSpringBean.createValidator(Lcom/blogspot/nurkiewicz/lookup/Flight;)Lcom/blogspot/nurkiewicz/lookup/FlightValidator;

Seems like Spring ignored lookup method with arguments and simply didn’t implement it using CGLIB. I would expect context startup to fail or at least warning that lookup won’t work (I even created SPR-7426) but sadly only unit tests can prevent you from such a mistake. And IntelliJ IDEA:

We might work around this limitation and create some sort of init(Flight flight) method instead of constructor. But what if we forget to call this method or call it twice? Thread safety, immutability and consistency are lost... Spring does not allow us to parameterize creation of prototype beans created by lookup method but come on, it’s open source and I am a programmer, I wouldn’t sleep at night if I at least didn’t try...

Patching Spring...

The stacktrace following AbstractMethodError didn’t help me but after turning on verbose Spring logging I immediately spotted org.springframework.beans.factory.support.CglibSubclassingInstantiationStrategy class that is responsible for dynamic creation of abstract lookup method code and other features using CGLIB. But first I had to discover why my parameterized lookup method is ignored by this mechanism. After few minutes of studying I came across org.springframework.beans.factory.support.LookupOverride class with method:

@Override
public boolean matches(Method method) {
return (method.getName().equals(getMethodName()) && method.getParameterTypes().length == 0);
}

So I changed too rigorous constraint and removed no arguments condition:

@Override
public boolean matches(Method method) {
return method.getName().equals(getMethodName());
}

I quickly run my unit tests and now Spring generated code for my abstract lookup method (AbstractMethodError is gone) but still framework tries to instantiate FlightValidator bean using no-arg constructor, ignoring lookup method parameters. First success, another challenge.

Half hour later I finally make out how CGLIB works and how Spring uses it. I’ll skip CGLIB tutorial (maybe we’ll come back to this great library later), enough is to say that every time we call lookup abstract method, CGLIB synthesized class calls provided callback method, that for lookup method looks like this (excerpt from LookupOverrideMethodInterceptor inner class in org.springframework.beans.factory.support.CglibSubclassingInstantiationStrategy.CglibSubclassCreator):

public Object intercept(Object obj, Method method, Object[] args, MethodProxy mp) throws Throwable {
LookupOverride lo = (LookupOverride) beanDefinition.getMethodOverrides().getOverride(method);
return owner.getBean(lo.getBeanName());
}

Third line is crucial. We take bean name defined in Spring XML and fetch it from BeanFactory named owner. But hey, what is that, args array argument?!? And take a look at overloaded getBean(String name, Object... args) method, ready to be used! I’ll give it a try and see what happens:

public Object intercept(Object obj, Method method, Object[] args, MethodProxy mp) throws Throwable {
LookupOverride lo = (LookupOverride) beanDefinition.getMethodOverrides().getOverride(method);
return owner.getBean(lo.getBeanName(), args);
}

Can you spot the difference? I run unit tests and can’t believe my own eyes – it works! It’s amazing, I only changed – not even added, changed! – two lines of code and unlocked this great feature. Now I can pass arbitrary set of parameters to the lookup method and they are going to be passed straight to the constructor of newly created object. Finally the lookup method idea makes sense – create new, fully customized and initialized object every time you request it. No need for further setup and danger of data inconsistency. Long live the Spring Framework!

If you like this feature, I opened SPR-7431 ticket, watch it and vote for it.

* one might argue that validate() should actually be a method of Flight and is an example of Feature Envy (see Martin Fowlers’ book) code smell. I already discussed how to get rid of this smell using Spring

Few words after Javarsovia 2010

2010-08-02T23:32:00.006+02:00

It is never too late to mention about such a great event like Javarsovia 2010 conference. The conference was really successful, even though I was one of the speakers ;-). If you were near Warsaw on 26th of June and missed the conference I feel really sorry for you. But first things first.

I was really surprised not seeing long queues for the registration, so not wasting a lot of time, equipped with good-looking conference T-shirt, we went to see the first presentation. Tomasz Bujok with his From zero to jBPM hero! lecture did a great job introducing jBPM framework. I have seen quite a few presentations about this engine already, thankfully Tomasz made one step further in the topic and have shown some anti-patterns and other tips for jBPM developers. This was really interesting as anyone, after reading a book or two, can have a "How-to" talk. But having "How-not-to" talk requires knowledge and experience in the technology far beyond the typical tutorial-driven "experts". I would really like to work with jBPM for a while, but I’m also full of concerns about the future of this framework.

I have seen Wojciech Seliga last year on Java Developers’ Day, where he’s been talking about Crucible, code review tool his company is developing for Atlassian. This time he shared with us some of his experience in working using agile methodologies. I must admit I was pretty amazed how well they adapted Scrum, especially in the field of their relationships with customers. Some people didn’t believe them when they promised to deliver first running software version after a week (one sprint). But they did and this is how they achieve customer trust. Probably one of the most successful companies implementing agile, proving it can really work and bring money. Lots of respect to you guys!

Piotr Jagielski had a whole speech about test code refactoring (and actually – test code quality at all). The most important idea from his lecture: if some setup/data is not important for the test, it is important to not include it in this test. For instance, suppose you are testing that creating Person object with birth date in the future should throw IllegalArgumentException. Unfortunately, the only available constructor requires, besides birthDate, also firstName and lastName. Supplying fake names would do the trick, but the test method is now cluttered with irrelevant setup code. Moreover, the reader of this test code might not be so sure about fake names irrelevancy. Some flavor of Builder pattern, introduced by Piotr, is the good solution for this problem. Or one can simply use Groovy with its ability to pass arbitrary property -> value map to the constructor call. I suggested Piotr he could benefit from using Groovy, but seems like he’s not using it for testing purposes.

After the lunch my time has come. Project Voldemort - when relation database is not enough (too much?) lecture taken place in Boolean room (BTW: great idea of naming conference rooms after Java data types according to their size!), here is the English translation of the presentation:

...and one of the photos taken during my presentation, thanks to Javarsovia 2010 gallery:

All about me. For those who have seen me, hope you didn’t regret it! Personally I would choose Sławomir Sobótka talk about design patterns, so thank you for choosing me instead :-).

Many times I was a bit jealous of American speakers, but after seeing Paweł Lipiński (and Dawid Weiss few month earlier) I find some Polish speakers being at least as charismatic and entertaining as those coming from the other side of the Ocean. Paweł came out with a toothbrush in his mouth, wearing a dressing-gown. Instantly everybody knew that he’s going to talk about clean... not code, but tests - although wonderful Uncle Bob’s book has been mentioned many times.

The truth is, I keep hearing the same things about TDD over and over. Same techniques, same principles, same dos and donts. But still some people live in their caves and don’t realize how could they benefit by using TDD (and even unit testing at all!) Some time ago a friend of mine, after developing in Wicket for a few months (and hundreds of my persuasions), finally tried out WicketTester class. "It’s great", he said, "how could I live without it?" If only I had such a charisma and experience like Paweł, maybe he would have tried earlier. Why can’t people wake up and keep manually testing their code, redeploying and restarting EARs over and over? If Paweł’s talk didn’t opened their eyes, they should at least be ashamed. It was not a developer or project manager lecture. He looked more like a rock-star, shouting with anger, desperately trying to convince the audience. Next time I will attend Paweł Lipiński’s talk, even if it will be on National Crocheting Congress. Great job, wonderful speech.

I really couldn’t wait to see Jarosław Pałka cross-sectional talk on NoSQL. Unfortunately, being short on time, he only managed to show Neo4j database and skipped promised CouchDB and BerkeleyDB. Although Neo4j is the most interesting NoSQL software from these three, it’s a shame there was no time for other players. The speaker had some technical issues while running the examples and focused too much on irrelevant details. Too bad, because the beginning of the lecture was very promising. I would really like to hear the lecture again, but it seemed to lack one or two days of preparation.

I must say Javarsovia 2010 was a really successful conference, that could easily compete with GeeCON or JDD. More than 600 attendees, 4 independent tracks and very good organization. Oh, did I mention the conference was completely free, including after party in pub? See you next year, good job!

Hades: DRY principle in JPA/Spring development

2010-07-06T23:11:00.006+02:00

It's almost two weeks after great Javarsovia 2010 conference, but before I write few words about this event, let me mention about really clever library called Hades. I owe you this after my attendance in GeeCON 2010, where I discovered this tool during its author talk.

DRY stands for Don't Repeat Yourself and if you were developing in JPA for a while you have violated this principal several times. Take for example this piece of code:

Although IntelliJ IDEA has a wonderful support for JPA (have you noticed this little popup suggesting me the proper named query parameter name since?), I still have to write the same boilerplate code over and over. Basically for each entity object I need a DAO class and 90% of them look the same except they have different entity type. Same CRUD, same paging and sorting logic, same unit tests, similar queries. We are getting bored after writing fifth or tenth DAO like this, especially if we are lazy (which is good!) So Hades provides nice abstraction, at least all your DAOs would follow same naming convention:

public interface GenericDao<T, PK extends Serializable> {
    T save(final T entity);
    List<T> save(final List<T> entities);
    T saveAndFlush(final T entity);
    T readByPrimaryKey(final PK primaryKey);
    boolean exists(final PK primaryKey);
    List<T> readAll();
    List<T> readAll(final Sort sort);
    Page<T> readAll(final Pageable pageable);
    Long count();
    void delete(final T entity);
    void delete(final List<T> entities);
    void deleteAll();
    void flush();
}

Nice, but you probably came out with similar generic interface long time ago. But Hades goes one step further and it automatically implements this interface for you… For any entity bean you provide!

public interface MoneyTransferDao extends GenericDao<MoneyTransfer, Long> {}

But let's start from the beginning. First get necessary dependencies:

<!-- Spring -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-orm</artifactId>
    <version>3.0.3.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>3.0.3.RELEASE</version>
    <scope>test</scope>
</dependency>

<!-- Persistence -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.1.119</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>commons-dbcp</groupId>
    <artifactId>commons-dbcp</artifactId>
    <version>1.4</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.hibernate.java-persistence</groupId>
    <artifactId>jpa-api</artifactId>
    <version>2.0-cr-1</version>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>3.5.1-Final</version>
</dependency>
<dependency>
    <groupId>org.synyx.hades</groupId>
    <artifactId>org.synyx.hades</artifactId>
    <version>2.0.0.RC2</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>org.springframework.orm</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- ... -->

<repository>
    <id>repo.synyx.de</id>
    <name>Synyx Maven2 Repository</name>
    <url>http://repo.synyx.org</url>
</repository>

All other dependencies necessary to run Spring-managed integration test with JPA 2.0 backed by Hibernate 3.5 will be downloaded transitively. You also need logging dependencies, take a look here.

As an example we are going to use these two entities:

public class MoneyTransfer implements Serializable {
    private long id;
    private Account from;
    private Account to;
    private BigDecimal amount;
    private Calendar date;

    //get/set

}

public class Account implements Serializable {
    private int id;
    private String ownerName;

    //get/set

}

Personally, I find JPA annotations great for rapid prototyping, but awful in production code, especially when fine-tuning your mapping (database sequence names in Java annotations attributes?!?) So here is my orm.xml excerpt:

<entity class="com.blogspot.nurkiewicz.hades.MoneyTransfer">
    <attributes>
        <id name="id">
            <generated-value/>
        </id>
        <basic name="date" optional="false">
            <temporal>DATE</temporal>
        </basic>
        <basic name="amount" optional="false">
            <column precision="20" scale="2"/>
        </basic>
        <many-to-one name="from" optional="false">
            <cascade>
                <cascade-all/>
            </cascade>
        </many-to-one>
        <many-to-one name="to" optional="false">
            <cascade>
                <cascade-all/>
            </cascade>
        </many-to-one>
    </attributes>
</entity>

<entity class="com.blogspot.nurkiewicz.hades.Account">
    <attributes>
        <id name="id">
            <generated-value/>
        </id>
        <basic name="ownerName" optional="false">
            <column length="120"/>
        </basic>
    </attributes>
</entity>

We all love XML, admit it! And finally unit test itself:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@Transactional
public class MoneyTransferDaoTest {

    @PersistenceContext
    private EntityManager em;

    @Resource
    private MoneyTransferDao dao;

    @Resource
    private AccountDao accountDao;

    @Test
    public void shouldReturnNothingWhenReadingNotExistingMoneyTransfer() throws Exception {
        //when
        final MoneyTransfer moneyTransfer = dao.readByPrimaryKey(17L);

        //then
        assertThat(moneyTransfer).isNull();
    }

    @Test
    public void shouldReturnExistingMoneyTransfer() throws Exception {
        //given
        final MoneyTransfer newTransfer = new MoneyTransfer();
        em.persist(newTransfer);

        //when
        final MoneyTransfer moneyTransfer = dao.readByPrimaryKey(newTransfer.getId());

        //then
        assertThat(moneyTransfer).isNotNull();
        assertThat(moneyTransfer.getId()).isEqualTo(newTransfer.getId());
    }

//...

}

Following Spring unit test naming convention, this test case will start Spring context located in MoneyTransferDaoTest-context.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" xmlns:hades="http://schemas.synyx.org/hades"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
            http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
            http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd http://schemas.synyx.org/hades http://schemas.synyx.org/hades/hades.xsd">

    <tx:annotation-driven transaction-manager="transactionManager"/>
    <context:annotation-config/>

    <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>
    <bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/>

    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="org.h2.Driver"/>
        <property name="url" value="jdbc:h2:mem:moneytransfers;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"/>
    </bean>

    <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
        <property name="entityManagerFactory" ref="entityManagerFactory"/>
    </bean>

    <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
        <property name="dataSource" ref="dataSource"/>
        <property name="jpaVendorAdapter" ref="jpaAdapter"/>
        <property name="jpaProperties">
            <props>
                <prop key="hibernate.format_sql">true</prop>
                <prop key="hibernate.ejb.naming_strategy">org.hibernate.cfg.DefaultComponentSafeNamingStrategy</prop>
                <prop key="hibernate.hbm2ddl.auto">update</prop>
            </props>
        </property>
    </bean>

    <bean id="jpaAdapter" class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>

    <hades:dao-config base-package="com.blogspot.nurkiewicz.hades"/>

</beans>

Now run the test, it should pass. That's right, we haven't written even single line of DAO code and still our MoneyTransferDao, injected in line 10, works perfectly! The whole magic is hidden under line 39 of Spring context file. hades:dao-config element discovers all interfaces extending org.synyx.hades.dao.GenericDao<T, PK extends Serializable> and dynamically implements them based on their generic types. We automatically get methods like:

public interface MoneyTransferDao extends GenericDao<MoneyTransfer, Long> {
    MoneyTransfer readByPrimaryKey(final Long primaryKey);
    Page<MoneyTransfer> readAll(final Pageable pageable);
 //...
}

Yep, Hades also provides built in support for paging and sorting – especially annoying when has to be implemented and tested manually for several entities.

OK, to be honest, there was no magic in what we have seen until now and you might have even written similar utilities for your internal usage. Although GenericDao has some built in methods that cover, let's say, 50% of typical queries, what about the rest? What if I would like to find all money transfers with amount greater than given value?

public interface MoneyTransferDao extends GenericDao<MoneyTransfer, Long> {
    List<MoneyTransfer> findByAmountGreaterThan(BigDecimal amount);
}

Where to put the implementation of this custom DAO method? Well, now the magic part begins – nowhere! Similar to GORM, Hades will parse this method name and create the query for you. All you have to do is to follow some naming convention. No custom queries, no boilerplate code. Hades will even set the parameter for you. It's such a clever tool, that simply by adding argument of type Pageable Hades will include paging clauses (like TOP, LIMIT, OFFSET, etc.):

public interface MoneyTransferDao extends GenericDao<MoneyTransfer, Long> {
    List<MoneyTransfer> findByDateGreaterThan(Calendar date, Pageable page);
 //...
}

moneyTransferDao.findByDateGreaterThan(
        Calendar.getInstance(),
        new PageRequest(1, 20, new Sort(Order.ASCENDING, "amount")));

So, Hades can transparently implement basic CRUD operations with sorting/paging support. It can also synthesize queries based only on interface method name and arguments. But once you discover that this feature is very limited (for instance it does not support Not, Like, IsNull, In and other modifiers known from GORM, see issue #274), you'll eventually end up with a need for a custom JPA query like this:

<named-query name="MoneyTransfer.getAverageTransferAmountSince">
    <query>
        SELECT AVG(transfer.amount)
        FROM MoneyTransfer transfer
        WHERE transfer.date > ?1
    </query>
</named-query>

Now we add method in our DAO interface that will execute this query:

public interface MoneyTransferDao extends GenericDao<MoneyTransfer, Long> {
    BigDecimal getAverageTransferAmountSince(Calendar since);
 //...
}

The implementation is trivial (see screenshot at the beginning of this article), so Hades implements this method for us as well. Name of the method matches name of the named query (prefixed by the entity name), which is enough for Hades. Few lines of code (repeated hundreds of times) are saved.

But what if you really want to implement custom DAO method, but still having all other methods implemented for you? There are two reasons: do some validation and parameters transformation before the query is executed and post-process results after query execution. The latter reason can be often eliminated using not very well known JPA query language feature. Take for instance this query:

SELECT transfer.amount, transfer.from.id, transfer.to.id
FROM MoneyTransfer transfer

It will return List<Object[]>, which isn't very object-orientish. Instead, our DAO layer should do some transformation and return more user friendly object. JPA can do this for you with this simple expression:

SELECT NEW RawMoneyTransfer(transfer.amount, transfer.from.id, transfer.to.id)
FROM MoneyTransfer transfer

RawMoneyTransfer is any Java object (not necessarily JPA entity) with constructor matching given parameters being only requirement. But once again, what if you really need custom DAO method? For example JPA does not define any date expressions, so there is no straightforward way to define "30 days before today" when generating report for last month in JPA QL. Unfortunately, Hades way of defining custom DAO methods is troublesome and a bit counterintuitive. I will open an issue and try to introduce simpler (although harder in implementation) solution. Meanwhile take a look at great Hades reference documentation for further details.

Hades also has support for entity auditing, but Envers, being part of Hibernate portfolio, is probably more mature solution. As of version 2.0 it also has built in support to participate in Spring transactions. As you have seen, Hades aims to increase your productivity by writing less code, less unit tests (comprehensive unit testing of Hades-generated methods isn't necessary) and promoting convention over configuration approach. It still has some limitations but give it a try, I recently will.

Clean code, clean logs: easy to read, easy to parse (10/10)

2010-05-19T23:35:00.004+02:00

There are two groups of receivers particularly interested in your application logs: human beings (you might disagree, but programmers belong to this group as well) and computers (typically shell scripts written by system administrators). Logs should be suitable for both of these groups. If someone looking from behind your back at your application logs sees:

from Wikipedia

then you were probably not reading my tips carefully enough. The reference to famous Clean code book in the title of this series is not accidental: logs should be readable and easy to understand just like the code should.

On the other hand, if your application produces half GiB of logs each hour, no man and no graphical text editor will ever manage to read them entirely. This is where old-school grep, sed and awk come in handy. If it is possible, try to write logging messages in such a way, that they could be understood both by humans and computers, e.g. avoid formatting of numbers, use patterns that can be easily recognized by regular expressions, etc. If it is not possible, print the data in two formats:

log.debug("Request TTL set to: {} ({})", new Date(ttl), ttl);
// Request TTL set to: Wed Apr 28 20:14:12 CEST 2010 (1272478452437)

final String duration = DurationFormatUtils.formatDurationWords(durationMillis, true, true);
log.info("Importing took: {}ms ({})", durationMillis, duration);
//Importing took: 123456789ms (1 day 10 hours 17 minutes 36 seconds)

Computers will appreciate "ms after 1970 epoch" time format, while people would be delighted seeing "1 day 10 hours 17 minutes 36 seconds" text. BTW take a look at DurationFormatUtils, nice tool.

I thought this article is going to be short, but after writing it I decided to split it into 10 parts, each in separate post. Hope you enjoyed my logging series, although still not everything has been covered. This only proves how logging is important and how many pitfalls should be avoided. Remember, logging code should also be clean and reading your logs is supposed to be as pleasant as reading your code.

Clean code, clean logs: use appropriate tools (1/10)

Clean code, clean logs: logging levels are there for you (2/10)

Clean code, clean logs: do you know what you are logging? (3/10)

Clean code, clean logs: avoid side effects (4/10)

Clean code, clean logs: concise and descriptive (5/10)

Clean code, clean logs: tune your pattern (6/10)

Clean code, clean logs: log method arguments and return values (7/10)

Clean code, clean logs: watch out for external systems (8/10)

Clean code, clean logs: log exceptions properly (9/10)

Clean code, clean logs: easy to read, easy to parse (10/10)

Clean code, clean logs: log exceptions properly (9/10)

2010-05-19T00:10:00.004+02:00

First of all, avoid logging exceptions, let your framework or container (whatever it is) do it for you*. Logging exceptions is one of the most important roles of logging at all, but many programmers tend to treat logging as a way to handle the exception. They sometimes return default value (typically null, 0 or empty string) and pretend that nothing has happened. Other times they first log the exception and then wrap it and throw back:

log.error("IO exception", e);
throw new MyCustomException(e);

This construct will almost always print the same stack trace two times, because something will eventually catch MyCustomException and log its cause. Log or wrap and throw back (which is preferable), never both, otherwise your logs will be confusing.

But if we really do WANT to log the exception? For some reason (because we don’t read APIs and documentation?), about half of the logging statements I see are wrong. Quick quiz, which of the following log the NPE properly?

try {
    Integer x = null;
    ++x;
} catch (Exception e) {
    log.error(e);        //A
    log.error(e, e);        //B
    log.error("" + e);        //C
    log.error(e.toString());        //D
    log.error(e.getMessage());        //E
    log.error(null, e);        //F
    log.error("", e);        //G
    log.error("{}", e);        //H
    log.error("{}", e.getMessage());        //I
    log.error("Error reading configuration file: " + e);        //J
    log.error("Error reading configuration file: " + e.getMessage());        //K
    log.error("Error reading configuration file", e);        //L
}

Surprisingly, only G and preferably L are correct! A and B don’t even compile in SLF4J, others discard stack traces and/or print improper messages. For example, E won’t print anything as NPE typically don’t provide any exception message and stack trace won’t be printed as well. Remember, first argument is always the text message, write something about the nature of the problem. Don’t include exception message, as it will be printed automatically after the log statement, preceding stack trace. But in order to do so, you must pass the exception itself as the second argument.

* There is one, ekhem, exception to this rule: if you throw exceptions from some remote service (RMI, EJB remote session bean, etc.), that are capable to serialize exceptions, make sure all of them are available to the client (are part of the API). Otherwise the client will receive NoClassDefFoundError: SomeFancyException instead of "true" error.

Clean code, clean logs: use appropriate tools (1/10)

Clean code, clean logs: logging levels are there for you (2/10)

Clean code, clean logs: do you know what you are logging? (3/10)

Clean code, clean logs: avoid side effects (4/10)

Clean code, clean logs: concise and descriptive (5/10)

Clean code, clean logs: tune your pattern (6/10)

Clean code, clean logs: log method arguments and return values (7/10)

Clean code, clean logs: watch out for external systems (8/10)

Clean code, clean logs: log exceptions properly (9/10)

Clean code, clean logs: easy to read, easy to parse (10/10)

Clean code, clean logs: watch out for external systems (8/10)

2010-05-17T22:46:00.006+02:00

This is the special case of the previous tip: if you communicate with any external system, consider logging every piece of data that comes out from your application and gets in. Period. Integration is a tough job and diagnosing problems between two applications (think two different vendors, environments, technology stacks and teams) is particularly hard. Recently, for example, we've discovered that logging full messages contents, including SOAP and HTTP headers in Apache CXF web services is extremely useful during integration and system testing.

This is a big overhead and if performance is an issue, you can always disable logging. But what is the point of having fast, but broken application, that no one can fix? Be extra careful when integrating with external systems and prepare to pay that cost. If you are lucky and all your integration is handled by ESB, bus is probably the best place to log every incoming request and response. See for example Mules' <log-component/>.

Sometimes the amount of information exchanged with external systems makes it unacceptable to log everything. On the other hand during testing and for short period of time on production (for example when something wrong is happening) we would like to have everything saved in logs and are ready to pay performance cost. This can be achieved by carefully using logging levels. Just take a look at the following idiom:

Collection<Integer> requestIds = //...

if(log.isDebugEnabled())
    log.debug("Processing ids: {}", requestIds);
else
    log.info("Processing ids size: {}", requestIds.size());

If this particular logger is configured to log DEBUG messages, it will print the whole requestIds collection contents. But if it is configured to print INFO messages, only the size of collection will be outputted. If you are wondering why I forgot about isInfoEnabled() condition, go back to this tip. One thing worth mentioning is that requestIds collection should not be null in this case. Although it will be logged correctly as null if DEBUG is enabled, but big fat NullPointerException will be thrown if logger is configured to INFO. Remember my lesson about side effects?

Clean code, clean logs: use appropriate tools (1/10)

Clean code, clean logs: logging levels are there for you (2/10)

Clean code, clean logs: do you know what you are logging? (3/10)

Clean code, clean logs: avoid side effects (4/10)

Clean code, clean logs: concise and descriptive (5/10)

Clean code, clean logs: tune your pattern (6/10)

Clean code, clean logs: log method arguments and return values (7/10)

Clean code, clean logs: watch out for external systems (8/10)

Clean code, clean logs: log exceptions properly (9/10)

Clean code, clean logs: easy to read, easy to parse (10/10)