It has been not even a full week building REST style interfaces for the Playmaker Studio mobile platform and I am very annoyed of all the curl guides how to access your REST API with curl. So here is my cheat sheet on this topic. Be aware that the I will update this frequently.

Common use cases

GETting data from a URL

This is a very simple use case just use:

curl https://graph.facebook.com/740999649
{"id":"740999649","name":"Niclas Meier"}

curl will automatically use the HTTP method GET.

POSTting updates

In the REST dictionary the HTTP method POST represents the verb ‘update’. So updating data implies a POST request to an URL.

Basic

Let’s have a look at the basics, I added some (revised / half the original) debugging output by supplying the -v option.

curl -v -X POST http://localhost:8080/1/stuff/23f96c6bd4c87910c.json -d 'name=Niclas'

> POST /1/stuff/23f96c6bd4c87910c.json HTTP/1.1
> Host: localhost:8080
> Accept: */*
> Content-Length: 11
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8
< Content-Length: 25
<
Stuff: 23f96c6bd4c87910c

There are some options involved:

• -v added the request/response header for debugging
• -X specified the request method (POST) to use.
• -d added some data in the request (POST) body.

So the 'name=Niclas' was sent to the server using the request body, but curl does not display the request body using the -v option.

Using a JSON body

So this is nice, when you want to post key-value pairs to your server, but many applications (e.g. CouchDB want to post JSON objects to the server. The initial guess

curl -v -X POST http://localhost:8080/1/stuff/23f96c6bd4c87910c.json -d '{"name":"Niclas"}'

Stuff: 23f96c6bd4c87910c, JSON body:

does not work. That’s where the content type comes in. If you post the JSON whiteout supplying the proper content type curl and/or the server will try to use application/x-www-form-urlencoded^* content type. This is the same content type your browser uses when submitting a form to a web server. Doesn’t sound bad, does it?

But it’s bad because the JSON will be ignored/dropped/whatever and the server is unable to understand the request. To solve the problem use:

curl -H "Content-Type: application/json" -X POST  http://localhost:8080/1/stuff/23f96c6bd4c87910c.json -d '{"name":"Niclas"}'

Stuff: 23f96c6bd4c87910c, JSON body: {"name":"Niclas"}

So these options are involved

• -X specified the request method (POST) to use.
• -H added the header Content-Type: application/json to the request.
• -d defined the data used for the request body ({"name":"Niclas"}).

A JSON file as body

So far so good. But if you have huge JSON requests, you don’t want to type all the JSON into the console. You may use the @ symbol in conjunction with the -d option so curl will read the request body contents from a file. This may look like this.

curl -H "Content-Type: application/json" -X POST  http://localhost:8080/1/stuff/23f96c6bd4c87910c.json -d @some-huge-request.json

Stuff: 23f96c6bd4c87910c, JSON body: {"name":"Niclas", ..., "foo":"Bar"}

A nice trick is, that if you use the -d with @-. curl will read the request body from the standard input. So you can do stuff like this:

cat some-huge-request.json | curl -H "Content-Type: application/json" -X POST  http://localhost:8080/1/stuff/23f96c6bd4c87910c.json -d @-

Stuff: 23f96c6bd4c87910c, JSON body: {"name":"Niclas", ..., "foo":"Bar"}

PUTting stuff

Is much like POST, so if you can POST you can PUT. One nasty little difference is, that you don’t have to supply a Content-Type HTTP header for PUT. curl does not use application/x-www-form-urlencoded as content type for PUT. Lost an hour (or so), because I did some PUT stuff before switching to POST.

Debugging

Detailed information

The key to get almost every information by supplying the -v option to curl.

curl -v https://graph.facebook.com/740999649

* About to connect() to graph.facebook.com port 443 (#0)
*   Trying 66.220.147.38... connected
* Connected to graph.facebook.com (66.220.147.38) port 443 (#0)
* SSLv3, TLS handshake, Client hello (1):
* SSLv3, TLS handshake, Server hello (2):
* SSLv3, TLS handshake, CERT (11):
* SSLv3, TLS handshake, Server finished (14):
* SSLv3, TLS handshake, Client key exchange (16):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSLv3, TLS change cipher, Client hello (1):
* SSLv3, TLS handshake, Finished (20):
* SSL connection using RC4-MD5
* Server certificate:
* 	 subject: C=US; ST=California; L=Palo Alto; O=Facebook, Inc.; CN=*.facebook.com
* 	 start date: 2010-01-13 00:00:00 GMT
* 	 expire date: 2013-04-11 23:59:59 GMT
* 	 common name: *.facebook.com (matched)
* 	 issuer: C=US; O=DigiCert Inc; OU=www.digicert.com; CN=DigiCert High Assurance CA-3
* 	 SSL certificate verify ok.
> GET /740999649 HTTP/1.1
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
> Host: graph.facebook.com
> Accept: */*
>
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Cache-Control: private, no-cache, no-store, must-revalidate
< Content-Type: text/javascript; charset=UTF-8
< ETag: "f89bfe40c87e487ae641d427c96746b226a91f3c"
< Expires: Sat, 01 Jan 2000 00:00:00 GMT
< Pragma: no-cache
< X-FB-Rev: 482216
< X-FB-Server: 10.36.50.102
< X-Cnection: close
< Date: Wed, 07 Dec 2011 13:14:19 GMT
< Content-Length: 183
<
* Connection #0 to host graph.facebook.com left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):
{"id":"740999649","name":"Niclas Meier","first_name":"Niclas","last_name":"Meier","link":"http:\/\/www.facebook.com\/people\/Niclas-Meier\/740999649","gender":"male","locale":"de_DE"}

But for may occasions that is simply too much, so check out the -i option.

Header information

Often it’s enough to get only the response headers for debugging. To get only these headers just use the -i option in curl.

curl -i https://graph.facebook.com/740999649
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "f89bfe40c87e487ae641d427c96746b226a91f3c"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 482216
X-FB-Server: 10.42.67.29
X-Cnection: close
Date: Wed, 07 Dec 2011 13:18:24 GMT
Content-Length: 183

{"id":"740999649","name":"Niclas Meier","first_name":"Niclas","last_name":"Meier","link":"http:\/\/www.facebook.com\/people\/Niclas-Meier\/740999649","gender":"male","locale":"de_DE"}

After been almost 10 years at SinnerSchrader it’s very confusing for me to be on the move again. On the 1^st of December I joined Playmaker Studio after being at gamigo for 18 month.You now may ask why? I don’t want to explain every thought that led to the decision, but I can say I enjoyed my job at gamigo. I learned damn much, especially stuff I never anticipated (I am not saying that I didn’t wanted to learn most of it ). I had a great team making a giant leap in the software development processes, nice colleagues and we brought the company a huge step ahead.

But it was more than about time to get a new direction in working life. At gamigo my job drifted to a pure management position and I was nudging around JIRA tickets and Excel files (okay some of them where Google Docs ) the whole day. But now I joined the Ranks of technicians again <cheer />!

Hopefully I will have some time for reviving this blog. For now I am trying to learn some new stuff – like Clojure, Noir, Heroku or mongoDBfor my new job. For me, this sounds like lots of fun!

After some inspiration the last few weeks, I decided to scrape together some spare time and have a closer look at the Scala programming language. This was kind of overdue because I am trying to have a look at new technologies at least once a year.

One major challenge is always finding an interesting topic which also has an appropriate level of difficulty. For my venture into Scala I choose a small open source project which I initiated two years ago called . This small framework validates an e-mail address and also checks the domain (via the DNS). This project seemed to have the right size and so I decided to build a scala variant called saev.

This turned out to be a very demanding venture which challenges a lot of knowledge and beliefs which I have from my activities in the Java environment.I would be lying if wouldn’t tell you, that I already head some doubts on the proceedings in the Java community. Things like having no update on the JDK for about two years now, including the unfortunate discussions on lambda expressions in Java, are paralyzing the development on the language basis. On the other hand side I have no idea how to judge the acquisition of Sun Microsystems by Oracle.

I first stumbled over Scala when I still was working at scoyo, when my former boss was building a small script which was converting localized text into an XML format. I found the language it self quite interesting but when you are in the middle of a Java team it was not easy to get started with it and had other things occupying me more.

Beginning this year I was willing to give Scala a new chance after having a quick look at PHP and Ruby. Both of PHP and Ruby didn’t convince me so I bought a Scala book and read it. But I must confess after this lecture I still was interested but nothing more. But after attending the Developer Conference Hamburg 2011 I decided to give Scala a real try. So I bought another book especially written by Prof. Dr. Friedrich Esser for guys who want to change form e.g. Java to Scala. I just want to take the take the time to recommend this book “Scala für Umsteiger“. Very well written book which shows you in the first chapter (approx. 100 pages) how to write the stuff you do in Java in the Scala language. An then fasten your seat belts

I am playing around with Scala for about a week right now, but I have to confess that I am somehow impressed and also a little bit scared. Let me explain why:
Fist of all the syntactical power of this “post functional” language is impressive for someone who did Java for over ten years. You can describe many of your problem solution in a very simple way. But when you want/need you can always fall back into Java because Scala uses the Java VM as foundation. On the other hand side I met a couple of programmers which are nice people, but who would be overstrained by this. And to be honest there are always situations where I take both of my books and google to figure out what some code is doing and why it’s working.
Don’t get me wrong I am pretty good programmer and I am using even complex concepts like AOP (aspect oriented programming) or dependency injection for a couple of years now. And I know the can cause lots of trouble and I am not sure if I should like @Transactional or not.

For my personal development I am quite sure, that I will continue to investigate Scala a little further. On the business side I am not sure if Scala will find a place in my development team. I said already ten years ago that you can use a bunch of trained apes to finish you Java project. It will take some time but the apes will figure it out. And that robustness is what you want on enterprise projects. Maybe for innovative companies or startups Scala is the language of choice or for companies which are willing to have polyglot development environment.

It’s sunday and I am fed up, sitting lazy behind my computer and taking a review of the last week. I attended two conferences this week so I am full of new ideas (don’t know if they are good yet) and wan’t to take a closer look on so many topics.

The first conference was the next conference in Berlin which was initiated some years a go by my former employer SinnerSchrader. So the focus of the next conference was mixture of brand, media, entrepreneurship and technology. Due to the fact that I meet a couple of former colleagues – some of them still working for SinnerSchrader.

The second conference was the Developer Conference Hamburg 2011 which had a sole technology focus.I heard couple of very good talks on both conferences. My highlight was the the keynote of Werner Vogels the CTO of Amazon which spoke about the analysis of big dataset which are regularly produced by modern IT infrastructures. If you generate a couple of gigabytes of data every day you should get the information out of them.

Another highlight of both conferences where the Couch DB talks. Both held by Jan Lehnhardt, one of the Couch DB core commiters who works for Couchbase. Jan can talk very fast in his talks, especially when he had some coffee . But there is no bull*** and he definitely knows what he is talking about. Because I attended the next and the devcon I was able to get a 10.000m overview and a 100m close look on the Couch DB. I am very fascinated by this topic, but I have at the moment no idea where to use it.

A dilemma what Couch DB shares with node.js. I heard of node on both conference too. On the next node.js was presented by Isaac Z. Schlueter. The topic was how node.js performs on DIRT (data intensive real time) applications. At devcon node.js was presented by Felix Geisendörfer which gave a more wide range overview on the capabilites of node.js. Unfortunately my current employer does at the moment some kind of “boring” e-commerce stuff, so no real use for node here. Some SinnerSchrader guys had a very innovative idea using node building the The World’s First Digital Foosball Table – nice one!

But the most influencing talks where from Prof. Dr. Friedrich Esser from the HAW Hamburg about Scala. The talk and the workshops where full of snappy remarks on Java programming language. I am doing Java for over ten years now. And I am confident that I am pretty good at Java and it was my favorite language the last ten years. But in the recent time I am feeling bored by Java and it’s very tight restrictions. We’ll see where the journey goes with this Scala stuff.

On the other hand side there were also some talks – which we presented brilliantly – that where about stuff that I am doing for a couple of year now. One of these was the “Abstract monitoring” talk from Dr. Johannes Mainusch from Xing. Very nice talk, I agree 100% but I was also doing this since 2005. Good to see that other developers are cooking with water too

But the last week reminded me of the gap what we have at the moment and what I am supposed to close as soon as possible. But now I am armed with some new ideas …

Some of you may already have noticed, that this blog uses WordPress as blog software. Nothing special about that I guess. As I mentioned before in January/February I moved my website from my old provide to a new one making some significant changes to the blog and it’s infrastructure.

I am in the web business since a couple of years and I already worked with a couple of servers. Like most of the others I worked most with the Apache web server. Which is still the work horse of the internet. But recently the nginx web server which is a lean, mean web serving machine. To get a little more experience with this product I decided to use it for my blog.The nginx web server already matured already 9 years and reached recently (12. April 2011) the version 1.0.0 (congratulations on this by the way ). But there are still some major differences between the Apache and the nginx web servers.For me this started when I wanted to use WordPress which is build upon PHP. PHP itself depends on the common gateway interface (a.k.a. CGI) which is a long time component of the Apache web server. Unfortunately the nginx server does not support CGI so you’ll have cover some more basics.

nginx itself supports CGI using the fast CGI standard. Which does actually a little bit more the plan CGI. To serve fast CGI you may use the nginx fast CGI module, so you still have access to all the scripting languages you like. But be aware that the nginx web server is known for it’s fabulous capabilities serving static content.

After installing nginx, a fast CGI wrapper app to execute the PHP scripts and configuring the fast CGI module, the setup of the WordPress blog was pretty basic. I’m using a standard MySQL database backing the WordPress. The whole system runs on a CentOS linux. The choice of the linux distribution was also inspired by the preferred system I use at my job for almost two years. Some times it’s good to stick to things you know

This was the status on which the whole system ran since February. But as a few – regarding to google analytics – of you may have noticed that the whole system was very slow. This is a direct result of my stinginess, because I don’t want to pay more money for my root server

So today I invested some spare time to look for other optimizations and I would like to say, that I was successful. My first search lead to a WordPress plugin to cache the pre-rendered WordPress pages. I have not this much posting and commenting traffic, so pre-rendering the pages seemed to be a good idea. The plugin of my choice is WP Super Cache which provides a very easy to configure caching of WordPress pages.
But I wanted to go one step further: The WP Super Cache plugin offer the possibility to bypass WordPress and PHP completely by using compressed pre-rendered pages via mod_rewrite. I guess most of you noticed the problem: mod_rewrite is an Apache module, which does not work with the nginx server, but nginx provides a powerful rewriting module too. A very helpful blog post from the WP Super Cache author helped to configure the web server. And now – at least for any anonymous user – the site is fast.

It do no longer take about two seconds to return the the first bytes to the user and the page itself is compressed only approximately five kilobytes large. To speed up the perceived loading time of the page, I am using the Use Google Libraries plugin pass the delivery of standard Java Script libraries to google. So the libraries can participate on sharing between different pages and the long time expiry which is used by google. The plugin WP Minify joins and compresses the JS and CSS used by the theme and other plugins I use, so the browser does download only a few minimized files instead of dozens of CSS and JS files.

I can say, that the experiment was quite successful and after getting familiar with some peculiarities the setup process was quite easy.

I just wanted to say, that I am back – at least a kind of

The last couple of month I was buried under a sh****** of work since I joined my new employer, but on the other hand side I a lot of fun and it is a very challenging job.

The last couple of weeks I used some spare time to move my infrastructure to a new home, including this blog. I will shut down my private blog soon, I guess my live is not exciting enough or may be I am not exhibitionistic enough to write over every breath I take. But now this blog is almost completely migrated and got a shiny new theme too – I hope you like it!

The good news are, that I want to take up my technophile blogging activities. I learned very much in the last couple of month about writing good software and what to do to prevent it.

The subject of my first post of the series “Contemporary Software Development” will be building. How to build your software project is a decision which is made quite early when you start developing.

Unfortunately in a lot of projects this very important topic does not get the appreciation it deserves. On one hand side it’s a very sad story of suffering and endurance. On the other hand side we are talking about a lot of wasted money.In my career as software engineer I experienced some different approaches to the project setup and the build process.

It started with something like find . -name '*.java' | xargs javac, which worked quite well for the first weeks of my professional career. But with a couple of software developer working on a project you want something more standardized.

So we went on with make(*). I guess most of the software engineers will know this build tool which still is a standard tool in the Unix/Linux world. make is a very powerful tools but has its peculiarities also. The make grammar is very delicate when it comes to white spaces. I quess quite a few people sat over a broken make build when a TAB char wasted your build script.

In the Java world Apache Ant was the successor to make in my career. The problem with make and the Java world is, that make is not really platform independent. There are make ports for Microsoft Windows but (at least when I made the jump from make to Ant) it does not work very well. So if you have a heterogeneous environment e.g. you develop on Microsoft Windows and you deploy into a Linux based cloud, you want your build to to be platform independent.

A nice story about platform independence. I did some consulting in a project for the Deutsche Bank Italy and a very large (and expensive) consulting company provided the BEA Weblogic build and setup. I am not 100% sure but I guess it was an Apache Ant based build. One major issue was the application server integration integration. To solve it, the complete project was placed and build in the application server which was committed in to the CVS source control management system. The delivery artifact was – of course – delivered without the application server. But this leads to another wish I have when I am using a build. You want the build to credit the current environment. If you are building for your local development environment you may have different requirements concerning the built artifact as when you are creating an artifact that will be deployed on staging or productive environment.

Back on memory lane: Apache Ant worked pretty well for some years and a couple of projects. But one thing that started to annoy me. Every project was using a slightly build setup so in the daily business there were always searching for artifacts or checking library versions.

Some former colleagues introduced me to Apache Maven. I started with Maven 1 which is a quite interesting mixture of Ant with a framework that offered the possibility to manipulate the Ant build file during the runtime. But Apache Maven had some features which I hat to get used to.
An example is the rigid directory structure defined in a Maven build: Why do I have to follow them? I want my special directory names! But nowadays I love this structure which is equal in every project. You find your files so fast now and even in foreign project. That’s another thing that you want: You want your builds to follow standards, so you can get familiar with the project in very short time. If you are working in the software business a couple of years, may have already realized that you will see very much projects during a professional career and standard projects and processes will make your life much more easy.

Let’s talk about some goodies now which modern build system offer. I will use Apache Maven as example but other systems like rake or buildr offer similar functions.

One thing I love/hate is dependency management. When I started with make or ant, we where committing all libraries into our CVS. Which worked quite well, in most cases you could check our the project, performed the initial build and started to work. But there where lots of minor but very nasty problems. Starting from which library version is really used to incompatibilities of the build tool version.

With the Apache Maven dependency resolution mechanism a new area begun. If you are having one independent project the mechanism is pretty easy to use. You define the libraries you want to use in your pom.xml and maven takes care of the rest. Okay if you want to use libraries which are not in the maven central repository it’s a little more complicated

If you are having a multi module/project environment things will get messy pretty easy, but: They would also if you don’t use the dependency management mechanism. You ask why? When you don’t use this mechanism you’ll normally have a huge monolithic project in your SCM system which will get even more difficult to manage or build. So you want to have a transparent dependency management in your build system. With Ivy for example you’ll have an add-on which offers the possibility to have an dependency management when you are using Ant.

Another goodie is release management. It’s very handy if you start a build to create your release artifact and your tag (or something similar) in the SCM system of your choice. You want your release process embedded in your build system, so you can perform the build when you are creating your release.

Another important topic is testing. You really want your build tool to support your testing facilities. At least when you create your release or deployment artifact you want your build to automatically run your test suite.

I have only one topic left in this post, that is IDE support. Unfortunately most modern IDE like Eclipe, Netbeans or Intellij IDEA offer a IDE specific build. This this very comfortable if you have a small project and what to deal only with your IDE. But you’ll grow really beyond this (my experience). But integration into other build tools is sometimes really poor. So you have to check how you can bridge the gap between your IDE and the build tool. E.g. the maven directory structure troubles some IDE
standard configurations. Fortunatly more and more projects provide solutions for this.

So let’s have a quick resume. This is what you should want in your build system:

• standardized process
• platform indipendence (if your need it)
• credit current environment
• standardized structures
• dependency management
• embeddable release process (including SCM support)
• support of your test tools
• IDE support

I think this list is not too lang and offers some major improvements for your daily work. So if your build process is missing some items from this list, you maybe should think about your build process. And remember: Your development resources are far to valuable to be wasted in an inefficient build process

It has been some time since my last blog post. But I promise to do better. I am planning a series ob blog post in which I am trying to explain how you should want to develop software nowadays – at least in my opinon.

I will try to cover topics like: How to build your system? How to manage you source code and you versions? Or what do do with your deployment data?

But I don’t want you to tell you which frameworks to use in fact I want to discuss what you should want to do not how you are going to do it.

I am excited, it will be a lot of work, but I am excited

Some of you may know Apache Tapestry 5 already. It’s a very great framework for building web applications. In my opinion you’ll won’t find a framework this mature and production ready very easy. Tapestry 5 covers a wide variety of topics related to the creation of state-of-the-art web applications. So it’s no surprise that Howard Lewis Ship the creator/founder of the Tapestry Project joined the ranks of the In the company I used to work we depended on Tapestry pretty heavy. We had created a couple very good solutions using this framework but we also had some challenges to meet. I guess they are pretty common to web based companies.

• We had to use a CMS system (Magnolia CMS in this case) to enable the marketing and non-techical guys to maintain all the content they are creating.
• We had to maintain a couple of so called landing pages. I guess most of the web guys know and hate them These pages are just an empty shell containing nothing more than some sightly different logos and graphics of partner companies. The also provide a nice URL in most cases like: http://www.mycomany.com/tv, /mobile or /unameit. Unfortunately some of these landing pages hade some minor dynamical stuff on it.
• Most of this landing pages require that you are storing some (voucher) code into your application to modifier your check-out process a little bit.

So, now you have a couple of pages, of which you don’t know when they appear – and you really don’t want to know, because coordinating the timing with the marketing guys is always a mess -, with very similar structure and functionality. As a matter of fact this case should be a text book example for component reuse. but this is a case where Tapestry 5 and the convention-over-configuration thing works against us.

So what do you have to do in classic Tapestry 5? Jepp you allready guessed it, you have to create a page class for each of this landing pages. Okay thanks to inheritance this class will be de-facto empty. But it is annoying to create this class. You’ll have to create a version of your web application, do a QA cycle (if you want to play it right), make a deployment. So you have a lots of communication with a bunch of other departments. In a world with perfect processes you might to accept this, but I guess most of the guys out there know the situation where a junior business consultant guy stands right at your desk telling you of the nation wide TV campaign that launches tomorrow and that needs this new landing page. Maybe some of you already tried to say the ‘n*’ word

A early solution was to introduce some Meta templates in out CMS. They were some simple HTML comments which where evaluated by a service in our web application and re-assembled via simple Tapestry pages and components. This worked quite well but brought us a bunch of issues – like template caching, dynamic contents in templates, etc. – which are already solved in Tapestry. The solution was also pretty limited in when dynamical and statical parts should be joined together. So I took some time to evaluate a different approach:

My first question was: Is it possible to make tapestry work with pages that do not have a class as backup?

I never tried this, because I figured out, that I actually didn’t want to do this, and as a matter of fact, it makes the whole exercise a lot easier. What I did was to make Tapestry use a default class for pages tapestry does not know. I call this pages virtual pages. I’ll guess you always have some minor data shared between all virtual pages, so you create on page class that Tapestry may use to serve virtual pages.

So how you serve virtual pages with Tapestry 5.1? I was surprised who simple it was (after some month of the wrong track). So this is, how virtual pages may work:

1. Check if the page exists
   A good place to do this is the ComponentClassResolver with its isPageName(..) method. I created a special implementation of the ComponentClassResolver which decorates the Tapestry original.
2. Mark the request
   Mark the request as request to a virtual page. I used a dedicated service with thread scope for this. You also may compute and store some data in this service.
3. Alter page class loading
   Adapt the loading of the component classes to load (and attach) the default class to the page. Another decorated service does the work here too.

And voila you can deliver content for pages with no backing class, astonishing isn’t it? You may look at the small prototype/example project at github and you’ll realize how simple the solution is. The prototype is a slightly modified Tapestry 5 archetype project which will serve the URL http://localhost:8080/About as virtual page.

So far, so good! But now some last words if this is a good solution at all. First I want to mention that we had an integration ready for the architecture we used, but it went – for several reasons, most non-technical – never productive.

Let’s talk about some oddities first:

• The URLs to address the pages do not fully comply the Tapestry behaviour. In Tapstry it does not matter if you request /About or /about, but the prototype only supports a simple template resolution.
• Some Tapestry components/mechanisms won’t work properly. Tapestry uses classes to compute links to pages. Always when this mechanism is used, you’ll may get problems. Components like <t:pagelink ...> may not work properly because you do not have a class. Keep this in mind.
• Unexpected Runtime and memory behaviour. Tapestry is a very stable and production ready framework. But we are misusing it a little bit. Keep a close eye on memory consumption because every HTML page will now be a tapestry template and will be cached in the memory of your virtual machine. Some of some infrastructure components are also optimized for a (relatively) small amount of page instances.

Why do I want to use Tapstry this way? The first advantage is the simple creation of new pages. You’ll create the .tml file and you are done. We used it with a CMS in the background and with some specialized CMS templates the marketing guys where able to create a bunch of landing pages without troubling an IT guy. In addition to the standard page we used some components which contained the major functions of the pages. So we were able to create instance of this virtual pages which behaved sightly different because we passed some parameters using the TML of the virtual page.

Why does not offer Tapestry this mechanism? First: It’s a prototype! If you take a closer look you will se how limited it is. This topic as hole comes across the tapestry mailing list regularly and there are lots of pro’s and con’s. I don’t want to discuss any of them in this blog post. But I agree with the Tapestry guys not to introduce it into the core framework.

At the time I was evaluating this prototype I had some very good reasons to do so and only a few are mentioned here. But if you have a big amount of content it is seldom a good idea to generate templates which are interpreted by a dynamic framework. No matter if you use JSP, Tapestry or even PHP.

I hope you’ll enjoyed reading this blog post. I learned much about Tapestry 5 preparing it and evaluating my idea. If you have questions of any kind feel free to contact me

Here at scoyo we use the Magnolia CMS to manage our website content. It’s a quite nice tool based on the Content Repository API for Java (JCR) (JSR-170). In this blog post I want to tell you a little more about a small domain specific language, which I created to manage the migration of content and configuration of our Magnolia CMS installation, using XML-Schema, JAX-B and the facilities of the CMS.

To introduce you a little more into the domain. When using a CMS with some other software components you’ll have a situation very similar like having a database. You have content which other (non-tech type) people manage and if you change your application sometimes you’ll have to change the content – or worse the structure of the content – too. In the database world there is a very nice book regarding the refactoring of databases.

As a solution to this issue the magnolia CMS offer some API related to the info.magnolia.module.ModuleVersionHandler. This API’s offers the possibility to define info.magnolia.module.delta.Tasks which may be related to specific module version. So the CMS may discover on startup time which Tasks to execute when migrating e.g. from module version 1.4.2 to 1.4.6. This is very nice because you can load partial XML content dumps or move some content (or configuration) nodes around.

Unfortunately you’ll have to do this while program the update procedure in Java in your ModuleVersionHandler. To close this gap we introduced an own domain specific language using XML. I refer to this as DSL because it evolved to be much more like a simple XML config file, I’ll hope you’ll get the point later on. The inspiration gave a freelance contractor with very deep magnolia know-how. So here is how I did it:

First of all the ModuleVersionHandler has to deliver all the information defined in the XML file, so you’ll have to override it. So we subclassed the info.magnolia.module.DefaultModuleVersionHandler to override methods like getExtraInstallTasks(...). This new version handler is responsible for reading the XML file, and converting it into the objects that magnolia handles.

Next step was to define a XML format. It should be an expressive format, nice to read and easy to understand. So waived of standard formats or facilities like the Springframework which also offers facilities to assemble object graphs from XML files. The format we choose looks like:

<updates>
	<version number="1.5.0">
		<description>Changed implementation of header selection</description>
		<updates>
			<load file="config.modules.scoyo.dialogs.pageProperties.xml"/>
			<if-exists repository="WEBSITE" node="/en"><then>
				<set-property node="/de" repository="WEBSITE" property="reportSuiteIdLive"><value>test_en</value></set-property></then>
			</if-exists>

 		</updates>
	</version>
</updates>

which is quite nice to read and you’ll have your documentation in the right place. In order to automatically process it using JAX-B you’ll have to define a XML-Schema which will be used to generate your Java bindings. Besides this it’s always good to have a XML-Schema, I’ll give you some further examples later

Our schema looks like this (at least in eclipe)

We defined some elements (as seen on the left hand side). Each of this elements contains some attributes (or inner elements) which are passed to the magnolia Tasks. The clou of this XML-Schema is the Task type and the <task /> element. The <task /> element is an element, which all elements defining a specific task (e.g. <load />) must have as substitution group. Doing this allows on every place where a <task /> may be placed in XML another element of this substitution group may be placed too. In fact you’ll never use <task /> but always use a specific element like <load />. The Task XML type covers the XML type part of the <task /> element, when generating the XML bindings the Task XML type will be translated into an abstract super class for all specific types like the Load XML type, which defines the structure of the <load /> element.

To generate the XML binding classes from the XML-Schema we use the Apache Maven 2 plugin from the Codehaus mojos. You may configure it like this:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxb2-maven-plugin</artifactId>
    <version>1.2</version>
    <executions>
        <execution>
        	<id>bootstrap</id>
        	<phase>generate-sources</phase>
            <configuration>
            	<schemaFiles>bootstrap_1_2.xsd</schemaFiles>
                <packageName>...</packageName>
            </configuration>
            <goals>
                <goal>xjc</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
    	<verbose>true</verbose>
        <outputDirectory>${project.build.directory}/generated-sources/java</outputDirectory>
        <clearOutputDir>false</clearOutputDir>
    </configuration>
</plugin>

The JAX-B bindings will produce nice annotated java beans which you can use in the further work. Another nice side effect of using JAX-B is, that it’s blazing fast compared to use DOM or XPath processing of your XML files. Another nice effect of having an XML-Schema.

So, after defining the XML-Schema and generating the JAX-B binding the next thing to do is to unmarshal the data from the XML file (or InputStream) which is not more than 20 lines of standard java code. Then you have an object graph representing the XML and the only thing left is to create the objects you (or the Magnolia CMS) need from this object graph. This should be an accomplishable task for a serious developer

I choose to create a generic mapper interface like

interface TaskHandler {
	info.magnolia.module.delta.Task create(T xmlTask);
}

and use a java.util.Map to determine the right TaskHandler instance for a XML task bean instance and voila I had all the info.magnolia.module.delta.Task instances which where defined in XML. Some glue code which does some sorting and other stuff completed my ModuleVersionHandler. A TaskHandler implementation could look like this:

dictionary.put(Load.class, new TaskHandler(Load.class) {
    @Override
    public Task create(Load xmlTask) {
        String name = name(xmlTask, String.format("Load file '%s'.", xmlTask.getFile()));
        String description = description(xmlTask, String.format("Load file '%s' for XML import.", xmlTask.getFile()));
        String resource = String.format("/mgnl-bootstrap/%1$s/%2$s", moduleName, xmlTask.getFile());
        return new BootstrapSingleResource(name, description, resource,
                javax.jcr.ImportUUIDBehavior.IMPORT_UUID_COLLISION_REPLACE_EXISTING);
    }
});

I used an anonymous inner class an add the instance directly to the dictionary mapping all JAX-B types to the TaskHandler. The task handler itself uses the getter from the XML bean to create a new instance of the BootstrapSingleResource task. You will mention that the name of the element (<load />) is more readable. One of the benefits using a specialized domain specific XML file.

I promised to give some more advantages of having an XML-Schema. Another Advantage is that you may validate the XML (quite boring) and when you deploy the XML to a public location (e.g. a web server) you will get auto completion in Eclipse. Which is very nice!

So my resume: Sometimes it’s more than only nice to have a solution specific to the problem domain. With very little effort you are able to create this solution using XML-Schema and JAX-B technology stack. The result in this case was a well documented XML format which can handle various content migration scenarios. With some further levels of indirections (which were very simple) I was able to introduce programming language constructs like conditions (e.g. the <if-exists repository="WEBSITE" node="/en" /> element). I guess it’s okay to call it a language now, isn’t it?

There are many situation where standard soultions like the Springframework (or the SOAP message XML format) are the best choice to quickly assemble an object graph, but when the XML (or the content in general) is object to changes made by humans it’s always worth to consider a more human readable variant.