Book Review: REST API Design Rulebook (Mark Masse)

RESTful style architectures are becoming more and more ubiquitous. There are many reasons for this:

• Web Tiers are full of JavaScript yearning to make nice simple AJAX requests
• The obvious shortcomings of SOAP style strong contracts 
• They are a nice alternative to ESB's for integrating heterogeneous architectures

However, like the MVC design pattern or the Agile Software Methodology, while many projects may be claiming to be using the RESTful architectural approach everyone is doing it differently.

In 2010, Martin Fowler - in his excellent blog - discussed the Richardson Maturity Model. This model provided a very good categorisation technique to assess the degree of RESTfullness based on how many core REST principles were being used.  Although, that same model gets a reference in Mark Masse's REST API Design Rulebook, Masse's book goes much more into low level detail about various REST best practises.

For example:

• Negative caching: adding cache headers not just for positive responses but to 3xx and 4xx responses.  This is something that may not be obvious, but could be a good performance / scalability boost depending on the nature of your application and user usage patterns etc.
• How to version your URIs, your representational forms and your resource objects
• Using a consistent forms to represent link relations 

In addition, there is a abundance of other ideas and guidelines, some pretty simple but nonetheless important:

• Don't end URI's with a slash
• Don't use underscores in URI paths
• Put "api" in the domain part of your rest resource path, e.g. 

https://api.dropbox.com/1/oauth/request_token

The main reason why I think it is good to have a book like this is because when a development team are trying to use a REST style architecture, disagreements, misunderstanding will inevitably happen. For example, the proverbial: 'Should a URI end in a plural or singular noun?'
It is always good to be able to reference a respected industry resource to prevent rabbit holes appearing and eating into your valuable project time.

Furthermore, there are some really quick and easy things you can do to make a much a better REST API that are discussed in the book. For example:

• Adding an ETag HTTP header to that shopping cart resource as items go in and out of it.
• Using query fields to generate partial responses and using the ! for an excludes option.

Now for some constructive criticism.  Firstly, I don't there will ever be complete consistency in REST approaches. Some of the so called best practises could be argued to be just subjective or nice-to-haves. They are not something that are going to make a big difference to either functional or non-functional aspects of your architecture. Some of the industry leaders not only take different approaches in their REST APIs, but they are also sometimes doing the opposite of what Massé suggests. For example, Massé suggests not to include a file extension type in your REST URLs (see Chapter 2), but  (at the time of writing) Twitter do just that (the URI is: https://api.twitter.com/1.1/statuses/mentions_timeline.json)

Furthermore, in a lot of projects you will be writing a REST API purely to serve JSON back to a Web client.   This is quite different to a public facing API on the scale of Twitter, Amazon etc.   Therefore you need to ask yourself if you really need to put the time investment in so that you are adhering to every single REST best practise instead of just doing what makes sense for your project.  Some obviously make sense, some could be argued to be overkill. For example making sure you are sending back the correct HTTP code when you know the client never even checks if it is a 403 or 405.

I do think this book is written more as if you were designing a public facing API.  If you find yourself in that situation you should definitely, definitely, definitely be considering everything Massé is saying in the book.  But note, the emphasis is on considering which doesn't always mean adhering or adopting.

The book does a very good job in covering best practises that a lot of developers just wouldn't think of (setting response headers such as content-length, setting the location header in responses for newly created resources, how to support HTTP 1.0 when you are trying to discourage caching) and is definitely worth a read but you really have to think about what makes sense for your project. As stated, some of the suggestions are quick wins others you have to assess the cost and the benefit. Following the core basic REST principles (statelessness, a good resource model, uniform interface etc.) is what is really important after that the challenge is figuring out what works best for each specific project and how to make the most of your time. That will vary from project to project and will depend on project scope, scale etc.   A good architectural decision should always consider the various options but make the appropriate decision for the appropriate project.

Until the next time, take care of yourselves.

MongoDB and Grails

So recently, I had a requirement to store unstructured JSON data that was coming back from a web service. The web service was returning back various soccer teams from around the world. Amongst the data contained in most of the soccer teams was a list of soccer players, who were part of the team. Some of the teams had 12 players, some had 20 some had even more than 20. The players had their own attribute, some were easy to predict some impossible. For the entire data structure, the only attribute that I knew would definitely be coming back was team's teamname. After that, it depended on each team.

{
   "teams": [{
       "teamname":"Kung fu pirates",
       "founded":1962,
       "players": [
          {"name": "Robbie Fowler", "age": 56},
          {"name": "Larry David", "age": 55}
          ...
        ]},
        { 
        "teamname":"Climate change observers",
        "founded":1942,
        "players": [
          {"name": "Jim Carrey", "age": 26},
          {"name": "Carl Craig", "age": 35}
          ...
        ]},
        ...
   ]

}

There are several different ways to do store this data. I decided to go for MongoDB. Main reasons:

• I wanted to store the data in as close as possible format to the JSON responses I was getting back from the web service. This would mean, less code, less bugs, less hassle.
• I wanted something that had a low learning curve, had good documentation and good industry support (stackoverflow threads, blog posts etc)
• Something that had a grails plugin that was documented, had footfall and looked like it was maintained
• Features such as text stemming were nice to have's. Some support would have been nice, but it didn't need to be cutting age.
• Would support good JSON search facilities, indexing, etc

MongoDB ticked all the boxes. So this is how I got it all working. After I installed MongoDB as per Mongo's instructions and the MongoDB Grails plugin, it was time to write some code. Now here's the neat part, there was hardly any code. I created a domain object for the Team.

class Team implements Serializable {

    static mapWith = "mongo"

    static constraints = {
    }

    static mapping = {
        teamname index: true
    }

    String teamname

    List players
    static embedded = ['players']
}

Regarding the Team domain object:

• The first point to make about the Team domain object was that I didn't even need to create it. The reason why I did use this approach was so that I could use GORM style api's such as Team.find() if I wanted to.
• Players are just a List of object. I didn't bother creating a Player object. I like the idea of always ensuring the players for the team were always in a List data structure, but I didn't see the need to type anything further.
• The players are marked as embedded. This means the team and players are stored in a single denormalised data structure. This allows - amongst other things - the ability to retrieve and manipulate the team data in a single database operation.
• I marked the teamname as a index.
• I marked the domain object as

  static mapWith = "mongo"

  This means that if I was also using another persistence solution with my GORM (postgres, MySQL, etc.) I am telling the GORM that this Team domain class is only for Mongo - keep your relational hands off it. See here for info. Note: This is a good reminder that the GORM is a higher level of abstraction than hibernate. It is possible to have a GORM object that doesn't use hibernate but instead goes to a NoSQL store and doesn't go near hibernate.

You'll note that in the JSON that there are team attributes such as founded that haven't been explicitly declared in the Team class. This is where Groovy and NoSQL play really well with each other. We can use some of the Meta programming features of Groovy to dynamically add attributes to the Team domain object.

private List importTeams(int page) {
    def rs = restClient.get("teams") // invoke web service
    List teams = rs.responseData.teams.collect {
         teamResponse ->
                Team team = new Team(teamname: teamResponse.teamname)
                team.save(); // Save is needed to dynamically add the attribute
                teamname.each {key, value ->
                    team["$key"] = value 
                }
                teamname.save(); // We need the second save to ensure the variants get saved.
                return teamname
        }
    log.info("importTeams(),teams=teams);
    teams
}

Ok, so the main points in our importTeams() method

• After getting our JSON response we run a collect function on the teams array. This will create the Team domain objects.
• We use some meta programming to dynamically add any attribute that comes back in the JSON team structure to the Team object. Note: we have to invoke save() first to be able to dynamically add the attributes that are declared in the Team domain object to the Team domain object. We also have to invoke save() again to ensure that attributes that are declared in the Team domain object to ensure they are saved. This may change in future versions of the MongoDB plugin, but it is what I had to do to get it working (I was using MongoDB plugin version 3.0.1)

So what's next? Write some queries. Ok so two choices here. First, you can use the dynamic finders and criteria queries with the GORM thanks to the MongoDB plugin. But, I didn't do this. Why? I wanted to write the queries as close as possible to how they are supposed to be written in Mongo. There were a number of reasons for this:

• A leaky abstraction is inevitable here. Sooner or later you are going to have to write a query that the GORM won't do very well. Better to approach this heads on.
• I wanted to able to run the queries in the Mongo console first, check explain plans if I needed to and then use the same query in my code. Easier to do this, if I write the query directly without having to worry about what the GORM is going to do.

The general format of queries is:

teams = Team.collection.find(queryMap) // where queryMap is a map of fields and the various values you are searching for. 

Ok, some examples of queries...

Team.collection.find(["teamname":"hicks"]) // Find a team name hicks
Team.collection.find(["teamname":"hicks", "players.name": "Robbie Fowler"] // As above but also has Robbie Fowler
Team.collection.find(["players.name": "Robbie Fowler"] // Any teams that has a Robbie Fowler
Team.collection.find(["teamname":"hicks", "players.name": "Robbie Fowler", {"players.$":1}]  // Returns matching player only
Team.collection.find(["teamname":"/ick/"]) // Match on the regular expression /ick/, i.e. any team that contains text ick.

Anything else? Yeah sure. I wanted to connect to a Mongo instance on my own machine when in development but to a Mongo machine on a dedicated server in other environments (CI, stage, production). To do this, I updated my DataSource.groovy as:

environments {
    development {
        grails {
            mongo {
                host = "localhost"
                port = 27017
                username = "test"
                password = "test"
                databaseName = "mydb"
            }
        }
        dataSource {
            dbCreate = "create-drop" // one of 'create', 'create-drop', 'update', 'validate', ''
            url = "jdbc:h2:mem:devDb;MVCC=TRUE;LOCK_TIMEOUT=10000"
        }
    }

    
    ci {
        println("In bamboo environment")
        grails {
            mongo {
                host = "10.157.192.99"
                port = 27017
                username = "shop"
                password = "shop"
                databaseName = "tony"
            }
        }
        dataSource {
            dbCreate = "create-drop" // one of 'create', 'create-drop', 'update', 'validate', ''
            url = "jdbc:h2:mem:devDb;MVCC=TRUE;LOCK_TIMEOUT=10000"
        }
    }
}

You'll see I have configured multiple datasources (MongoDB and PostGres). I am not advocating using both MongoDB and a relational database, just pointing out it is possible. The other point is that the MongoDB configuration is always under:grails { mongo {

Ok this is a simple introductory post, I will try to post up something more sophisticated soon. Until the next time, take care of yourselves.

JavaScript Performance tip using a Closure

Here is a simple performance JavaScript tip using a JavaScript closure that is so quick to explain you have no reason not to keep reading.   Consider this: you want a function which will tell you the position on a rugby team for a certain number. Those of us who are familiar with the sport will know that in rugby, the various positions always have the same number.

1. Loose head
2. Hooker
3. Tight head
4. Lock
5. Lock
6. Flanker (blind side)
7. Flanker (open side)
8. No. 8
9. Scrum half
10. Out half
11. Left wing
12. Inside Centre
13. Centre
14. Right wing
15. Full back

So for your first attempt you define a positions array in the global namespace and then a function to resolve the position for a given number.

var positions = ['No position', 'Loose head', 'Hooker', 'Tight head', 'Lock', 'Lock', 'Flanker', 'Flanker', 'No. 8',  'Scrum half', 'Out half', 'Left wing', 'Inside centre', 'Outside centre', 'Full back']

var getPosition = function(n) {
   return positions(n);
}

Everyone starts laughing at you at code review time. You get comments such as:
"Don't pollute the name space, re-write please."
"Did you even bother using JsLint?"
"Do you want fries with that?"

For your second attempt, you put the positions array into a function as a local variable.

var getPosition = function() {
    var positions = ['No position', 'Loose head', 'Hooker', 'Tight head', 'Lock', 'Lock', 'Flanker', 'No. 8', 'Flanker', 'Scrum half', 'Out half', 'Left wing', 'Inside centre', 'Outside centre', 'Right wing' 'Full back'];   // positions is a local variable
   return positions[n];
}

Back at the second code review:
"Well it's better, but you do realise that every time that function is called, the array is allocated?"
"But you said, don't pollute the global name space"
"Look we have standards here, don't pollute global name space and don't incur performance costs when you don't need do"
"Ok"

You leave the code review despondent and crestfallen. Back at your coffee stained desk, when your headphones are on low volume, you keep hearing the word closure, closure, closure from a few of the JavaScript nerds sitting near you.  That evening, you are having difficult getting to sleep.  Closure, closure, closure.  The word won't leave your head.  Closure, closure, closure.   Yeah you know that closures offer a way to encapsulate code in JavaScript, but this isn't about encapsulation. Wait a sec! Closures close over free variables and make them accessible to the lexical scope. Hmmm... This means you could do something like...

var getPosition = function () {
    var positions = ['No position', 'Loose head', 'Hooker', 'Tight head', 'Lock', 'Lock', 'Flanker', 'Flanker', 'No. 8', 'Scrum half', 'Out half', 'Left wing', 'Inside centre', 'Outside centre', 'Right wing', 'Full back'];   // positions is a local variable
    return function(n) {
        return positions[n];
    }
}()

console.log(getPosition(4));

What's going on here?

• The inner function "closes over" the positions array
• The outer function returns the inner function, which is then assigned it to the variable getPosition
• The outer function is self invoking. This means the declaration, invocation and assignment will happen all at the same time.
• Because it is the outer function which allocated the array and because the outer function is only invoked once, the array is only allocated once.
• Because the inner function has access to what it "closes over" even after the outer function has executed, it means the inner function will have access to the positionsarray (that is only allocated once).

So you return to code review a little more sanguine. You get one comment:
"Third time lucky"

You might be thinking, it doesn't take that long to allocate an array in JavaScript is this not overkill? Well, it depends. Is your application needing to squeeze every nano second? Is the amount of data you need to initialise a lot more than 15 elements in an array? These are pertinent questions of course. But the technique is a handy one to know because encapsulation is clearly not the only advantage of closures.

Grails tip: refactoring your URLs

On the current project I am working we use a lot of integration tests. For you non-Grails users out there, Integration tests test your Controller APIs, your Services and any persistence that might happen all very neatly. The only slice of the cake they don't test from a back end perspective are your Grails filters for which you'd need something like a functional test. In the Grails world, Controller API's are mapped to URL requests in the URLMappings.groovy file. This is just a simple Groovy to configure which HTTP request go to which Controller.

For example:

class UrlMappings {
    static mappings = {
        "/sports/rugby/ball" (controller: "rugbyBall", action = [POST: "createBall", DELETE: "removeBall", GET: "getBall"])
        ...

So in the above example, the HTTP request /sports/rugby/ball will go to the RugbyBallController and will go to the methods: createBall(), deleteBall(), getBall() depending on weather the request is a GET, POST or DELETE. Now suppose, you have your project all set up to server up the CRUD operations for the rugby ball and after a few hectic sprints some software entropy creeps and you need to refactor your Controller APIs but before you race ahead and do that your project manager looks you in the eye and says:

"You must support all existing APIs as clients are using them".

This is how generally refactoring works in the real world when things go into production. There is always a phase of supporting of old and new, deprecating the old and then when everyone is happy removing it. Anyway, you begin by updating your URLMappings.groovy

class UrlMappings {
    static mappings = {
        // Old APIs
        "/sports/rugby/ball" ( controller: "rugbyBall", action = [POST: "oldCreateBall", DELETE: "oldRemoveBall", GET: "oldGetBall"])
        ...

        // New APIs
        "/sports/rugby/v2/ball" ( controller: "rugbyBall", action = [POST: "createBall", DELETE: "removeBall", GET: "getBall"])
        ...

The URLMappings.groovy show the old and the new. The old APIs are going to controller methods that you have renamed. Clients using these APIs are not impacted because they only send HTTP requests, they do not which Controller are behind these endpoints. The old APIs already have really good integration tests and our project manager has mandated that the new APIs must have similar quality integration tests before they go anywhere near pre-production.

def "test adding a single item to your cart"() {
    setup: "Set up the Cart and Landing Controller"
       //...
    when:
       //...
       rugbyBallController.oldGetBall();
       rugbyBall = JSON.parse(rugbyBallController.response.contentAsString)
    then:
       rugbyBall.isOval();

Mr. Project manager says: "I want this all new tests added by Friday or you are not going for a pint after work. You need a quit way to get your integration tests done". Thinking about that cool larger and its quenching effect on the back your throat, you remember Groovy's excellent support for invoking methods dynamically where you can specify the name of the method as a variable.

   myObject."$myMethod"()  // myMethod is a Groovy String variable.

In the above code snippet, myMethod is a variable that corresponds to the name of method you want to invoke on myObject. "$myMethod" means, evaluate the variable myMethod (which of course will be the method name), the () of course just means invokes the method. Eureka moments happens when you remember that the old and new APIs will return the exact same JSON. All you need to do is run the same test twice, once for the old code and once for the new. Since you are using the spock framework for your integration tests that's easily achieved using a where block.

def "test adding a single item to your cart"(String method) {
    setup: "Set up the Cart and Landing Controller"
       //...
    when:
       //...
       rugbyBallController."$method"();
       rugbyBall = JSON.parse(rugbyBallController.response.contentAsString)
    then:
       rugbyBall.isOval();
    where:
       method = ["oldGetBall", "getBall"]

Happy days. Now go off and drink that lager.

The magic of Groovy's with...

In a recent post, this blog examined the meaning of Closures' delegates and how they could be changed. This post will show how the ability to set the closure's delegate allows the language to become quite expressive where other languages remain cumbersome and verbose. For the purpose of example (and some fun) consider there is a groovy object drico, which represents the legendary Irish rugby player, Brian O'Driscoll

In case you don't know, Brian O'Driscoll is the best Rugby player to ever come from Ireland.  He could tackle, break, off load, ruck, jackal, kick you name it. An exceptional skilful athlete and widely regarded as one of the greatest players the game has ever seen.  In case, you don't know what Rugby is think American Football with no helmets, timeouts and a slightly longer shaped oval ball.   It is basically superior in every regard.   Anyway, so we have the drico object in our Groovy code suppose and we want to invoke a bunch of methods on it.  We could find ourselves doing:

RugbyPlayer drico = new RugbyPlayer();
...
drico.youWereAmazing();
drico.seriouslyYouWereAmazing();
drico.sayTotsAmazeBalls();
drico.howManyTriesDidYouScore();
drico.youreTheBest();
...

Wow, that's a lot methods being invoked on Drico.  There must be some Groovy trick we could do to lessen the text here? Remember, it is generally better to be coding than typing

Well we could put all the methods we want to invoke on Drico into a Closure and then set that Closure's delegate to Drico.

RugbyPlayer drico = new RugbyPlayer();
...
def dricoClosure = {
    youWereAmazing();
    seriouslyYouWereAmazing();
    sayTotsAmazeBalls();
    howManyTriesDidYouScore();
    youreTheBest();
    ...
}

dricoClosure.delegate = drico
dricoClosure();

Not bad. We have removed all the drico., and just gone straight to the method invocations but we have also added some code setting up the closure delegate. So one step forward, one step back. We can get rid of the one step back by using Groovy's with method. The with method is applicable to any Groovy object and accepts one closure. The delegate of the closure is the object with is being invoked on. This means we can do this:

RugbyPlayer drico = new RugbyPlayer();
drico.with {
    youWereAmazing();
    seriouslyYouWereAmazing();
    sayTotsAmazeBalls();
    howManyTriesDidYouScore();
    youreTheBest();
    ...
}

Using this approach means we have still removed all the drico. and gone straight to the method invocations. It also means we don't need to set the closure's delegate and we don't need to explicitly invoke the closure. The result is we have code with a much better signal to noise ratio and which is far more expressive. Until the next time take care of yourselves.

Groovy Closures: this, owner, delegate let's make a DSL.

Groovy closures are super cool. To fully understand them, I think it's really important to understand the meaning of this, owner and delegate. In general:

• this: refers to the instance of the class that the closure was defined in.
• owner: is the same as this, unless the closure was defined inside another closure in which case the owner refers to the outer closure.
• delegate: is the same as owner. But, it is the only one that can be programmatically changed, and it is the one that makes Groovy closures really powerful.

Confused? Let's look at some code.

class MyClass {
  def outerClosure = {
    println this.class.name    // outputs MyClass
    println owner.class.name    // outputs MyClass
    println delegate.class.name  //outputs MyClass
    def nestedClosure = {
      println this.class.name    // outputs MyClass
      println owner.class.name    // outputs MyClass$_closure1
      println delegate.class.name  // outputs MyClass$_closure1
    }
    nestedClosure()
  }
}

def closure = new MyClass().closure
closure()

With respect to above code:

• The this value always refers to the instance of the enclosing class.
• owner is always the same as this, except for nested closures.
• delegate is the same as owner by default. It can be changed and we will see that in a sec.

So what is the point of this, owner, delegate? Well remember, that closures are not just anonymous functions. If they were we could just call them Lambdas and we wouldn't have to come up with another word, would we?

Where closures go beyond lambdas is that they bind or "close over" variables that are not explicitly defined in the closure's scope. Again, let's take a look at some code.

class MyClass {
  String myString = "myString1"
  def outerClosure = {
    println myString;     // outputs myString1
    def nestedClosure = {
       println myString;  // outputs myString1
    }
    nestedClosure()
  }
}

MyClass myClass = new MyClass()
def closure = new MyClass().outerClosure
closure()

println myClass.myString 

Ok, so both the closure and the nestedClosure have access to variables on the instance of the class they were defined in. That's obvious. But, how exactly do they resolve the myString reference? Well it's like this. If the variable was not defined explicitly in the closure, the this scope is then checked, then the owner scope and then the delegate scope. In this example, myString is not defined in either of the closures, so groovy checks their this references and sees the myString is defined there and uses that. Ok, let's take a look at an example where it can't find a variable in the closure and can't find it on the closure's this scope, but it can find's it in the closure's owner scope.

class MyClass {
  def outerClosure = {
    def myString = "outerClosure";     
    def nestedClosure = {
       println myString;  // outputs outerClosure
    }
    nestedClosure()
  }
}

MyClass myClass = new MyClass()
def closure = new MyClass().closure
closure()

In this case, Groovy can't find myString in the nestedClosure or in the this scope. It then checks the owner scope, which for the nestedClosure is the outerClosure. It finds myString there and uses that. Now, let's take a look at an example where Groovy can't find a variable in the closure, or on this or the owner scope but can find it in on closure's delegate scope. As discussed earlier the owner delegate scope is the same as the owner scope, unless it is explicitly changed. So, to make this a bit more interesting, let's change the delegate.

class MyOtherClass {
  String myString = "I am over in here in myOtherClass"
}

class MyClass {
  def closure = {
    println myString
  }
}


MyClass myClass = new MyClass()
def closure = new MyClass().closure
closure.delegate = new MyOtherClass()
closure()   // outputs: "I am over in here in myOtherClass"

The ability to have so much control over the lexical scope of closures in Groovy gives enormous power. Even when the delegate is set it can be change to something else, this means we can make the behavior of the closure super dynamic.

class MyOtherClass {
  String myString = "I am over in here in myOtherClass"
}

class MyOtherClass2 {
  String myString = "I am over in here in myOtherClass2"
}

class MyClass {
  def closure = {
    println myString
  }
}


MyClass myClass = new MyClass()
def closure = new MyClass().closure
closure.delegate = new MyOtherClass()  
closure()     // outputs: I am over in here in myOtherClass

closure = new MyClass().closure
closure.delegate = new MyOtherClass2() 
closure()     // outputs: I am over in here in myOtherClass2

Ok, so it should be a bit clearer now what this, owner and delegate actually correspond to. As stated, the closure itself will be checked first, followed by the closure's this scope, than the closure's owner, then its delegate. However, Groovy is so flexible this strategy can be changed. Every closure has a property called resolvedStrategy. This can be set to:

• Closure.OWNER_FIRST
• Closure.DELEGATE_FIRST
• Closure.OWNER_ONLY
• Closure.DELEGATE_ONLY

So where is a good example of a practical usage of the dynamic setting of the delegate property. Well you see in the GORM for Grails. Suppose we have the following domain class:

class Author {
   String name 

   static constraints = {
       name size: 10..15
   }
}

In the Author class we can see a constraint defined using what looks like a DSL whereas in the Java / Hibernate world we would not being able to write an expressive DSL and instead use an annotation (which is better than XML but still not as neat as a DSL). So, how come we can use a DSL in Groovy then? Well it is because of the capabilities delegate setting on closures adds to Groovy's metaprogramming toolbox. In the Author GORM object, constraints is a closure, that invokes a name method with one parameter of name size which has the value of the range between 10 and 15. It could also be written less DSL'y as:

class Author {
   String name 

   static constraints = {
       name(size: 10..15)
   }
}

Either way, behind the scenes, Grails looks for a constraints closure and assigns its delegate to a special object that synthesizes the constraints logic. In pseudo code, it would be something like this...

// Set the constraints delegate

constraints.delegate = new ConstraintsBuilder();  // delegate is assigned before the closure is executed.

class ConstraintsBuilder = {
  //
  // ...
  // In every Groovy object methodMissing() is invoked when a method that does not exist on the object is invoked
  // In this case, there is no name() method so methodMissing will be invoked. 
  // ...
  def methodMissing(String methodName, args) {
     
     // We can get the name variable here from the method name
     // We can get that size is 10..15 from the args
     ...
     // Go and do stuff with hibernate to enforce constraints
  }
}

So there you have it. Closures are very powerful, they can delegate out to objects that can be set dynamically at runtime. That plays an important part in Groovy's meta programming capabilities which mean that Groovy can have some very expressive DSLs.

Good use of Closures - Execute around pattern

Not long ago, in a blog post, I explained what Closure were in Groovy.  This blog post will explain one good example of using them.  I recently found myself having to write the same exception handling logic for a bunch of back-end Controller APIs which were serving AJAX requests.  It was like this

class ApiRugbyPlayerController {
    JSON getPlayerStats() {
        try {
            ...
            // invoke business service method to get player stats
        } catch (ServiceException serviceException) {
            // don't care too much about this. 
            // log and move on
            ...           
        } catch (SessionException sessionException) {
            // clear out session cookies
            ...
            // send 403 to client 
            ...
        } catch (Exception ex) {
            throw new ApiException(ex)
        }
    }

    JSON updatePlayerStats() {
        try {
            ...
            // invoke business service method to update player stats
        } catch (ServiceException serviceException) {
            // don't care too much about this. 
            // log and move on
            ...           
        } catch (SessionException sessionException) {
            // clear out session cookies
            ...
            // send 403 to client 
            ...
        } catch (Exception ex) {
            throw new ApiException(ex)
        }
    }

    JSON queryPlayerStats(){
        try {
            ...
            // invoke business service method to query player stats
        } catch (ServiceException serviceException) {
            // don't care too much about this. 
            // log and move on
            ...           
        } catch (SessionException sessionException) {
            // clear out session cookies
            ...
            // send 403 to client 
            ...
        } catch (Exception ex) {
            throw new ApiException(ex)
        }
    }
}

As can be seen, there is some code duplication going on here. In the spirit of DRY (don't repeat yourself), it is better to only define this exception handling logic once and then re-use it. So I defined the following utility method, which implements the exception handling pattern and takes a closure which is executes the exception handling for.

    private JSON withExceptionHandling(Closure c) {
        try {
            ...
            c.call();
        } catch (ServiceException serviceException) {
            // don't care too much about this. 
            // log and move on
            ...           
        } catch (SessionException sessionException) {
            // clear out session cookies
            ...
            // send 403 to client 
            ...
        } catch (Exception ex) {
            throw new ApiException(ex)
        }
    }

We can make a code block a closure in Groovy by surrounding it with {}. This means I can make the logic inside my Controller methods into Closures and pass them to my utility method. And when I pass it to my utility method I don't even need to pass it inside a () as Groovy doesn't make you. So that means, I can take out all the common exception handling, remove the code bloat and my Controller API's are much cleaner.

class ApiRugbyPlayerController {
    JSON getPlayerStats() {
        withExceptionHandling {
            ...
            // invoke business service method to get player stats
        } 
    }

    JSON updatePlayerStats() {
        withExceptionHandling {
            ...
            // invoke business service method to update player stats
        } 
    }

    JSON queryPlayerStats(){
        withExceptionHandling {
            ...
            // invoke business service method to query player stats
        } 
    }

    private JSON withExceptionHandling(Closure c) {
        try {
            ...
            c.call();
        } catch (ServiceException serviceException) {
            // don't care too much about this. 
            // log and move on
            ...           
        } catch (SessionException sessionException) {
            // clear out session cookies
            ...
            // send 403 to client 
            ...
        } catch (Exception ex) {
            throw new ApiException(ex)
        }
    }
}

So there we go. We have adhered to DRY principles, avoided code bloat and have a dedicated place for our exception handling confident that it being implemented consistently. This example of Groovy closure is a little but like a second order invocation in JavaScript. If we wanted to do something like in Java, it would just involve a lot more code. We could use something like the template method pattern. You would have more decoupling, but you have a lot more code. Or you could make all your AJAX APIs enter a common method (like a Front Controller) and put your common exception handling there. Again, possible but just more code. Until the next time, take care of yourselves.

Closures in Groovy.

The simpliest explanation of a closure in Groovy is that it is anonymous function.

def closure = { println "I am a closure" }
closure() // Prints I am a closure

Ok, so first point here is that I am a closure is not printed when the closure is defined but only when it is invoked. Closures facilitate delayed execution. It is also possible to pass parameters to a closure

def closureWithParameters = {x, y -> print(x  + " and " + y)}
closureWithParameters("Hello dudes", "Hello Mega Dude")  // Prints Hello dudes and Hello Mega Dude

When the closure has only one parameter, we don't even need the -> we can just use the implicit it variable.

def closureWithParameters = { println it }
closureWithParameter("Hello dude")  // Prints Hello dude

Now, now, now kiddies. Closures don't just exist in Groovy, they exist in many languages and one of their features that people sometimes forget about is that they contain a representation of the function's lexical environment. In English, this means they get a snapshot of the context in which they are defined and only they they can access this snapshot and change it. In JavaScript, we can do something like this:

function outerFuntion () {
    var counter = 1;
    function innerFunction() {
        alert("Counter=" + counter++);
    }   
    return innerFunction;
}

Even though counter is defined in outerFunction() as a local variable, it is considered to be in innerFunction()'s lexical environment hence it can access it. When innerFunction() is returned as a closure it will get its own value of it that only it can access. So if we were to do this:

var myClosure = outerFuntion();  // myFunc is now a pointer to the innerFunction closure.
myClosure();  // Executes Counter=1;

First, outerFunction() is executed and it returns the innerFunction closure. The variable is assigned to this closure. Now, now, now, note the key word here is "returned". innerFunction() is returned, it is not executed. So again we see the delay of execution characteristic of closures. Everytime we then execute the closure, the counter is increased.

myClosure();  // Executes Counter=2;
myClosure();  // Executes Counter=3;
myClosure();  // Executes Counter=4;
myClosure();  // Executes Counter=5;
myClosure();  // Executes Counter=6;

So the closure has state, that it remembers across invocations. That state begins as the snapshot of the context in which the function is defined and it is something that only they closure can change. So yeah that's the key point of closures. They are a special kind of object that combines two things: a function, and the environment in which that function was created. The environment consists of variables that were in-scope at the time that the closure was created. Ok, so back onto Groovy. The same example would look like:

def outerFunction () {
    def counter = 1;
    return {
        print "Counter=" + counter++
    }
}

def myClosure = outerFunction()

myClosure();  // executes 1 
myClosure();  // executes 2
myClosure();  // executes 3 
myClosure();  // executes 4
myClosure();  // executes 5 
myClosure();  // executes 6

It's very similar to the JavaScript example. The word def is used instead of function. We just also make use of the fact you don't have to use the word function in Groovy when you want define an anonymous function. If we wanted to make the inner function anonymous in the JavaScript version we could do:

function outerFuntion () {
    var counter = 1; 
    return function () {
        alert("Counter=" + counter++);
    };
}

var myClosure = outerFuntion();  // myFunc is now a pointer to the innerFunction closure.
myClosure();  // Executes Counter=1;
myClosure();  // Executes Counter=2;

But still have to use the word function, we just don't have to give it a name. Ok, so until the next time take care of yourselves.