Thursday, March 6, 2014

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.

Saturday, January 11, 2014

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.

Monday, December 30, 2013

Groovy's Smooth Operators

Take a trip back to 1984.  Apple release the Macintosh, 'The Final Battle' is about to commence in V and Scotland win the Five Nations completing a grand slam in the process.  Right in the middle of miners' strike in the UK, English pop group Sade release the catchy number: Smooth Operator.  It was chart success in the UK and in the US (not to mention the German, Dutch and Austrian charts). Little did Sade know that decades later the Groovy programming language would feature several smooth operators that go above and beyond the standard set of Java operators.  Now, we'll leave the 1980's comparisons there and shall discuss a few of the smooth operators in Groovy in this blog post.

Elvis 


The Elvis Operator (so named after a certain person's hairstyle) is a shortened version of the ternary operator.  It is very handy for null checking. And remember even though it can be argued null handling is bad coding practise because it is better to not have nulls in your code, lots of APIs in a code base will inevitably return nulls and in the real world where you want to add some robustness and defensive coding to keep things smooth in production, this kind of thing can be useful.

Now here is how it works.  If the expression to the left of the Elvis operator evaluates to false (remember in Groovy there are several things such as null, such as an empty String which can be coerced to mean false), the result of the expression will be the whatever is on the right.
String country = country.name ?: "Unknown country"
So, in the above example if country.name is null or just "" since both are false in Groovy, country will be assigned as "Unknown country".   If country.name was not false, country would just be assigned that value.

Null-Safe Dereference (also called the Safe Navigation operator) 

This is especially useful to avoid null pointer exceptions in a chained expression. For example,
String location = map.getLocation().getXandYCoordinates();
might yield a null pointer exception. But using the safe navigation operator if either map, or the result of map.getLocation() are null
String location = map?.getLocation()?.getXandYCoordinates(); 
location will just be set as null. So, no null pointer exception is thrown.

Spread 

The Spread operator is useful when executing a method on elements of a collection and collecting the result. In this example, I parse a bunch of Strings into arrays and then run a closure on each of the arrays to get all the first elements.
def names = ["john magoo","peter murphy"]
def namesAsArrays = names*.split(" ")
namesAsArrays.each(){print it[0]} 
Now, remember the Spread operator can only be used on methods and on elements. It can't execute a closure for example. But what we can do is leverage Groovy's meta programming capabilities to create a method and then use the spread operator to invoke that. Suppose we had a list of numbers that we wanted to add 50 too and then multiply the answer by 6 we could do:
def numbers = [43,4]
java.lang.Integer.metaClass.remixIt = {(delegate + 50) * 6}
numbers*.remixIt()

Spaceship operator 

This originated in the Perl programming language and is so called because you guessed it, <=> looks like a spaceship!  So how does it work?  Well, it is like this.  The expression on the left and the right of the spaceship operator are both evaluated.   -1 will be returned if the operand on left is smaller, 0 if the left and right are equal and 1 if the left is larger. It's power should become more obvious with an example.

Say we have a class to represent software engineers.
class SoftwareEngineer {
    String name
    int age
    String toString() { "($name,$age)" }
}

def engineers = [
    new SoftwareEngineer(name: "Martin Fowler", age: 50),
    new SoftwareEngineer(name: "Roy Fielding", age: 48),
    new SoftwareEngineer(name: "James Gosling", age: 58)
]
Now we could easily sort by age
engineers.sort{it.age}
But what about when our list of Engineers grows and grows and we have multiple engineers of the same age? In these scenarios it would be nice to sort by age first and name second. We could achieve this by doing:
engineers.sort{a, b -> 
   a.age <=> b.age ?: a.name <=> b.name
This expression will try to sort engineers by age first. If their ages' are equal a.age <=> b.age will return 0. In Groovy and in the Elvis construct, 0 means false and hence a.name <=> b.name will then be evaluated and used to determine the sort.

Field Access 

In Groovy, when a field access is attempted, Groovy will invoke the corresponding accessor method. The Field Access operator is a mechanism to force Groovy to use field access.
class RugbyPlayer {
     String name
     String getName() {name ?: "No name"} 
}

assert "Tony" == new RugbyPlayer(name: "Tony").name
assert "No name" == new RugbyPlayer().name
assert null == new RugbyPlayer().@name

Method Reference 

The Method Reference operator allows you to treat a reference to a method like a closure.
class MyClass {
   void myMethod() { println "1" }
   void myMethod(String s) { println "2" }
}

def methodRef = new MyClass().&"myMethod"
methodRef()    // outputs 1
methodRef('x') // outputs 2
The .& creates an instance of org.codehaus.groovy.runtime.MethodClosure. This can be assigned to a variable and subsequently invoked as shown.

Happy New Year to you all and hopefully some more blogging in 2014.

Saturday, October 26, 2013

Grails: Applying build information to your builds

Occasionally, when I buy some food I check the label to see how unhealthy it is in an effort to remind myself to eat better. I probably should do this more often but that's another story.

With software, I take a more strict approach. I like to know exactly what version of what I am using and if it pertains to a build coming from a project I am working on, I like to know even more:
  • the branch it came from 
  • any code or config changes 
  • the time the build was done 
  • the person who did the build
  • the commit revision it corresponds to
The advantages of this are obvious but worth re-stating.
  • While you are in development, if you have multiple deployments and see something unusual you will immediately want to compare them. 
  • For example say you have:
    • build #349 on box 1
    • build #352 on box 2 (which includes development changes from a feature branch Y)
    You notice some strange behaviour for an error message on box 2 but don't on box 1. You can immediately check which box has what version, then check the changes and then try to rationalise the difference.
  • You can be sure your latest code check-in is deployed
  • All this build information should be in official release notes, so if you can automate it as part of your development process you have saved yourself having to automate it as part of your release
  • In enterprise architectures where you have multiple components developed from different teams integrating with each other, all components should make it easy to get this information. This helps to manage the stack and for everyone to be able to immediately check if new versions of any components have been deployed or to roll back to stable versions if problems with  any upgrades of components happen.
So away with the opinions and now with some examples. The project that I am currently working uses a Grails based architecture and Atlassian's Bamboo for builds and deploys. I wanted to get this information I described into every build - and yes that includes every development build.  I will now outline the steps.

Step 1

Write an event handler to execute when the war is being created. This should read a bunch of system properties (which you'll set in bamboo) and put them in your application.properties of your war file. Example:
eventCreateWarStart = { warName, stagingDir ->
    def buildNumber = System.getProperty( "build.number", "CUSTOM" ) 
    def buildTimeStamp= System.getProperty("build.timeStamp", "") 
    def buildUserName= System.getProperty("build.userName", "")
    def repositoryRepositoryUrl= System.getProperty("repository.repositoryUrl",  "")
    def repositoryRevisionNumber= System.getProperty("repository.revision.number", "")
    def repositoryBranch= System.getProperty("repository.branch", "")
 
    ant.propertyfile(file: "${stagingDir}/WEB-INF/classes/application.properties") {
        entry(key:"build.number", value:buildNumber) 
        entry(key:"build.timestamp", value: buildTimeStamp)
        entry(key:"build.userName", value: buildUserName)
        entry(key:"repository.revision.number", value: repositoryRevisionNumber)
        entry(key:"repository.branch", value: repositoryBranch) 
    }

}

Step 2

Update your bamboo build to set these system properties when the war is being built.  To do this, update the build war task to something like:
war -Dbuild.number=${bamboo.buildNumber} 
    -Drepository.branch=${bamboo.repository.git.branch} 
    -Dbuild.userName=${bamboo.ManualBuildTriggerReason.userName} 
    -Dbuild.timeStamp=${bamboo.buildTimeStamp} 
    -Drepository.revision.number=${bamboo.repository.revision.number}
This will mean when bamboo builds you war all the above properties will be put in your application.properties file.

Step 3

Now all you need to do is make it easy for a Grails GSP to read these properties and display them.  This means that when deployed all anyone will have to do is hit a special URL and then they'll get all the build info for the deployed WAR.


...
... Some CSS and JavaScript

Environment: ${grails.util.Environment.current.name}


Build Info:

NameValue
UserName#${g.meta([name: 'build.userName'])}
Built by #${g.meta([name: 'build.number'])}
Date#${g.meta([name: 'build.date'])}
Branch#${g.meta([name: 'repository.branch'])}
Revision number#${g.meta([name: 'repository.revision.number'])}
And in the spirit of food analogies... Here's one I made earlier and how it looks

So there you go, software taken more seriously than food. I'm off to get a Big Mac!