Scala and Spring 3 JavaConfig

Scala, Spring 3, Actor, REST, IoC configuration by code...
... and well, I should be able to put some other buzz words in that title, perhaps agile and Scrum ?

I wanted to test Spring 3 "configuration via code" new feature, and especially how well it works with Scala.

As a Tapestry 5 (former) user, I'm a great fan of IoC configuration done in Java (or Scala). From a developer point of view, it's so much more easy and robust (especially refactoring prone) to have access to a real, type safe language in place of an ersatz like XML... and most of the time, it's also much less verbose.

The application
I needed a pretext and decided to build a trivial web application that allows to upload files to some URL, and post-process them - a rather usual need in a web-application. That will allow to test Spring 3 new "REST" features, a bit of Expression Language, and put in a little Scala Actor to let the (long) processing be done asynchronously.
I also used maven, and Slf4j with NoCommonsLogging to be able to use Slf4j with Spring.

What exactly does the application:
- wait uploads on a REST endpoint URL;
- when an upload comes, save it into a temporary file;
- signal the file's availability to a "file processor". That processing may take a looooooong time to process (for example, it's a big XML report, with a lot of parsing, input validation, graphs generation, etc), and so, the processing should be done in a side process.

Results
Everything comes along really well, and the result is available on github.

To test it, you will need a JVM and Maven (if you haven't done it yet and are not limited by production constrains, just go download the last 1.6 JVM (1.6.0_18), the performances improvements with the last two releases are impressive)

% git clone git://github.com/fanf/scala-spring3-upload.git

% cd scala-spring3-upload

% mvn jetty:run

You should have a Jetty server up and running on localhost.
Now, you can upload a file to http://localhost:8080/upload, and see that the upload is processed and HTTP code returned, and then an asynchronous process is launched to process the file - well, actually it just waits 10 seconds and delete it.
On Linux, you can use Curl to post files:

% curl -F FileToUploadName=@/path/to/the/file/to/upload http://localhost:8080/upload/

Details about the project
Here comes the different files and their purpose:

src/main/webapp/WEB-INF/

It contains usual servlet configuration files, in XML :
- web.xml : standard Java servlet config file, nothing to see here. with a reference to the annotation based context loader and the AppConfig.scala file.

- upload-servlet.xml : Spring servlet config file. It's this one that is Spring default enter point, and it contains an entry point to the Scala file used for bean configuration, and to the prope


I just don't understand why this last file is needed. It's where you feel that JavaConfig was an afterthought in Spring... Couldn't have we a convention in place of that ? Something like "put your master configuration code in that package" ? All in all, it's small pain to have to write that file, but it also bring really little information. 


UPDATE: as Chris Beams shows me, I should have RTFM more carefully. It's now possible (I do believed it wasn't in first RCs), and I updated the sources to have a full ScalaBased configuration.

src/main/scala/org/test/upload

That package contains the code to receive file (UploadEndpoint.scala) and process them (FileProcessor.scala).
As you can see, there is very little code, and most of it is self-explanatory.

src/main/scala/org/test/upload/config

That last package only contains the AppConfig.scala file, the place where Spring IoC configuration is done.
I really like the cleaness of that file, compared to what may have been the equivalent XML one.
The default sleepTime value is especially cool, typically a things hard to do when you only have XML

Conclusion
This little project could be a good starting-point if you want to use Spring 3 with Scala, or Slf4j with Spring.
I'm also rather impressed by how much little code is needed with Spring 3 to configured the REST endpoint.
And building little asynchronous services thanks to actor is just too simple (OK, here it's a toy, but if you want serious business with actor, look at AKKA).

Tapestry 5 - Scala : view article in HTML, JSON or XML

We must have the REST in our blog, it will attract a lot of investors

The last time we saw how to make basic CRUD functionalities for the blog. That was quite a long time, because I started to encounter some rough edges that make Scala and T5 don't go together as smoothly as expected. Nevertheless, all problems were worked around.

This article is about how simply one can customized the output format of her URL in a RESTful way (see that for more details about REST, but whatever says this too academic article, we all well know that "REST" means "pretty shiny URLs" and "being 2.0, not like whose outdated web service" ;).

So, basically, what we will provide is two different ways of viewing an article:

• A standard, HTML view with this kind of URLs: http://localhost:8080/blog/article/view/1
  
  


• An XML or JSON output, with this kind of URLs: http://localhost:8080/blog/article/view:xml/1 or blog/article/view:json/1
  
  

  
  <article title="First article" id="1">
      <published>true</published>
      <content>Content for the first article</content>
      <creationDate>2009-03-24 16:16:31.865 CET</creationDate>
  </article>
  

  
  And:
  

  
  {"article": {
    "@published": "true",
    "@title": "First article",
    "@id": "1",
    "content": "Content for the first article",
    "creationDate": "2009-03-24 16:16:31.865 CET"
  }}
  

The "view article" page

The first step here is to build a page that will show an article based on it's id.
We want that an URL like: http://localhost:8080/blog/article/view/1
Return the page:


For that, we add a ViewArticle class and ViewArticle template in the package "org.example.blog.pages.article".

The template is trivial, we simply display meaningful information of a backed article object:
org.example.blog.pages.article.ViewArticle.tml

<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">

 <h2>${article.title}</h2>
 <h4>by ${authorname}, on ${article.creationDate}</h4>
 
 <div>
  ${article.content}
 </div>

</t:layout>

And that's all.

The Scala class is not much more complicated:
org.example.blog.pages.article.ViewArticle.scala

class ViewArticle {

  @Inject
  var articleDao : ReadDao[Article,String] = _

  @Inject
  var conf : BlogConfiguration = _
  
  @Property
  var article : Article = _
  
  var id : String = _
  
  def onActivate(id:String) { this.id = id }
  
  def getAuthorName() = this.conf.getAuthor.getLogin
  
  def setupRender {
    this.article = this.get(id)
  }

  private def get(id:String) = 
    if(null == id ) NoneArticle
    else this.articleDao.get(id).getOrElse(NoneArticle)
}

We see that I use two services, the Article DAO that allows to retrieve article from their store, and the blog's configuration that is used to display to author name: the article object it accessible from the template because of the @Property annotation (this T5 annotation is in fact the same as the Scala @BeanProperty one, it generates the pair of getter/setter for the attribute), getAuthorName() is called in the template by ${authorname}.

The logic of the page is almost inexistent: when the page is activated (what means an HTTP request is handled by that page), we store the "id" parameter (in our example, it's "1") for when the page is rendered. There is more about Tapestry 5 page activation and parameters here.
When the page is rendered, we ask the article DAO to retrieve the article with the given ID. If none is found, or if the given id was null (no parameter was found in the URL), we used a special "NoneArticle" object for the rendering. This object is a placeholder that stands for "null" for article type, and is defined as follow:

org.example.blog.data.Article.scala

object NoneArticle extends Article(None) {
  creationDate = new Date(0L);
  title = "No such article"
}

And with that, the HTML view is over.

Marshalling article

Here we deal with the transformation of article object into XML or Json, and how we make a service for that task available in our blog.

XStream, the swiss-knife of serialization

Well, in fact I will confess something: I did almost nothing to make the other two output renderings works, it's basically only the mapping of an XStream output to some Tapestry 5 event handlers.

If you don't already know XStream, stop reading here, and just go and look for its 2 minutes tutorial - it's actually a two minutes thing to read and shows how powerful Xstream is.

For the lazy clicker, there's a summary: XStream is an amazing XML and JSON marshalling and unmarshalling library for Java. It's fast, it's powerful, it's broadly used with all the good that that carries, and its learning curve is counted in seconds.

Basically, without any configuration, you can use it like that:

Person joe = new Person("Joe", "Walnes");
XStream xstream = new XStream();
String xml = xstream.toXML(joe);

And it will output something like that:

<org.foo.domain.person>
  <firstname>Joe</firstname>
  <lastname>Walnes</lastname>
</org.foo.domain.person>

With one more config line for the Xstream object:

xstream.alias("person", Person.class);

You get a prettier output:

<person>
  <firstname>Joe</firstname>
  <lastname>Walnes</lastname>
</person>

Doesn't it look simple? And if I say that it also works for JSON output, and also in the reverse way (from JSON/XML to Object), that output customization is almost infinite, you're likely to fall in love with this little, cute library.

Marshalling services for our blog

In the pages, we only need a simple service that transform object to a String representation. As always, we define an interface for that service:

org.example.blog.services.Marshaller.scala

trait Marshaller { 
   def to(o:Any) : String
}

Next, we are going to build two implementation for that service, one for XML output and one other for the JSON output. The two of them will extend a common Xstream based Marshaller:

org.example.blog.services.impl.XstreamMarshaller.scala

class XstreamMarshaller(val xstream:XStream) extends Marshaller  {
  override def to(o : Any) = this.xstream.toXML(o)
}

class XmlXstreamMarshaller() extends XstreamMarshaller(new XStream(new DomDriver()))

class JsonXstreamMarshaller() extends XstreamMarshaller(new XStream(new JsonHierarchicalStreamDriver()))

There is only one step remaining to enable the service in our blog: binding interface and implementation in the Tapestry module definition:
org.example.blog.services.AppModule.scala

object AppModule {
  //bind is a conventionnal method name for binding interface and implementation when no special configuration is needed
  def bind(binder : ServiceBinder) {
    binder.bind[Marshaller](classOf[Marshaller],classOf[impl.XmlXstreamMarshaller]) withId "xmlMarshaller"
    binder.bind[Marshaller](classOf[Marshaller],classOf[impl.JsonXstreamMarshaller]) withId "jsonMarshaller"
  }

Note that we assign a name (an Id) to each marshaller. That's because we now have two implementations for a given interface declared in the IoC registry. Tapestry 5 will not be able to know automatically what we really want to use when we will require a service injection for that interface, and so we will have to precise the name of the actual service we really want.

An now, let's use these marshallers to render JSONinfied and XMLified articles.

Binding URL to marshaller output

This second part aims to produce the correct output based on the URL.

T5 event handling system

Again, I did nothing special to bind URL and XML/JSON output since I used the standard Tapestry 5 event system: Url with ":" after a component or page name are interpreted as "component:eventname/eventparams".

For example, http://localhost:8080/blog/article/view:xml/1 means: throws the "xml" event on page "article", with the "1" parameter.

For our use case, the only thing to do is to handle "Xml" and "Json" events in the Scala back end of the "Article/View" page. Like most of the time in Tapestry 5, these event handlers are based on convention, and here the convention is to use "onEVENT" for the method name, where "EVENT" is the name of the event to handle.

The modified ViewArticle class looks like:

org.example.blog.pages.article.ViewArticle.scala

class ViewArticle {

  @Inject
  var articleDao : ReadDao[Article,String] = _

  @Inject
  var conf : BlogConfiguration = _
  
  @Inject @Service("xmlMarshaller")
  var xmlMarshaller : Marshaller = _
  
  @Inject @Service("jsonMarshaller")
  var jsonMarshaller : Marshaller = _

  @Property
  var article : Article = _
  
  var id : String = _
  
  def onActivate(id:String) { this.id = id }
  
  def getAuthorName() = this.conf.getAuthor.getLogin
  
  def setupRender {
    this.article = this.get(id)
  }
  
  def onXml = new TextStreamResponse("text/xml",this.xmlMarshaller.to(NoneArticle))
  def onJson = new TextStreamResponse("text/plain",this.jsonMarshaller.to(NoneArticle))
  
  def onXml(id:String) = {
    new TextStreamResponse("text/xml",this.xmlMarshaller.to(this.get(id)))
  }

  def onJson(id:String) = {
    new TextStreamResponse("text/plain",this.jsonMarshaller.to(this.get(id)))
  }
  
  private def get(id:String) = 
    if(null == id ) NoneArticle
    else this.articleDao.get(id).getOrElse(NoneArticle)
}

Compared to the first version, we just injected two marshallers and used them in event handlers. I set-up specific handlers for the case when no parameter is given in the URL.

Note that we solved the injection ambiguity problem on "Marshaller" injection by naming the service we really want to be injected thanks to the "@Service("name")" annotation after the @Inject one.

The only other remarkable thing is the TextStreamResponse object, that allows to return arbitrary text output for rendering. It's an implementation of the StreamResponse interface, that allows to return arbitrary content - yes, returning a PDF for a given URL is a matter of returning the correct StreamResponse in a handler method. Simple, no ?

With that, we have a first promising result.

http://localhost:8080/blog/article/view:xml/1 leads to:

<org.example.blog.data.Article>
  <published>true</published>
  <comments class="scala.Nil$"/>
  <content>Content for the first article</content>
  <title>First article</title>
  <creationDate>2009-03-25 14:19:41.940 CET</creationDate>
  <id class="scala.Some">
    <x class="string">1</x>
  </id>
</org.example.blog.data.Article>

And http://localhost:8080/blog/article/view:json/1 leads to:

{"org.example.blog.data.Article": {
  "published": true,
  "comments": {
    "@class": "scala.Nil$"
  },
  "content": "Content for the first article",
  "title": "First article",
  "creationDate": "2009-03-25 14:19:41.940 CET",
  "id": {
    "@class": "scala.Some",
    "x": {
      "@class": "string",
      "$": "1"
    }
  }
}}

And non existing article or no parameter, like in http://localhost:8080/blog/article/view:xml/foobar leads to:

<org.example.blog.data.NoneArticle_->
  <published>false</published>
  <comments class="scala.Nil$"/>
  <content/>
  <title>No such article</title>
  <creationDate>1970-01-01 01:00:00.0 CET</creationDate>
  <id class="scala.None$"/>
</org.example.blog.data.NoneArticle_->

That's not too bad for a couple of line of code, but output should be nicer.

Configuring output

Actually, we don't want to show the qualified class name in the output, nor we need the comments here, and it will be cool to have "id" and "title" as attributes of the "article" node.

For that, we will customized Xstream marshaller.

The first step is to change the marshaller implementation registration in AppModule to a more configurable one:

org.example.blog.services.AppModule.scala

  def bind(binder : ServiceBinder) {
    //remove marshaller from here
  }

  def buildXmlMarshaller(): Marshaller = {
    val m = new XmlXstreamMarshaller
    ConfigureArticle4Xstream.configure(m.xstream)
    m
  }

  def buildJsonMarshaller(): Marshaller = {
    val m = new JsonXstreamMarshaller
    ConfigureArticle4Xstream.configure(m.xstream)
    m
  }

These new definition also build two marshallers, named "XmlMarshaller" and "JsonMarshaller", but with that way we are able to configure the Xstream instance of each implementation.
Since our case is really simple, the two configurations are the same, and look like that:

org.example.blog.services.impl.XstreamMarshaller.scala

object ConfigureArticle4Xstream {
  def configure(x:XStream) {
    import org.example.blog.data.{Article,NoneArticle}
    //output "article" in place of org.example.blog.data.Article
    x.alias("article",classOf[Article])
    
    //title and id will be output as attributes of article...
    x.useAttributeFor(classOf[Article],"title")
    x.useAttributeFor(classOf[Article],"id")

    //...and since Id is not a simple string, we have to provide a converter to make it works
    x.registerLocalConverter(classOf[Article],"id",new ArticleIdConverter())
    
    //we don't want to display comments
    x.omitField(classOf[Article],"comments")
    
    //special config for NoneArticle
    x.alias("article",NoneArticle.getClass)
  }
}

Each line provides the commented explanation.
The id converter simply output the id if available, or "none":
org.example.blog.services.impl.XstreamMarshaller.scala

class ArticleIdConverter extends SingleValueConverter {
  def fromString(s:String) = if("none" == s) None else Some(s)
  def toString(a:Object) = a match { 
    case None => "none" 
    case Some(x) => x.toString 
    case _ => error("Not supported type: " + a.getClass.getName)
  }
  def canConvert(c:Class[_]) = {
    if(c == classOf[scala.Option[_]]) true
    else false
  }  
}

With this configuration, outputs are much nicer:

http://localhost:8080/blog/article/view:xml/1 leads to:

<article title="First article" id="1">
  <published>true</published>
  <content>Content for the first article</content>
  <creationDate>2009-03-25 15:09:20.476 CET</creationDate>
</article>

And http://localhost:8080/blog/article/view:json/1 leads to:

{"article": {
  "@title": "First article",
  "@id": "1",
  "published": true,
  "content": "Content for the first article",
  "creationDate": "2009-03-25 15:09:20.476 CET"
}}

And non existing article or no parameter, like in http://localhost:8080/blog/article/view:xml/foobar leads to:

{"article": {
  "@title": "No such article",
  "@id": "none",
  "published": false,
  "content": "",
  "creationDate": "1970-01-01 01:00:00.0 CET"
}}

Now, we can say too our chief that he can go and look for investor, our blog has the REST (well, almost ;).
And that's all for today !

Next time

We reach a rather satisfying result with really few lines of code, but I have to say that our implementation is bad.

The main reason for that is that there is a bunch of coupling and code duplication at the moment:
- from the page designer point of vue, it's crappy to have to inject several marshallers, and choose the correct one for each event;
- moreover, addind a new output (for example, plain text) would mean modifying *all* pages that use marshallers;
- with the actual configuration, each time that we want to customize an output for a given object, we have to actually modify the code of XstreamMarshaller core implementation, or in the core module definition !

So the next time, we will see how we can improve these points. And again, it will be easy, thanks to Tapestry IoC provided features.

As always, the real full code is available at Github at this tag :
http://github.com/fanf/scala-t5-blog/tree/article4_20090325