Fetching, aggregating and transforming data for delivery is a seemingly complex task. Imagine a service that serves aggregated search results from Twitter, Google and Bing where the response has to be tailored for mobile and web. One has to fetch data from different sources, parse and compose the results then transform them into the right markup for delivery to a specific client platform.
To cook this I’ll need:
- a web server
- a nice way to aggregate web service responses (pipelining would be nice)
- a component to transform the raw aggregated representation into a tailored client response.

I could take a stab at it and use Apache/Tomcat, Java (using Apache HttpClient 4.0), a servlet dispatcher (Spring WebMVC) and Velocity templating but it sounds too complex.

Enter Node.js. It’s an event-based web server built on Google’s V8 engine. It’s fast and it’s scalable and you develop on it using the familiar Javascript.
While Nodejs is still new, the community has built a rich ecosystem of extensions (modules) that greatly ease the pain of using it. If you’re unfamiliar with the technology, check-out the Hello World example, it should get you started.
Back to the task at hand, here are the modules I’ll need:
- Restler to get me data.
- async to allow parallelizing requests for effective data fetching.
- Haml-js for view generation

To restate the requirement, we want to aggregate results from Google and Twitter using any arbitrary search predicate.
First we need node.js itself:

git clone http://github.com/ry/node/tree/master
./configure
make
sudo make install

Let’s bring the necessary modules. Create a project directory then fetch them in it:

git clone  http://github.com/caolan/async.git
git clone http://github.com/danwrong/restler.git
git clone http://github.com/creationix/haml-js.git

Most of the action take place in one file that fires the webserver and contains all the event logic. My small little server is called servus.js so I’ll call the file just that.

Update Jun/28: Servus now lives in github, grab it here

First thing, import all the modules, assuming that all of them are in the root of the project directory and create the basic port listener (all code in servus.js):

var sys = require('sys'),
  http = require('http'),
  rest = require('./restler/lib/restler'),
  async = require('./async/lib/async'),
  haml = require('./haml-js/lib/haml');
  url = require('url'),
  fs = require('fs');

http.createServer(function (req, res) {
    process.addListener('uncaughtException', function (err) {
      sys.puts('Caught exception: ' + err);
      res.writeHead(500, 'text/plain');
      res.end('error!');
    });

   res.writeHead(200, {'Content-Type': 'text/plain'});
   res.end('Servus\n');
}).listen(8124, "127.0.0.1");
sys.puts('Server running at http://127.0.0.1:8124/');

Listening for ‘uncaughtException’ events ensures that the server keeps running when an exception occurs. Run this with node servus.js and you should see the server responding with ‘Servus’ when browsing to http://localhost.

Let’s add some real code. First, we define the request URLs for Twitter and Google. Next, parse the URL and extract the query predicate. Servus will respond to /aggregate?q= requests and querying both search services using async. Replace res.writeHead and res.end lines with:

    var serviceUrls = {};
    serviceUrls.twit = 'http://search.twitter.com/search.json?q=';
    serviceUrls.goo = 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=';
    var urlParsed = url.parse(req.url, true);
    var path = urlParsed.pathname;

    switch(path) {
      case '/aggregate':
        //extract search predicate
        var query = urlParsed.query;
        if(query != undefined) {
          predicate = query.q;
        } else {
          res.writeHead(400);
          res.end('Query expected. Use q=... in the URL');
          return;
        }
        async.parallel([
          function(callback) {
            callRestService(serviceUrls['goo'] + predicate, 'goo', callback);
          },
          function(callback) {
            callRestService(serviceUrls['twit'] + predicate, 'twit', callback);
          }
        ],
        //callback
        function (err, results) {
             //use the results argument and a haml template to form the view.
        }
      );
      break;

Through the async module, both GET requests are fetched in parallel. The callback function is called after all functions in the first argument async.parallel have been completed; the ‘results’ argument in the callback function accumulates the search results in an array. The function ‘callRestService’ gets the JSON results and parses them in hashes of format {url: …, text: …}. Let’s implement it:

    function callRestService(url, serviceName, callback) {
        request = rest.get(url);
        request.addListener('success', function(data) {
            searchResults = [];
            if(serviceName == 'goo') {
              dataJson = JSON.parse(data).responseData.results;
              for(sr in dataJson) {
                searchResult = {}
                searchResult.url = dataJson[sr].url;
                searchResult.text = dataJson[sr].title;
                searchResults.push(searchResult);
              }
            } else if(serviceName == 'twit') {
              dataJson = data.results;
              for(sr in dataJson) {
                searchResult = {}
                searchResult.url = 'http://twitter.com/' + dataJson[sr].from_user +
 '/status/' + dataJson[sr].id;
                searchResult.text = dataJson[sr].text;
                searchResults.push(searchResult);
              }
            }
          callback(null, searchResults);
        });
        request.addListener('error', function(data) {
          sys.puts('Error fetching [' + url + ']. Body:\n' + data);
          callback(null, ' ');
        });
    }

The callback function in async.parallel takes the search results and will a use haml template to produce the view for web serving. Here’s the template (search-res.haml):

%h1 Search results
  :if items.length === 0
    %p There are no search results
  :if items.length > 0
    %table
      :each sr in items
        %tr
          %td %a{href: sr.url}&= sr.text

We’ll load this template and use it subsequently in the callback function:

    //load template; this goes before http.createServer
    var searchResHamlTemplate;
    fs.readFile('./search-res.haml', function(e, c) {
        searchResHamlTemplate = c.toString();
      });

The callback function above is implemented like this:

        //callback
        function (err, results) {
          //results accumulated two arrays of search results,
          //for google and twitter respectively.

          res.writeHead(200, {'Content-Type': 'text/html'});
          var searchItems = [];
          for(i=0;i<results.length;i++) {
            for(sr in results[i]) {
              searchItems.push(results[i][sr]);
            }
          }
          res.end(haml.render(searchResHamlTemplate, {locals: {items: searchItems}}));
        }

Done. You can grab the complete code here: servus.js. The final version contains a few more bits to be able to properly respond to GET queries. Querying the server using http://localhost:8124/aggregate?q=worldcup will render a few google results on top followed by all twitter search results.

Adding a Service Level Agreement guarantee
What if we want to add SLA (service level agreement) to our little server? Some web service clients require that servers respond within a guaranteed time. Turns out it’s not hard at all. We only have to add one more function in the parallel.async call that is called after the preset timeout using setTimeout:

    var timeoutReached = false;
...
        async.parallel([
          function(callback) {
            callRestService(serviceUrls['goo'] + predicate, 'goo', callback);
          },
          function(callback) {
            callRestService(serviceUrls['twit'] + predicate, 'twit', callback);
          },
          function(callback) {
            setTimeout(function() {
              if(!timeoutReached) {
                //serve search results if any
                serveContent(partialResults);
                sys.puts("Timeout reached");
              }
            }, 200);
          }
        ]);

partialResults is an array where search results are accumulated as they come in. If this array size becomes 2 then we know that the fetch/parse has completed and the result can be served to the view:

    function callRestService(url, serviceName, callback) {
        request = rest.get(url);
        request.addListener('success', function(data) {

...same as before...

           partialResults.push(searchResults);
           if(partialResults.length ==  2 && !timeoutReached) {
             sys.puts("Timeout not reached");
             serveContent(partialResults);
           }
        });

    function serveContent(results) {

...same as before...

      timeoutReached = true;  //prevent further search results to be processed
    }

Lastly, timeoutReached flag is turned off in serveContent to prevent further results to be processed.

I’ve attached the final version of servus.js with sla: servus-sla.js. The code is available now in a github project called servus. The sla timeout is specified as an argument when starting nodejs. If none is specified, the default is 2 seconds.

If you’re behind a corporate proxy, use proxychains. You can find more details about this issue here

Update Mar.04 Thanks to @ewolff some of the points described below are now official feature requests. One (SPR-6928) is actually scheduled in Spring 3.1 (cool!). I’ve updated the post and added all open tickets. Please vote!

This post is somewhat a response to InfoQ’s Comparison of Spring MVC and JAX-RS.
Recently I have completed a migration from a JAX-RS implementation of a web service to Spring 3.0 MVC annotation-based @Controllers. The aforementioned post on InfoQ was published a few days after my migration so I’m dumping below the list of problems I had, along with solutions.

Full list of issues:

• Same relative paths in multiple controllers not supported
• @ExceptionHandler is controller-centric
• Standard content negotiation can’t respond with a fixed response type
• JSR 303 bean validation not applied in @Controllers
• Formatting responses (i.e. Date) not working when using Spring formatter annotations

Same relative paths in multiple @Controllers not supported
Consider two Controllers where I use a versioned URL and a web.xml file that uses two URL mappings:

@Controller
public class AdminController {
   @RequestMapping("/v1/{userId}")
   public SomeResponse showUserDetails(String userId) {
      ...
   }
}

@Controller
public class UserController {
   @RequestMapping("/v1/{userId}")
   public SomeOtherResponse showUserStreamtring userId) {
      ...
   }
}
In web.xml:
	<servlet-mapping>
	  <servlet-name>public-api</servlet-name>
	  <url-pattern>/public</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
	  <servlet-name>admin-api</servlet-name>
	  <url-pattern>/admin</url-pattern>
	</servlet-mapping>

Here I want to implement handling for /admin/v1/{userId} as well as /user/v1/{userId}. Each controller serves a different purpose (admin and public) and I want to keep the servlet application contexts separate for each servlet mapping (for instance add authentication and different view resolvers to all /admin/* URLs).
Deploying this configuration barfs the following exception:

java.lang.IllegalStateException: Cannot map handler [UserController] to URL path
[/v1/{userId}]: There is already handler [com.test.controller. UserController@6b177115]
mapped.

I would like Spring MVC to account for web.xml servlet mappings before deciding that two identical @RequestMappings in different controllers refer to the same URI. My solution was to have all @RequestMappings specifying the full path and resorting to a custom view to work around this issue).

@ExceptionHandler is controller-centric
RESTful web services respond with the usual HTTP responses (200s, 400s, 500s, etc.). These responses are being mapped from application exceptions and it only makes sense to specify the same @ExceptionHandler for all @Controllers since most (if not all) exceptions handled by them are for the same business domain. Currently SpringMVC only supports declaring and @ExceptionHander per controller and not globally per webapp. This forces the implementors to extend their @Controller classes from a common one where the @ExceptionHandler is specified or, to use composition and delegate exception handling to one service which leads to duplication. Both are ugly. There are several ways to deal with exceptions (check SPR-5622; please guys, add this to the main Spring documentation) but ideally I’d like to see a global scoped handler like @ExceptionHandler(scope=APPLICATION) where I can remap once framework exceptions to more suitable ones that translate into proper error codes (like working around SPR-5622 like issues).

Standard content negotiation can’t respond with a fixed response type (SPR-6937)
Here’s a simple requirement: Implement an RSS feed that serves a user’s activity stream.
Here’s another requirement (make that best practice):

Service methods should have as arguments primitives, wrappers or other POJOs and
 respond with void, primitives, wrappers or other POJOs.

I want testability, readability and portability for service classes and using framework objects for arguments/return objects adds unacceptable clutter.
As such, no framework objects are allowed as arguments or return types in a @Controller and in this case I don’t want to work with ModelAndViews just to be able to select the desired View.
Since this new requirement (add RSS view) belongs to the user domain, I want to add a method in the UserController class that returns a POJO which should be always unmarshalled into RSS regardless of request content type (there goes ContentNegotiationViewResolver). The same controller has other methods returning POJO view objects that I want marshalled into JSON or plain text response body and an HTTP response status. This is already available in RESTEasy via the elegant Produces annotation. The same RESTful controller should respond with different response types for different requests since I want to keep its domain centered around the user (and not response types).

...
public class UserController {
...
   @RequestHandler("/rss/{userId}")
   public SomePOJO getRssFeed(String userId) {
      ...
      //returns a POJO that should always be resolved by an RSS view
   }

   @RequestMapping("/activity/{userId}")
   public SomeOtherPOJO showUserStream(String userId) {
      ...
      //return POJO that should always be resolved by a JSON view
   }
...
}

It turns out this is not immediately possible. To my knowledge none of the included view resolvers provide a straight mapping between URLs and views so I had to write one that configures like this:

<bean class="UrlToViewViewResolver">
   <map name="urlToViewMap">
      <property key="/user/rss/*" value="rssView"/>
      <property key="/user/activity/*" value="jsonView"/>
      ...
   </map>
</bean>

The implementation (not included) is trivial and based on AntPathMatcher, a utility class readily available in Spring.

JSR 303 bean validation not applied in @Controllers (SPR-6928, scheduled for 3.1)
On Springsource’s weblog there’s a nice tutorial on how to get validation and type conversion in Spring 3.0 here. When it comes to validation though, Spring only supports it “after binding user input to it”. It is not possible to validate arguments and return types for a RESTful controller (no web forms or user input of any kind there). This means this won’t work out of the box:

   @RequestHandler("/admin/", method = RequestMethod.PUT )
   public void updateUser(@Valid User user) {
      ...
      //returns a POJO that should always be resolved by an RSS view
   }

since in a RESTful scenario the User object won’t be bound from a form but unmarshalled from XML/JSON/CSV or any other wire format.
To enable validation for a RESTful controller I chose to use @Valid at the method level and add an around advice that intercepts all methods annotated as such then use a Validator to validate arguments and return objects.

<aop:config proxy-target-class="true">
	<aop:pointcut id="validatableMethodExecution"
        expression="execution(* com.mycorp..*.*(..)) and @annotation(javax.validation.Valid)"/>

	<aop:aspect id="validateArgumentsAndReturnObject" ref="validatorAspect">
		<aop:around pointcut-ref="validatableMethodExecution" method="validate"/>
	</aop:aspect>
</aop:config>

public class ModelValidatorAspect {
	@Autowired
	private Validator validator;

    public Object validate(ProceedingJoinPoint pjp) throws Throwable {
        Set<ConstraintViolation> violations =new HashSet<ConstraintViolation>();
        for(Object obj : pjp.getArgs()) {
            if(obj != null) {
                violations.addAll(validator.validate(obj));
            }
        }
        if(!violations.isEmpty()) {
            throw new BadRequestException(composeErrorMessage(violations));
        }

        Object ret = pjp.proceed();

        //validate return object and throw exception if the validation fails.
        if(ret != null) {
            violations = validator.validate(ret);
        }
        if(!violations.isEmpty()) {
            throw new BusinessValidationException(violationsStr);
        }
   }
}

This could get more complex if you have deal with collections of validatable objects but it’s not hard to enhance the code to handle that.

Formatting responses (i.e. Date) not working using Spring formatter annotations
Spring comes with some niceties like @DateTimeFormat and @NumberFormat and naturally I want to rely on them by annotating the class attributes of return types used by @Controllers.
That’s not quite working since the formatters work with form-backed model objects. However, if you use a MappingJacksonJsonView there is a way of formatting using Jackson’s own @JsonSerialize.

Although at times it felt that the switch to SpringMVC was too much, the features that come with it (like abstracting web-related properties as annotations) will turn your RESTful controllers into annotated POJOs focused on the business domain which ultimately means maintainable code.

Update Mar.04 I left out several points about JSON marshalling that didn’t work as expected (Jackson marshaller is a handful).
- One enhancement I suggested to ease the pain of configuring JSON marshalling is creating a namespace similar to oxm (SPR-6943)
- The second was to add Jetisson support (SPR-6938) as an alternative to Jackson JSON marshaller.

I’m keen on your feedback regarding these issues so if you have better solutions please comment.

<repository>
  <id>SpringSource Enterprise Bundle Repositorys</id>
  <url>http://repository.springsource.com/maven/bundles/milestone</url>
</repository>

and the spring packages that you need since the packaging has changed from 2.5.x. Instead of a single spring.jar file, now there is one per feature so you have to sort out what jars to include in the project. I ended up with the following:

  <properties>
      <spring.version>3.0.0.M2</spring.version>
  </properties>
  <dependencies>
   ...
  <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.core</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.web</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.transaction</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.orm</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.jdbc</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.web.servlet</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.context</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.aop</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.expression</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>org.springframework.test</artifactId>
      <version>${spring.version}</version>
    </dependency>
  </dependencies>

Once the jars are brought, I’ve replaced my old jarfiles with the all-new M2s then fired the build target.
The first issue I found was with the asm version.

Spring 2.5 uses a repackaged asm version 2.2.3 (more info here). The new Spring 3.0 M2 doesn’t package it anymore ( see comment) so I had to add it manually. I had to add the two asm 2.2.3 jars in order to resolve this dependency:

   <dependency>
     <groupId>asm</groupId>
     <artifactId>asm-commons</artifactId>
     <version>2.2.3</version>
   </dependency>
   <dependency>
     <groupId>asm</groupId>
     <artifactId>asm</artifactId>
     <version>2.2.3</version>
   </dependency>

After refreshing the jars and redeployed, I hit the first roadblock, a ClassNoDefFoundError:

Initialization of bean failed; nested exception is
java.lang.NoClassDefFoundError: Could not initialize class
net.sf.cglib.proxy.Enhancer
...
Caused by: java.lang.ClassNotFoundException:
org.objectweb.asm.CodeVisitor

Odd, I didn’t have this error before but as it turns out, I was using a cglib version 2.1.3 which has a hard dependency on asm and I actually had an asm jar version 1.5.3 packaged along with the other jar dependencies. On top of this, there is a problem with an antlr version conflict. Different versions of antlr are required by Spring 3.0 and Hibernate 3.3.1 which I’m also using. This is Jar hell! So I put together a version requirment matrix to sort-out the dependencies between these libraries:

Fortunately the Hibernate folks have changed the default bytecode generation library to javassist starting with v3.2.2. The bummer is the cglib dependency on asm 1.5.3 since this version is in conflict with asm 2.2.3 required by both Spring and Hibernate. The solution is to use a repackaged cglib as explained here.
To get the nodep version of cglib, I added the following snippet in my pom.xml file:

<dependency>
  <groupId>cglib</groupId>
  <artifactId>cglib-nodep</artifactId>
  <version>2.2</version>
</dependency>

I’m taking the opportunity and upgrade to the newer version 2.2 of cglib.
Next is antlr. Spring requires a different version of antlr than Hibernate but fortunately antlr has changed the package notation from antlr.* in v2.x to org.antlr.* in v3.x so it’s safe to include both jars. Let’s get both versions through Maven:

   <dependency>
     <groupId>antlr</groupId>
     <artifactId>antlr</artifactId>
     <version>2.7.7</version>
   </dependency>
   <dependency>
     <groupId>org.antlr</groupId>
     <artifactId>antlr</artifactId>
     <version>3.0.1</version>
   </dependency>

Here’s the mix of jars that works for me with Spring & Hibernate:

I can’t help but notice the compatibility problems with using the Spring & Hibernate mix. It wasn’t easy to fix them and it still feels more of a hack than an actual solution. In Spring’s defense, this is a milestone version so I should expect some wrinkles. I had similar issues when upgrading Hibernate a while back. Hibernate was the first to change their packaging to use feature-centric jars (I think). I recall having issues around antlr and asm. I remember being reluctant at first about the new dependency to javassist but it worked just fine.

Next on the list is refactoring the controllers to use the new REST support of Spring. The majority of my controllers are extending from org.springframework.web.servlet.mvc.AbstractController so I’ll upgrade them to use @Controller stereotype. I’m already familiar with @Controller, I’m using it to route all top URLs found on Spincloud’s header (i.e. features). I use a simple approach: drop the inheritance to AbstractController and change handleRequestInternal:

@Controller
public class WeatherDetailsController extends AbstractController {
...
  @Override
   protected ModelAndView handleRequestInternal(HttpServletRequest request,
     HttpServletResponse response) throws Exception {
    //parse URI to extract stationIDs
...
  }
}

with the much cooler:

@Controller
public class WeatherDetailsController {
...
 @RequestMapping(value="/weather/{stationIds}", method = RequestMethod.GET)
 public ModelAndView displayWeather(@PathVariable("stationIds") String idz,
   HttpServletRequest request, HttpServletResponse response) {
...
  }
}

Last, remove the carbonfive HandlerMapping bean in the spring servlet XML which used to look like this:

 <bean class="carbonfive.spring.web.pathparameter.ParameterizedUrlHandlerMapping">
  <property name="alwaysUseFullPath" value="true"/>
  <property name="mappings">
   <props>
    <prop key="/weather/*">weatherDetailsController</prop>
   </props>
  </property>
 </bean>

Deployed and started the container successfully but when I hit a URL that was supposed to be routed through the new controller, I got the following error:

2009-03-07 20:55:49,072: WARN  PageNotFound:1017
 No mapping found for HTTP request with URI [/weather/15150] in
DispatcherServlet with name 'weather'

Bummer: the URL is not routed to any controller. I initially suspected the DefaultAnnotationHandlerMapping I was using was to blame but after searching on the interweb and finding nothing else worthy and a couple of hours of research in my own code, I discovered that the problem was in web.xml. I had fine grained servlet-mapping URLs, including one that should have routed all URLs starting with /weather that looked like this:

 <servlet-mapping>
   <servlet-name>weather</servlet-name>
   <url-pattern>/weather/*</url-pattern>
 </servlet-mapping>

which is not good anymore. After checking the web.xml file in the Petstore example, I noticed that the servlet mappings can use the greedy <url-pattern>/</url-pattern> to route to one controller then more specific patterns for routing to other controllers. Since I have more than one controller, I changed the mappings like below:

 <servlet-mapping>
   <servlet-name>weather</servlet-name>
   <url-pattern>/</url-pattern>
 </servlet-mapping>
 <servlet-mapping>
   <servlet-name>tag</servlet-name>
   <url-pattern>/tag/*</url-pattern>
 </servlet-mapping>

I like RESTful URLs. They clearly express the intent of the provided resource. We humans speak a language close to REST when we talk to The Internet. 

Take a look at Google’s RESTful search query, probably the most used RESTful URL ever:

http://www.google.com/search?q=your-terms-of-choice

in freeform language this translates to: “Google, search for this term.”

How about the Flickr RESTful tag cluster search service:

http://api.flickr.com/services/rest/?method=flickr.tags.getClusters&
api_key=a6f11b67ae348a7b3f2da0d865b8bc1d&tag=Berlin

In Flickr lingo this means: “Fetch all tag clusters for the ‘Berlin’ tag”.

It doesn’t take much to understand RESTful URLs. They speak the language of the domain they represent and therefore in the Web Services provider-consumer world:

The collection of all RESTful services provided by a domain represents its web-oriented Domain Specific Language.  

DSLs have been around for a long time. For more information check Martin Fowler’s talk on the subject.