The Horror of Java

Many developers, with good reason, are terrified of the Java ecosystem. If you were unlucky, you've have been plopped in the middle of a large Java EE service with thousands of lines of inflexible XML and tens of thousands of lines of generated Java that no human will ever read (former defense contractor here - I've written five thousand line WSDLs by hand and worked on projects that generate thousands of lines of SOAP responses with String concatenation). If you're one of the lucky ones, you worked on a 'modern and lightweight' project with Spring and Hibernate instead, which only entails plumbing the depths of abstraction with joys such as the AbstractSingletonProxyFactoryBean.

Compared to the ease of working with web.py or Sinatra, you'd be forgiven for writing off the entire Java world for good. I came pretty close - after my time defense contracting, I basically refused to write anything but Lisp and Javascript (which is basically just a Lisp with infix syntax ;-)) for the better part of a year because of the post traumatic flashbacks.

The Appeal of Java

Whether it was the need to work on search with Lucene, big data with Hadoop, or other JVM languages like Scala or Clojure - I kept getting pulled back into the Java world. Fortunately, in the last few years great libraries and frameworks have emerged that make Java more usable. Some of the ones I've found most useful include the JSON library Jackson, the RESTful web framework Jersey, and the miscellaneous utility functions in Google's Guava library.

Intended Audience

The rest of this post assumes that you already know Java (or will be learning it from a different source). There are a number of excellent books for learning the nooks and crannies of the Java language, in particular I can't endorse Bloch's Effective Java or Goetz et al's Java Concurrency in Practice enough.

Jersey

Jersey is my preferred framework for writing RESTful services. It's closer to Sinatra or web.py - but if you want something like Rails or Django you should look at Play.

It takes a little bit of glue to setup (read on - I explain it all in later sections!) - but once you do, it's easy to define a new resource that can handle many different 'verbs.' Here's an example that defines a 'Student' resource where you can add, list, and delete students:

And it's really that easy. You just annotate methods/classes with 'routing' information, and your done. We can now list, create, and delete student records from a RESTful HTTP web service. Take a look:

You can see the whole thing on github - and the rest of this article will explain how to setup some of the magic that makes this possible.

Jackson

I don't think I need to sell anyone on the advantages of JSON as a data interchange format: it's easy to work with, human readable, and flexible. Jackson is by far the best Java JSON library I've come across. The one problem is that it's a little difficult to figure out how to do non-trivial things straight from the Javadocs. The author of Jackson is the amazing Tatu Saloranta - and his personal blog is full of great tips on how to use Jackson in the real world. But, of course, sometimes it's hard to find the example you need on the blog - so I'm going to show some you some common usages.

If you use 'normal' looking plain old Java objects (POJOs) with a no-argument constructor and getters and setters for each instance variable, Jackson will work out of the box for you with no trouble or special annotations (see).

However, one of the best habits I ever got into was making objects immutable unless there is a good reason not to. The problem with that is by default, under the covers, Jackson instantiates objects using the no-argument constructor and then uses the setters to set the instance variables properly. That won't work for immutable objects - so we can use the @JsonCreator annotation to tell Jackson how to instantiate objects. Take a look at an example:

Now we're getting somewhere - this is more like code I might use in production. Next, let's say that we're using this JSON to communicate with other services, and a requirement comes down that courses be represented by a string of the department's shortname and course number, instead of the object that includes the vanity name, etc. That is, instead of the courses looking like:

we want them to look like:

This is where things start to get a little tricky, and Jackson's flexibility really shines. We can define completely custom classes that are responsible for serializing and deserializing the Course object like this:

There is a lot more to Jackson - but this should be more than enough to get started. Check out the actual documentation for ideas.

Guava

Guava is an enormous, and extremely powerful, library of utility functions. There is a lot of overlap with Apache Commons - but I generally find the Guava versions faster and easier. I've put together some quick examples of the pieces I use most often:

If you want to learn more about Guava check out the full docs. At least take a look at the Files utility functions and MoreExecutors static factories.

Maven

Maven is an all in one build and dependency managment system. It also has one of my favorite features, called 'archetypes.' These allow you to create a 'template' which can be used as the basis of new projects. I put together an archetype for Java web services which you can easily reuse - check it out on Github.

The most common thing you'll need to do with Maven is add a new dependency. Just head over to MVNRepository - search for the library you want to add, and copy the dependency (which MVNRepository will list verbatim) into your project's pom.xml.

You can use Maven to run your service too - just type 'mvn tomcat:run' in your service's directory, and it will automatically start up. In production, you'll want to deploy your project's WAR file to an application server (like Tomcat) - but that's a story for another day.

Much More

There is much more we can talk about but I hope I've shown you enough to convince you that Java Web Services have come out of the dark ages. If there's interest in more about the Java world please let me know on the below form: