Using Velocity Templates with Jersey

Java Server Faces are cool but they do not really support a REST-based, document centric approach (well, perhaps JSF 2.0 has got a bit better here). Jersey is a simple-to-use, but highly configurable implementation of RESTful WebServices (JSR 311). Jersey supports the routing of http-calls according to the URL and the http-headers, and allows to access the http-request and response. But it comes with absolutely no support for the rendering of a response. Thats where Velocity comes handy. Velocity is a template infrastructure, which allows you to use Java beans to fill data into html-pages or other types of documents. In the following I will show how I configured Velocity to be used in a web application and how I used the injection capabilty of Jersey to keep URL-handlers free from infrastructural coding of initializing Velocity.

  1. I used a Tomcat web application server. In principal other application servers can be taken as well, but the way to make libraries available will be different. The Tomcat I used has the version 6.0.26.
  2. Add the Jersey, JAX-WS and the Velocity libraries to the libs of Tomcat. Probably not all the libraries are required but they did not harm. Additionall, as I found out later, I needed libraries from the Velocity-Tools project, velocity-tools and velocity-tools-generic.
  3. Create a new web-application (using Eclipse or NetBeans) for your Tomcat installation. Open the web.xml and enter and configure the Jersey servlet. Have a look on the configuration. You see the packages explicitely named, that Jersey are inspecting.
  4. Now we create a resource class for Jersey. I took an example class from the Jersey Users Guide. When you built and deploy the web-app the resource should become available under the URL: http://localhost:8080/<context-root>/helloworld.
  5. Next step is to bring Velocity into play. The first issue to solve is the location of the Velocity templates. By default Velocity loads its templates from a path in the file system. This is not quite what you would like to have if you have a packaged we application. Fortunately the Velocity Tools project provides a webapp loader, which allows you to package the templates with the web application.We already copied the velocity tool libraries in the lib directory of Tomcat. Now we must configure Velocity to use this loader. We tell Velocity that the webapp loader should be used as resource loader, set the relative path, where the templates will be located and hand over the servlet context. You find the code in the class VelocityResolver.
  6. This brings us to the question where this initialization can be done. As you can see in the last line of code above, Velocity needs to know the servlet context. In principal the servlet context can be accessed in the Jersey resource classes. Jersey makes it available using injection. But is the resource class the right place for the initialization of an infrastructure component? I think not. First, the resource should focus solely on retrieving and rendering data, and should not be mixed up with infrastructure coding. And secondly, we probably want to reuse the Velocity engine across many resource classes.
  7. Fortunately Jersey allows for own InjectableProviders. These providers can be used to extend the injections Velocity provides to resources. This is a very powerful mechanism. So, I wrote a class called “VelocityResolver“, which does nothing more then providing an “Injectable”, which in turn initializes and serves the Velocity engine.
  8. Please note in the code above that the class is annotated as Provider. This is how Jersey recognizes that the class is an Injectable Provider which will be used for injections. Also note the usage of the annotation Context which gives us access to the servlet context which is needed for the initialization of the Velocity engine. Having this in place the usage of Velocity in resource classes is rather simple. The class HelloWorldResource provides an example.
  9. The VelocityEngine is injected using again the annotation @Context. Later a new VelocityContext is created and populated with sample variables. These can be accessed from within the Velocity templates. As you can see in the configuration of the webapp loader above the templates are searched in the folder WEB-INF/mytemplates. If you place there a simple script named mytemplate.vm with a content like Hello $name, the call to the URL http://localhost:8080/<context-root>/helloworld yields “Hello Velocity” as result.
  10. That’s the setup of Jersey with Velocity. You can use this couple for the provisioning of documents of any format according to the REST principals from within any web application server. I’m going to use this framework for the rendering of data that I store in a CouchDB. CouchDB fits very well to the REST apporach, as it stores documents instead of records within a table. It is extremely fast and supports replication within the cloud. Its rendering capabilities are rather poor, and thats the point where Velocity wins the game. Have fun!

Leave a Reply

You must be logged in to post a comment.