ShowOff is great if you are fed up with the bloated presentation applications that make a mess of your source code. Text files means that presentations can be properly version controlled. It's easy to re-arrange slides and sections. ShowOff uses SHJS to highlight code blocks. It supports many languages, but currently not Clojure. Searching around for a while revealed a Gist of SHJS styling code that I wanted to try out:

# Clojure syntax highlighting for GNU source-highlight
# rocks with SHJS
comment start ";"
include "number.lang"
vardef SPECIALCHAR = '\\.'
environment string delim "\"" "\"" begin
  specialchar = $SPECIALCHAR
end
type = "int|byte|boolean|char|long|float|double|short|void"
vardef FUNCTION = '\(([[:alpha:]]|_)[[:word:]]*(?=[[:blank:]]*)'
function = $FUNCTION
include "symbols.lang"

This is what I did on my MacOSX Snow Leopard to get ShowOff to high-light Clojure source code:

1. Install some pre-requisites. I use HomeBrew, but you can use MacPorts or whatever package manager you prefer.

gem install showoff
brew install yuicompressor
brew install source-highlight
brew install unix2dos

2. Download the shjs source distro.

3. Unzip shjs-0.6-src.zip somewhere which we will call SHJS_HOME

4. cd SHJS_HOME

5. touch source-highlight-lang/clojure.lang

6. Edit source-highlight-lang/clojure.lang and paste this Clojure source code high-lighting spec (that's the same as displayed above).

7. My Perl installation needed a recursive descent parser, so I did this:
cpan install Parse::RecDescent

8. make

9. I then copied the resulting minified JavaScript file to where my ShowOff gem keeps the language style files. I use the RVM Ruby manager, so this is where I needed it:

cp lang/sh_clojure.min.js ~/.rvm/gems/ruby-1.9.2-p290/gems/showoff-0.4.2/public/js/sh_lang/

Should you discover that you need some more tools installed, you can clean up with make maintainer-clean. After you installed whatever you were missing, run make again.

Testing Clojure high-lighting

In order to test this, we will create a simple presentation called "mypres":

showoff init mypres

This creates a new directory mypres. We go to that directory and look around:

.
├── one
│   └── 01_slide.md
└── showoff.json

OK, so we have now the skeleton of a presentation, containing a section folder named one and a set of slides in the 01_slide.md file. Looking closer at that file, we see this:

!SLIDE
# My Presentation #

!SLIDE bullets incremental
# Bullet Points #

* first point
* second point
* third point

We will now add to this file a slide definition with some Clojure source code, formatted as a code block by indenting it. Note that we have preceded the code with @@@ clojure, in order to tell ShowOff what language we want to format the block as:

!SLIDE encode-symbol
# Huffman encoding #

	@@@ clojure
	(defn encode
	  "takes as arguments a message and a tree
	 and produces the list of bits that gives
	 the encoded message"
	[[first & rest :as message] tree]
	  (when (seq message)
	    (concat (encode-symbol first tree)
	            (encode rest tree))))

We serve the presentation:

$ showoff serve

Finally we can watch the presentation by browsing to http://localhost:9090

ShowOff source code high-lighting for Clojure

- "Clojure combines the expressiveness of Lisp, the agility of a dynamic language, the performance of a compiled language, and the wide applicability of the JVM in a robust, production-ready package. Clojure is a practical language designed to support high-performance, concurrent applications which efficiently interoperate with other software in the JVM ecosystem. All of this combines to make it an ideal tool for the programmer to quickly build robust programs."

And motivate why they chose to support Clojure:

- "Clojure covers a new use case on the Heroku platform: components which demand correctness, performance, composability; and optionally, access to the Java ecosystem."

Ladies and gentlemen, it's time to consider moving the parenthesis from the end of the method name to the beginning of the function call. Try it, you'll like it.

Clojure maps

A map is a data structure that associates keys to values. Maps are very important in Clojure, because they are used to store entity data, much like custom classes with fields and setters/getters are used in traditional object-oriented languages like Java. In the Java world, we have java.util.Map. They are somewhat cumbersome to work with, mostly due to the static, generic typing, but also because there is no literal map syntax, plus the fact that you can't initialize it with elements. You must first create it, then mutate it:

import java.util.Map;
import java.util.HashMap;

Map<String,Object> map = new HashMap<String,Object>();
map.put("somekey", "somevalue");

Clojure maps, on the other hand, have a very concise literal syntax. Zero or more key-value pairs between curly braces. That's it.

(def map {:somekey "somevalue"})

The key :somekey in the map above is a Clojure keyword. Keywords are symbolic identifiers that always evaluate to themselves, and they have a very fast equality check. For those reasons (and others, as we will see), keywords are often used, rather than strings, as keys in maps.

A Clojure map is not only a data structure, it is also a function. When a map is called with a key, it will return the corresponding value (or nil if no key was found). It can look like this when testing it from the REPL:

user> (def animal {:species :lion, :name "Leo", :age 3})
user> (animal :name)
"Leo"

In fact, keywords are functions too. When a keyword is called with a map as argument, it will look itself up in the map and return the matching value:

user> (:name animal)
"Leo"

This form is more common in idiomatic Clojure.

The Ring library

Ring is a Clojure web applications library inspired by Ruby's Rack. Ring abstracts the HTTP request and response as maps, and expects handlers to be functions that take a map as argument and returns a map. The returned map is transformed by Ring into a HTTP response, which is sent back to the caller. This is a simple, but powerful abstraction. It means that web handlers can be written as regular functions, which can be tested in isolation. Web libraries like Compojure build on top of the Ring abstraction and provide more high-level constructs, like routing. In order to not complicate this example, however, we will stick to plain Ring.

Let's say that we have a HTTP request that looks like this:

GET /welcome HTTP/1.1
HOST: www.sayhello.com

Ring transforms this into a Clojure map that looks like this:

{:protocol        :http
 :request-method  :get
 :uri             "/welcome"
 :server-name     "www.sayhello.com"}

Let's further assume that we want to generate a corresponding HTTP response:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 11

Hello world

In order to produce that HTTP response, Ring expects this map:

{:status 200
 :headers
    {"Content-Type" "text/plain"
     "Content-Length" 11}
 :body "Hello world"}

So all we need to do is to provide a function that returns the above map, like this:

(defn app [req]
  {:status 200
   :headers
      {"Content-Type" "text/plain"
       "Content-Length" 11}
   :body "Hello world"})

Ring provides a response convenience function that returns a skeletal response map with status 200, no headers, and the given argument as body:

(use 'ring.util.response)
(defn app [req]
  (response "Hello world"))

We'll use the response function in our example later.

Leiningen

In order to manage our dependencies, we will use the Leiningen build tool. The simplest way to install it is to download the stable release of the script and place it somewhere in the PATH, like ~/bin. Then run lein self-install:

$ lein self-install
Downloading Leiningen now...
...

$ lein version
Leiningen 1.5.2 on Java 1.6.0_24 Java HotSpot(TM) 64-Bit Server VM

Building the web application

We create a new project and go there:

$ lein new cljheroku
$ cd cljheroku

The newly created directory contains the following files:

cljheroku/
├── README
├── project.clj
├── src
│   └── cljheroku
│       └── core.clj
└── test
    └── cljheroku
        └── test
            └── core.clj

First we need to create a Procfile for Heroku:

$ echo "web: lein run -m cljheroku.core" > Procfile

This will have Leiningen start the web application by running the function called -main in the namespace cljheroku.core, ie the file src/cljheroku/core.clj. We'll change that file to contain this:

(ns cljheroku.core
  (:use ring.util.response
        ring.adapter.jetty))

(defn app [req]
  (response "Hello World"))

(defn -main []
  (let [port (Integer/parseInt (get (System/getenv) "PORT" "8080"))]
    (run-jetty app {:port port})))

Let's look at this code in more detail. We begin with the first chunk:

(ns cljheroku.core
  (:use ring.util.response
        ring.adapter.jetty))

The ns macro will create a namespace cljheroku.core and load all functions in the namespaces ring.util.response and ring.adapter.jetty. Since we used :use and not :require, these functions can be referenced by name, without any prefix or namespace qualifier. This enables us to write (response ...) instead of (ring.util.response/response ...).

Then we define our Ring handler called app.

(defn app [req]
  (response "Hello World"))

As you can see, it's just a regular function that takes one argument: a HTTP request map, and returns the result of the response function: a HTTP response map. If we wanted to set the Content-Type header, we could use the content-type function, another function from ring.util.response. Instead of (response "Hello world"), we would pass the response through the content-type function: (content-type (response "Hello world") "text/plain"). But here we will just use response.

Finally we specify a -main function.

(defn -main []
  (let [port (Integer/parseInt (get (System/getenv) "PORT" "8080"))]
    (run-jetty app {:port port})))

It will serve the same purpose as the Java main method, namely provide an entry point from the outside world. It gets the value of the PORT environment variable, or uses 8080 as default. It can be enlightening to analyze that part in detail. (System/getenv) is simply Clojure's way of calling Java's static method System.getenv(), which returns a java.util.Map. The get function takes a map (yes, it works with Java maps too), a key and a default value, and returns the matching value. So, (get (System/getenv) "PORT" "8080") will get the PORT variable from the environment, and if there is no PORT set there, it will return "8080". The resulting string value of the port is parsed into an integer, and is stored as the local variable port. This value is then passed in to the Jetty adapter as part of a configuration map. All this in two lines. If you're not used to Clojure's lack of ceremony, you might find it overwhelming. I personally find it refreshingly to-the-point.

OK, that was the source code for our handler. We now need to adjust the project.clj file slightly, and provide a dependency to Ring. We'll also add an exclusion of a duplicate dependency that Jetty has. Here is the resulting project.clj:

(defproject cljheroku "1.0.0-SNAPSHOT"
  :description "Example Ring app running on Heroku"
  :dependencies [[org.clojure/clojure "1.2.1"]
                 [ring/ring-core "0.3.8"]
                 [ring/ring-jetty-adapter "0.3.8"]]
  :exclusions [org.mortbay.jetty/servlet-api])

Before we do anything else, though, we should add this baby to Git:

$ git init
Initialized empty Git repository in /Users/john/Source/cljheroku/.git/

$ git add .

$ git commit -m "Initial commit"

We should probably push this to a maintained repository somewhere, but for our purposes, we have now stored this in Git.

Testing locally

Before we test it, we will ask Leiningen to retrieve the dependencies:

$ lein deps

The lib directory now contains a list of jars that we need. Leiningen will make sure they all get on the classpath without you ever having to see it. You can ask Leiningen for the classpath, though, should you really like to see it:

$ lein classpath

You can also have Leiningen create a pom file for you, which can be handy if you need to look at the dependency:tree, import the project into an IDE that only knows Maven; things like that:

$ lein pom

Anyway, we can now start this web application using the same command as we placed in the Procfile for Heroku. It will start Clojure with the correct classpath, find and make available the given namespace (cljheroku.core), and call its -main function with any given arguments (none, in our case):

$ lein run -m cljheroku.core
2011-06-12 18:41:24.927:INFO::Logging to STDERR via org.mortbay.log.StdErrLog
2011-06-12 18:41:24.928:INFO::jetty-6.1.26
2011-06-12 18:41:24.959:INFO::Started SocketConnector@0.0.0.0:8080

Browsing to localhost:8080 shows a page with "Hello world" on it. Good. It works.

We now change the handler function to instead respond with, say, "Hello everyone" and save it. When we reload the page, the new message appears. Excellent. It reloads automatically.

OK. We're happy with our web application and want to deploy it into the cloud. What do we do?

Deploying on Heroku

Heroku is, as I mentioned at the beginning, mainly a Ruby application platform. The command line tool for working with Heroku is a Ruby Gem. We first need to install Ruby and RubyGems. Assuming that has been done, we need to get the heroku gem:

$ sudo gem install heroku

Now we can create an app on the Cedar stack:

$ heroku create --stack cedar
Enter your Heroku credentials.
Email: john.doe@example.com
Password:
Found existing public key: /Users/john/.ssh/id_rsa.pub
Would you like to associate it with your Heroku account? [Yn]
Uploading ssh public key /Users/john/.ssh/id_rsa.pub
Creating furious-sword-794... done, stack is cedar
http://furious-sword-794.herokuapp.com/ | git@heroku.com:furious-sword-794.git
Git remote heroku added

We can list the remote repositories to see what the last sentence above meant:

$ git remote -v
heroku	git@heroku.com:furious-sword-794.git (fetch)
heroku	git@heroku.com:furious-sword-794.git (push)

And finally, in order to deploy our first verison of the web app, we push everything to heroku:

$ git push heroku master
The authenticity of host 'heroku.com (50.19.85.156)' can't be established.
RSA key fingerprint is 8b:48:5e:67:0e:c9:16:47:32:f2:87:0c:1f:c8:60:ad.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'heroku.com,50.19.85.156' (RSA) to the list of known hosts.
Counting objects: 13, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (13/13), 1.27 KiB, done.
Total 13 (delta 0), reused 0 (delta 0)

-----> Heroku receiving push
-----> Clojure app detected
-----> Installing Leiningen
       Downloading: leiningen-1.5.2-standalone.jar
       Writing: lein script
-----> Installing dependencies with Leiningen
       Running: lein deps :skip-dev
       Downloading: org/clojure/clojure/1.2.1/clojure-1.2.1.pom from central
       Downloading: ring/ring-core/0.3.8/ring-core-0.3.8.pom from clojars
       ...
       Copying 10 files to /tmp/build_19juox87ngduz/lib
-----> Discovering process types
       Procfile declares types -> web
-----> Compiled slug size is 11.0MB
-----> Launching... done, v4
       http://furious-sword-794.herokuapp.com deployed to Heroku

To git@heroku.com:furious-sword-794.git
 * [new branch]      master -> master

We browse to http://furious-sword-794.herokuapp.com, and we see the text "Hello world" (if you remembered to change back from "Hello everyone"). Now we make a small change:

-  (response "Hello World"))
+  (response "Hello World, I tell you!"))

All we need to do to deploy the change is to commit it, and then push to heroku:

$ git ci -a
$ git push heroku master

When we reload the page, the new text is there.

Roll back to previous release

We can list the releases that have been pushed:

$ heroku releases
Rel   Change                          By                    When
----  ----------------------          ----------            ----------
v5    Deploy 34516b0                  john.doe@examp..  3 minutes ago
v4    Deploy e471ca1                  john.doe@examp..  5 minutes ago

Let's say there was a problem with the release that was just deployed, and we want to roll back. With Heroku, it's trivial to roll back to the previous release:

$ heroku rollback
Rolled back to v4

When we're done with this web app completely, we can destroy it like this:

$ heroku apps:destroy

It's even possible to roll back to earlier releases, but I won't show that here. This concludes the Clojure-on-Heroku guide. Thank you for your time.

References

1. Heroku: http://www.heroku.com/
2. Clojure: http://clojure.org/
3. Ring library: https://github.com/mmcgrana/ring
4. Leiningen: https://github.com/technomancy/leiningen
5. Compojure: https://github.com/weavejester/compojure/wiki
6. FlightCaster uses Clojure and Heroku: http://www.infoq.com/articles/flightcaster-clojure-rails
7. I got the idea for this blog from this Gist: https://gist.github.com/1001206

We will once again look at Section 1.3 of Structure and Interpretation of Computer Programs, Formulating Abstractions with Higher-Order Procedures. To recap, the sum function is an abstraction of a sum of some sequence. It takes a term function for calculating the current term, a start value a, a next function for calculating the next value of a, and an end value b:

(defn sum [term a next b]
  (if (> a b)
    0
    (+ (term a)
       (sum term (next a) next b))))

After introducing the sum function, the authors describe a simple sum for calculating the integral of a function:

Looking at the first term, we see that (a+dx/2) is the start value, ie what we will pass as the a parameter to sum. The term function for calculating the value of the current term is obviously f.

We can also see that each term has one dx added to it. The first term has no dx, the second term has one dx, the third term has 2dx, etc. A simple function adding dx to its argument will be perfect as the next function. We'll define it as a private function using defn-, to not clutter the namespace with internal functions. However, it needs to know the dx, so we'll define it inside the integral function, like this:

(defn integral [f a b dx]
  (defn- add-dx [x] (+ x dx))
  ...

Finally, we need to multiply the result of calling sum by dx. Here is the implementation of the integral function:

(defn integral [f a b dx]
  (defn- add-dx [x] (+ x dx))
  (* (sum f (+ a (/ dx 2)) add-dx b)
     dx))

We'll need a function that we can pass as f, so we can do some interesting integration. Let's use cube:

(defn cube [x] (* x x x))

The integral of x^3 is x^4/4. Integrating from 0 to 1 results in (1^4)/4 = 1/4 = 0.25. That's what we will compare with.

Let's test our integral function using a dx of, say 0.01:

user> (integral cube 0 1 0.01)
0.24998750000000042

Not that bad. However, in Exercise 1.29, the authors suggest using Simpson's Rule, which is a more accurate method of numerical integration.

Simpson's Rule

Simpson's Rule for numerical integration goes like this:

OK, so how do we squeeze this into the sum function? First we note that h is used in more than one place, so we'll begin by creating a local binding h. We'll also multiply the result of sum with h/3:

(defn simpson-sum [f a b n]
  (let [h (/ (- b a) n)]
	...
    (* (sum ... ... ... ...)
       (/ h 3))))

Next, we see that the factor of each term is alternating between 4 and 2, except the first and the last one, which are 1. This can be implemented as a conditional:

(cond (zero? k) y
      (= k n) y
      (odd? k) (* 4 y)
      (even? k) (* 2 y))

The k will be provided as a parameter, as we'll see in a second, but we're missing the y. So let's add the expression of y and package it all up in a function inside simpson-sum:

(defn simpson-sum [f a b n]
  (let [h (/ (- b a) n)]
  (defn- simpson-term [k]
    (let [y (f (+ a (* k h)))]
      (cond (zero? k) y
            (= k n) y
            (odd? k) (* 4 y)
            (even? k) (* 2 y))))
    (* (sum ... ... ... ...)
       (/ h 3))))

OK, so now we have something that, given a k, provides the corresponding term in the sum, with the correct factor. The sequence for the sum is from 0 to n, so all we need to do now is to call sum with simpson-term as the term function, zero as the start value of the sequence, inc as the next function, and n as the end of the sequence:

(defn simpson-sum [f a b n]
  (let [h (/ (- b a) n)]
    (defn- simpson-term [k]
      (let [y (f (+ a (* k h)))]
        (cond (zero? k) y
              (= k n) y
              (odd? k) (* 4 y)
              (even? k) (* 2 y))))
    (* (sum simpson-term 0 inc n)
       (/ h 3))))

The test run on cube using n=100 gives some impressive results:

user> (simpson-sum cube 0 1 100)
1/4
user> (simpson-sum cube 0 2 100)
4
user> (simpson-sum cube 3 4 100)
175/4

Not bad at all. Clojure's use of Ratio enables us to get accurate precision. But what happens if I select a floating point interval?

user> (simpson-sum cube 0 0.5 100)
0.015624999999999995

Pretty good that too.

Using BigDecimal

Now, what if I want to use BigDecimal in order to get really high precision in my floating points? In Clojure, the letter M on a number indicates that it's a BigDecimal literal:

user> (simpson-sum cube 0 0.5M 100)
Non-terminating decimal expansion; no exact representable decimal result.
  [Thrown class java.lang.ArithmeticException]
Backtrace:
  0: java.math.BigDecimal.divide(BigDecimal.java:1603)
  1: clojure.lang.Numbers$BigDecimalOps.divide(Numbers.java:1067)
  2: clojure.lang.Numbers.divide(Numbers.java:139)
  3: user$simpson_sum.invoke(NO_SOURCE_FILE:1)

What happened here? Actually, this is something that can potentially happen whenever using BigDecimal divison, whether it's from Java, Clojure or something else. The JavaDoc for BigDecimal.divide states:

divide(BigDecimal divisor)
Returns a BigDecimal whose value is (this / divisor), and whose preferred scale is (this.scale() - divisor.scale()); if the exact quotient cannot be represented (because it has a non-terminating decimal expansion) an ArithmeticException is thrown.

Could it be that division of h by 3 that messes things up? Division by 3 is always troublesome when using floating point numbers. Anyway, in order to solve this, we need to use a version of BigDecimal.divide that takes a scale (we'll use 10) and a rounding mode. Only line 10 needs to be changed:

(defn simpson-sum [f a b n]
  (let [h (/ (- b a) n)]
    (defn- simpson-term [k]
      (let [y (f (+ a (* k h)))]
        (cond (zero? k) y
              (= k n) y
              (odd? k) (* 4 y)
              (even? k) (* 2 y))))
    (* (sum simpson-term 0 inc n)
       (.divide (bigdec h) 3M 10 java.math.RoundingMode/HALF_UP))))

Ugly as hell, but what can you do? (Plenty, actually, as we'll see soon) Let's test it:

user> (simpson-sum cube 0 0.5M 100)
0.0156250031250000000000M

OK, so it works. Are we happy now? Not really. Look what happens if we use an n that is a multiple of 3:

user> (simpson-sum cube 0 0.5M 6)
Non-terminating decimal expansion; no exact representable decimal result.
  [Thrown class java.lang.ArithmeticException]
Backtrace:
  0: java.math.BigDecimal.divide(BigDecimal.java:1603)
  1: clojure.lang.Numbers$BigDecimalOps.divide(Numbers.java:1067)
  2: clojure.lang.Numbers.divide(Numbers.java:139)
  3: user$simpson_sum.invoke(NO_SOURCE_FILE:1)

This time it's the other division that is the problem. We'll change line 2 as well:

(defn simpson-sum [f a b n]
  (let [h (.divide (bigdec (- b a)) (bigdec n) 10 java.math.RoundingMode/HALF_UP)]
    (defn- simpson-term [k]
      (let [y (f (+ a (* k h)))]
        (cond (zero? k) y
              (= k n) y
              (odd? k) (* 4 y)
              (even? k) (* 2 y))))
    (* (sum simpson-term 0 inc n)
       (.divide (bigdec h) 3M 10 java.math.RoundingMode/HALF_UP))))

user> (simpson-sum cube 0 0.5M 6)
0.0156249999937499999925000000049999999992M

So, we're good now? No, Clojure has actually a much better way of handling this than resorting to the above. Let's look at the documentation for the function with-precision:

user> (doc with-precision)
-------------------------
clojure.core/with-precision
([precision & exprs])
Macro
  Sets the precision and rounding mode to be used for BigDecimal operations.               

  Usage: (with-precision 10 (/ 1M 3))
  or:    (with-precision 10 :rounding HALF_DOWN (/ 1M 3))                                  

  The rounding mode is one of CEILING, FLOOR, HALF_UP, HALF_DOWN,
  HALF_EVEN, UP, DOWN and UNNECESSARY; it defaults to HALF_UP.

OK, so we simply call with-precision with the expression we want precision on. Pretty elegant. Here is the final implementation:

(defn simpson-sum [f a b n]
  (with-precision 10
    (let [h (/ (- b a) n)]
      (defn- simpson-term [k]
        (let [y (f (+ a (* k h)))]
          (cond (zero? k) y
                (= k n) y
                (odd? k) (* 4 y)
                (even? k) (* 2 y))))
      (* (sum simpson-term 0 inc n)
         (/ h 3)))))

We're now getting even better results than when manually providing a scale to BigDecimal.divide. Here is a run with n=6:

user> (simpson-sum cube 0 0.5M 6)
0.01562500000M

Compare that with the integral function that we implemented first. That would have given us this result:

user> (integral cube 0 0.5 0.01)
0.015621875000000023

The exact integral of x^3 between 0 and 0.5 is (0.5^4)/4 = 0.015625, so it's clear that Simpson's Rule is very good for numerical integration. The code becomes really elegant even when using BigDecimal arithmetic, thanks to Clojure's support for BigDecimal precision.

References

• Equations were rendered using the LaTeX Equation Editor: http://www.hamline.edu/~arundquist/equationeditor/
• My previous blog entry about the sum function: http://blog.jayway.com/2011/03/20/the-substitution-model-a-tool-for-understanding-recursion/
• Structure and Interpretation of Computer Programs: http://mitpress.mit.edu/sicp/

• a sum of an integer range
• a sum of the cubes of an integer range
• a sum of a series that converges to π/8

The purpose is to highlight what is common between them and what differs. The differences boil down to:

1. calculating the current term
2. calculating the next value

The authors show that all three functions can be expressed as calls to a higher-order function. Here is the sum function in Clojure:

(defn sum [term a next b]
  (if (> a b)
    0
    (+ (term a)
       (sum term (next a) next b))))

The function takes four parameters: [term a next b]. term is the function for calculating the current term, a is the start of the range to perform the sum on, next is the function for calculating the next value in the sequence, and b is the end of the range. The sum function first calculates the current term by applying term to a, then adds that to the result of calling itself again, but this time not with a, but the next value in the sequence: (next a). It keeps doing that until a is greater than b, then the upper bound is reached and the function is done. It doesn't call itself any more, but instead returns zero.

sum-integers

Using sum to calculate a sum of integers is easy. Each number in the sequence will itself be the actual term. We use the identity function as term, since it returns its input unchanged. The inc function increments its argument by one, so that is ideal for next. Here is the implementation:

(defn sum-integers [a b]
  (sum identity a inc b))

I'll test the function in my REPL (user> is the prompt):

user> (sum-integers 1 10)
55

sum-cubes

The second example is summing up the cubes of an integer range. We define the cube function:

(defn cube [x] (* x x x))

The implementation of sum-cubes is very similar to sum-integers. We simply replace identity with cube, so the current term will be the cube of the integer, rather than just the integer:

(defn sum-cubes [a b]
  (sum cube a inc b))

user> (sum-cubes 1 10)
3025

pi-sum

The third example is a series that happens to converge to π/8:

In order to be able to apply the generic sum tool to this problem, we need to write two helper functions: one function for calculating the current term: pi-term, and one function for calculating the next value in the sequence: pi-next. We can see, by looking at the series above, that each term is 1/(x*(x+2)), and that the next term has an x that is 4 greater than the previous term:

(defn- pi-term [x] (/ 1 (* x (+ x 2))))
(defn- pi-next [x] (+ x 4))

Note that I didn't use defn to define the functions, I used defn-. That is a Clojure feature for making the helper functions private, so we don't clutter up the namespace with internal stuff. Now we have what we need to call sum.

(defn pi-sum [a b]
  (sum pi-term a pi-next b))

We'll test this function with the range 1 to 10, multiplying with 8 so we'll get π (remember that the series converges to π/8):

user> (* 8 (pi-sum 1 10))
10312/3465

Here we can see that the output is Clojure's built-in type Ratio. Division of integers that can't be reduced to an integer yields a ratio, rather than a floating point or truncated value. This can be really useful, but when the numbers get large, it can be hard to see what the ratio represents:

user> (* 8 (pi-sum 1 100))
3400605476464206445954873476681150352328/1089380862964257455695840764614254743075

Any numeric operation on a Ratio involving Doubles, will yield a Double. That means we can skip the Ratio and go directly to Double by using 1.0 as the starting point:

user> (* 8 (pi-sum 1. 1000))
3.139592655589783

The Substitution Model

If it's not immediately obvious to you how sum works, you can always use the Substitution Model. Evaluate the body of the procedure with each formal parameter replaced by the corresponding argument. Let's evaluate the call (sum-integers 1 3):

Retrieve the body of sum-integers:

(sum identity a inc b)

Replace the formal parameters a and b by the arguments 1 and 3:

(sum identity 1 inc 3)

The problem is reduced to evaluating a call to sum with four arguments. So let's retrieve the body of sum:

(if (> a b)
  0
  (+ (term a)
     (sum term (next a) next b)))

Now we replace sum's formal parameters [term a next b] with our arguments identity, 1, inc, and 3:

(if (> 1 3)
  0
  (+ (identity 1)
     (sum identity (inc 1) inc 3)))

1 is not greater than 3, so it reduces to:

(+ (identity 1)
   (sum identity (inc 1) inc 3))

(identity 1) evaluates to 1, and (inc 1) evaluates to 2, so it reduces to:

(+ 1
   (sum identity 2 inc 3))

We'll evaluate the call to sum again, directly replacing this time:

(+ 1
  (if (> 2 3)
    0
    (+ (identity 2)
       (sum identity (inc 2) inc 3))))

2 is not greater than 3, so this reduces to:

(+ 1
  (+ 2
     (sum identity 3 inc 3)))

We retrieve the body of sum again, replacing parameters with arguments:

(+ 1
  (+ 2
    (if (> 3 3)
      0
      (+ (identity 3)
         (sum identity (inc 3) inc 3))))

3 is not greater than 3, so this reduces to:

(+ 1
  (+ 2
    (+ 3
       (sum identity 4 inc 3))))

We retrieve the body of sum for the last time:

(+ 1
  (+ 2
    (+ 3
      (if (> 4 3)
        0
        (+ (identity 4)
           (sum identity (inc 4) inc 3))))

4 is greater than 3, so this reduces to:

(+ 1
  (+ 2
    (+ 3
      0)))

which evaluates to 6.

The Substitution Model is a useful technique when you're new to functional programming, or when you just need to know in detail what is really going on in a function.

I want a debug function that first prints the "quoted" (unevaluated) code and then what it evaluates to, so I can write something like this:

user> (dbg (+ 1 2))
dbg: (+ 1 2)=3
3

This can be useful in iterations, for example, to check whether you get what you expect in each step:

user> (for [i (range 5)] (dbg (+ 1 i)))
(dbg: (+ 1 i)=1
dbg: (+ 1 i)=2
dbg: (+ 1 i)=3
dbg: (+ 1 i)=4
dbg: (+ 1 i)=5
1 2 3 4 5)

Quoting is best explained using an example:

user> (+ 1 2 3)
6

user> (quote (+ 1 2 3))
(+ 1 2 3)

I'm also going to use the let form, to get convenient temporary access to an expression for the duration of the let scope. Outside the let scope, the symbol is not available:

user> (let [x (+ 1 2 3)] (println x))
6
nil

user> x
Unable to resolve symbol: x in this context

So what I want is code that looks something like this:

  (let [x body]
    (println (str "dbg: " (quote body) "=" x))
    x)

In order to get the code in, we declare it as an argument using the varargs symbol (&), which will give us body as a list of forms (expressions):

(defsomething dbg [& body]
  (let [x body]
    (println (str "dbg: " (quote body) "=" x))
    x))

If we declare this as a function using defn, the arguments (body) will be evaluated before the function is called. We don't want that, so we instead use defmacro to get control over the evaluation. Using the macro syntax quote (`), we can actually write the code exactly as we want it, and then simply unquote (~) the body symbol to get the symbol value:

(defmacro dbg [& body]
  `(let [x ~body]
     (println (str "dbg: " (quote ~body) "=" x))
     x))

However, varargs are delivered as a list, so simply unquoting body will give us some strange result. We can check it using macroexpand-1. You'll see that the macro tries to evaluate body by placing the list inside a list: ((+ 1 2)):

user> (macroexpand-1 '(dbg (+ 1 2)))
(let [user/x ((+ 1 2))]
  (println (str "dbg: " (quote ((+ 1 2)))) "=" user/x))
  user/x)

What we want is the contents of the varargs list as separate elements, not as a list. We change the unquote operator (~) to the unquote-splicing operator (~@):

(defmacro dbg [& body]
  `(let [x ~@body]
     (println (str "dbg: " (quote ~@body) "=" x))
     x))

We expand the macro again, and now it looks better:

user> (macroexpand-1 '(dbg (+ 1 2)))
(let [user/x (+ 1 2)]
  (println (str "dbg: " (quote (+ 1 2)))) "=" user/x))
  user/x)

However, note the fully namespace-qualified symbol user/x. Clojure will not allow this due to the risks of name conflicts. When we try to run this macro, we will get an exception: Can't let qualified name: user/x. We need some way of generating a unique symbol on the fly. We use the symbol generation operator (#):

(defmacro dbg [& body]
  `(let [x# ~@body]
     (println (str "dbg: " (quote ~@body) "=" x#))
     x#))

We test it:

user> (macroexpand-1 '(dbg (+ 1 2)))
(let [x__2071__auto__ (+ 1 2)]
  (println (str "dbg: " (quote (+ 1 2)) "=" x__2071__auto__))
  x__2071__auto__)

OK, so the final macro looks like this:

(defmacro dbg [& body]
  `(let [x# ~@body]
     (println (str "dbg: " (quote ~@body) "=" x#))
     x#))

This boils down to two very simple rules:

• Any temporary symbols must be appended with # to become unique symbols
• Any varargs arguments must be unquote-spliced using ~@

Let's try our macro:

user> (dbg (+ 1 2))
(+ 1 2)=3
3

Let's confirm that the debug functionality does not affect others using the dbg'd code:

user> (* 3 (dbg (+ 1 2)))
dbg: (+ 1 2)=3
9

Now, let's try the dbg macro on some more advanced code. Here's an implementation of factorial using loop-recur:

(def factorial
  (fn [n]
    (loop [cnt n acc 1]
      (if (zero? cnt)
        acc
        (recur (dec cnt) (* acc cnt))))))

To check what happens inside the recur function, I add calls to dbg:

(def factorial
  (fn [n]
    (loop [cnt n acc 1]
      (if (zero? cnt)
        acc
        (recur (dbg (dec cnt)) (dbg (* acc cnt)))))))

Calling it gives:

user> (factorial 5)
dbg: (dec cnt)=4
dbg: (* acc cnt)=5
dbg: (dec cnt)=3
dbg: (* acc cnt)=20
dbg: (dec cnt)=2
dbg: (* acc cnt)=60
dbg: (dec cnt)=1
dbg: (* acc cnt)=120
dbg: (dec cnt)=0
dbg: (* acc cnt)=120
120

% ldapadd -Dcn=Manager,dc=jayway,dc=se -wsomepwd -f /tmp/t.ldif
adding new entry "ou=groups,dc=jayway,dc=se"

adding new entry "c=Sweden,dc=jayway,dc=se"
ldap_add: Invalid DN syntax (34)

After some time of swearing and random changes, I managed to find out the following little piece of information (which seems rather obvious in hindsight): country (c) is supposed to be the two-letter ISO 3166 country code.

But hang on now, we have in the Spring LDAP samples successfully been using c=Sweden and c=Norway. What is this? Well, it's actually very simple. Back in the good old days in 1997, the RFC2256 specified the c attribute (countryName) like this:

5.7. c

   This attribute contains a two-letter ISO 3166 country code
   (countryName).

    ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE )

Note that they suggest only in text that it should be the two-letter ISO code. This is curious, since in fact there existed a syntax specification at that time, specified in RFC2252:

6.8. Country String

   ( 1.3.6.1.4.1.1466.115.121.1.11 DESC 'Country String' )

   A value in this syntax is encoded the same as a value of Directory
   String syntax.  Note that this syntax is limited to values of exactly
   two printable string characters, as listed in ISO 3166 [14].

      CountryString  = p p

   Example:
      US

In the newer spec RFC4519 from 2006, they are much more strict:

2.2.  'c'

   The 'c' ('countryName' in X.500) attribute type contains a two-letter
   ISO 3166 [ISO3166] country code.
   (Source: X.520 [X.520])

      ( 2.5.4.6 NAME 'c'
         SUP name
         SYNTAX 1.3.6.1.4.1.1466.115.121.1.11
         SINGLE-VALUE )

   1.3.6.1.4.1.1466.115.121.1.11 refers to the Country String syntax
   [RFC4517].

   Examples: "DE", "AU" and "FR".

Note that they have added a SYNTAX directive, which means there is no escape any more. Apparently, later versions of OpenLDAP are using a core.schema that follows RFC4519. This is good, I guess. I just wish someone would have told me about it...

When the ratio between a and b is equal to the ratio between a+b and a, then you have the Golden Ratio. The value of the Golden Ratio is:

Why is it so special? Because if you know about it, it can be seen in many different places; in geometrical figures, in architecture, in paintings, and in nature. I'll show you. Draw a pentagon:

Draw straight lines between all vertices of the pentagon. This will result in a pentagram (five-pointed star). Now mark the lengths a and b as this picture shows:

Guess what the ratio is between the lengths a and b? The Golden Ratio. Now, mark two other lengths a' and b':

You guessed it. The ratio between a' and b' is the Golden Ratio.

It's actually pretty easy to approximate Phi (φ), as the Golden Ratio normally is called. Take any two numbers and add them, then divide the sum with the larger number. For example, 11 and 74:

11.0+74.0=85.0
85.0/74.0=1.1486486486486487

Now we add the larger of the numbers (74) to the sum (85), and then we again divide the new sum (159) with the the previous sum (85):

74.0+85.0=159.0
159.0/85.0=1.8705882352941177

We're getting there. One more time:

85.0+159.0=244.0
244.0/159.0=1.5345911949685536

No, this is too tedious. Let's write a program that does it. For no reason whatsoever, I'll pick Scala. What is Scala? I'm on a Mac, so I'll just do:

% port info scala
scala @2.7.5 (lang, java)

Description:          Scala is a modern multi-paradigm programming language designed to express common programming patterns
                      in a concise, elegant, and type-safe way. It smoothly integrates features of object-oriented and
                      functional languages. It runs inside a Java Virtual Machine and is fully interoperable with Java.
Homepage:             http://www.scala-lang.org/

This is how I install Scala:

% sudo port install scala

I'll want some editor support, so I install the TextMate bundle that accompanies Scala:

% cd /Library/Application\ Support/TextMate/Bundles/
% unzip /opt/local/share/scala/misc/scala-tool-support/textmate/Bundles/Scala.tmbundle.zip

I'll tell TextMate to reload its bundles by selecting the menu "Bundles | Bundle Editor | Reload Bundles". Now I'm all set.

Consider this Scala program (phi1.scala):

var x = 11.
var y = 74.

for (i <- 1 to 5) {
    var sum = x + y
    var q = sum / y
    println(q)
    x = y
    y = sum
}

I'll run it like this:

% scala phi1.scala
1.1486486486486487
1.8705882352941177
1.5345911949685536
1.651639344262295
1.6054590570719602

It's not pretty, but it does the job. Let's spice it up with some input arguments and better printout (phi2.scala):

var x = 11.
var y = 74.
var n = 13

if (args.length > 3) {
    println("Usage: scala phi2.scala [n [x [y]]]")
    println("  n: number of times to perform calculation (default: " + n + ")")
    println("  x: start value of 'x' (default: " + x + ")")
    println("  y: start value of 'y' (default: " + y + ")")
    System.exit(1)
}
if (args.length >= 1) n = Integer.parseInt(args(0))
if (args.length >= 2) x = Integer.parseInt(args(1))
if (args.length == 3) y = Integer.parseInt(args(2))

for (i <- 1 to n) {
    var sum = x + y
    print(i + ": " + x + "+" + y + "=" + sum)
    var q = sum / y
    println(", " + sum + "/" + y + "=" + q)
    x = y
    y = sum
}

I'll run it with four arguments to test it:

% scala phi2.scala 1 2 3 4
Usage: scala phi2.scala [n [x [y]]]
  n: number of times to perform calculation (default: 13)
  x: start value of 'x' (default: 11.0)
  y: start value of 'y' (default: 74.0)

I won't bore you with more tests, but instead do what we intended to do from the start: have a program run the iterations for us. I'll run it with no arguments, using the defaults:

% scala phi2.scala
1: 11.0+74.0=85.0, 85.0/74.0=1.1486486486486487
2: 74.0+85.0=159.0, 159.0/85.0=1.8705882352941177
3: 85.0+159.0=244.0, 244.0/159.0=1.5345911949685536
4: 159.0+244.0=403.0, 403.0/244.0=1.651639344262295
5: 244.0+403.0=647.0, 647.0/403.0=1.6054590570719602
6: 403.0+647.0=1050.0, 1050.0/647.0=1.6228748068006182
7: 647.0+1050.0=1697.0, 1697.0/1050.0=1.6161904761904762
8: 1050.0+1697.0=2747.0, 2747.0/1697.0=1.618738951090159
9: 1697.0+2747.0=4444.0, 4444.0/2747.0=1.6177648343647615
10: 2747.0+4444.0=7191.0, 7191.0/4444.0=1.618136813681368
11: 4444.0+7191.0=11635.0, 11635.0/7191.0=1.6179947156167431
12: 7191.0+11635.0=18826.0, 18826.0/11635.0=1.6180489901160293
13: 11635.0+18826.0=30461.0, 30461.0/18826.0=1.6180282587910337

Actually, I will run one more test, but this time I'll choose the starting values more carefully. One of many wonderful properties of the Fibonacci series is that the ratio between the numbers is very close to the Golden Ratio. This means it will converge much quicker. Check this out, four correct decimals after just four iterations:

% scala phi2.scala 4 21 34
1: 21.0+34.0=55.0, 55.0/34.0=1.6176470588235294
2: 34.0+55.0=89.0, 89.0/55.0=1.6181818181818182
3: 55.0+89.0=144.0, 144.0/89.0=1.6179775280898876
4: 89.0+144.0=233.0, 233.0/144.0=1.6180555555555556

Here is the final version, with some stuff that makes the file executable (phi.scala):

#!/bin/sh
exec scala $0 $@
!#
var x = 11.
var y = 74.
var n = 13

if (args.length > 3) {
    println("Usage: scala phi.scala [n [x [y]]]")
    println("  n: number of times to perform calculation (default: " + n + ")")
    println("  x: start value of 'x' (default: " + x + ")")
    println("  y: start value of 'y' (default: " + y + ")")
    System.exit(1)
}
if (args.length >= 1) n = Integer.parseInt(args(0))
if (args.length >= 2) x = Integer.parseInt(args(1))
if (args.length == 3) y = Integer.parseInt(args(2))

for (i <- 1 to n) {
    var sum = x + y
    print(i + ": " + x + "+" + y + "=" + sum)
    var q = sum / y
    println(", " + sum + "/" + y + "=" + q)
    x = y
    y = sum
}

I'll make it executable and run it:

% chmod +x phi.scala
% ./phi.scala 10 13 21
1: 13.0+21.0=34.0, 34.0/21.0=1.619047619047619
2: 21.0+34.0=55.0, 55.0/34.0=1.6176470588235294
3: 34.0+55.0=89.0, 89.0/55.0=1.6181818181818182
4: 55.0+89.0=144.0, 144.0/89.0=1.6179775280898876
5: 89.0+144.0=233.0, 233.0/144.0=1.6180555555555556
6: 144.0+233.0=377.0, 377.0/233.0=1.6180257510729614
7: 233.0+377.0=610.0, 610.0/377.0=1.6180371352785146
8: 377.0+610.0=987.0, 987.0/610.0=1.618032786885246
9: 610.0+987.0=1597.0, 1597.0/987.0=1.618034447821682
10: 987.0+1597.0=2584.0, 2584.0/1597.0=1.6180338134001253

Check out Golden Ratio on Wikipedia for more details.

Unit testing is often used to test complex units with one or more collaborators, usually with the help of mock objects. But the greatest value with unit testing, in my opinion, lies in testing the lowest level utility methods; the building blocks that simply have to be bullet-proof in order for the rest of the system to have a stable foundation.

Let's say that we have an Article domain object, storing article numbers from the database in the form "01234567":

public class Article {

    /**
     * 8 character numeric article number, eg "01234567".
     */
    private String articleNumber = "";

    public String getArticleNumber() {
        return articleNumber;
    }

    public void setArticleNumber(String articleNumber) {
        this.articleNumber = articleNumber;
    }
}

Business now demands that the article number should be formatted with dots here and there. They have added the story "User should see article numbers formatted as 123.456.78" to the Sprint Backlog.

We decide to write a test for this:

import static org.junit.Assert.assertEquals;
import org.junit.Test;

public class ArticleTest {

    @Test
    public void testGetFormattedArticleNumberNoZeros() {
        Article tested = new Article();
        tested.setArticleNumber("98765432");
        assertEquals("987.654.32", tested.getFormattedArticleNumber());
    }
}

We search around for a while, and find several nice tools for parsing formatted strings, but nothing useful for writing formatted strings that will help us in our scenario. Lacking ideas, we desperately try DecimalFormat. It's actually not that bad. If we divide by 100, we'll automatically get the right-most dot, don't we? We decide to give it a try:

import java.math.BigDecimal;
import java.text.DecimalFormat;
import java.text.DecimalFormatSymbols;
import java.text.NumberFormat;

public class Article {

    /**
     * 8 character numeric article number, eg "01234567".
     */
    private String articleNumber = "";

    public String getArticleNumber() {
        return articleNumber;
    }

    public void setArticleNumber(String articleNumber) {
        this.articleNumber = articleNumber;
    }

    /**
     * Retrieves the formatted article number.
     *
     * TODO I didn't find a nice generic formatting method, so I wrote this terrible hack.
     *
     * @return the formatted article number, eg 123.456.78
     */
    public String getFormattedArticleNumber() {
        NumberFormat nf = NumberFormat.getNumberInstance();
        DecimalFormat df = (DecimalFormat) nf;
        BigDecimal number = new BigDecimal(articleNumber);
        number = number.divide(new BigDecimal(100));
        String str = df.format(number);
        return str;
    }
}

We get a failure:

expected:<987[.654.]32> but was:<987[ 654,]32>

The decimal point is a comma (,) in the default locale, and the grouping separator is a blank. We can tweak that by calling the getDecimalFormatSymbols method, giving us a DecimalFormatSymbols that we can change:

DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
symbols.setDecimalSeparator('.');
symbols.setGroupingSeparator('.');
df.setDecimalFormatSymbols(symbols);

We also make sure the grouping size is always three by calling df.setGroupingSize(3). Here is the code so far:

public String getFormattedArticleNumber() {
    NumberFormat nf = NumberFormat.getNumberInstance();
    DecimalFormat df = (DecimalFormat) nf;
    df.setGroupingSize(3);
    DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
    symbols.setDecimalSeparator('.');
    symbols.setGroupingSeparator('.');
    df.setDecimalFormatSymbols(symbols);
    BigDecimal number = new BigDecimal(articleNumber);
    number = number.divide(new BigDecimal(100));
    String str = df.format(number);
    return str;
}

Success! Excellent. Now, we suspect that there might be problems with leading zeros, so we add another test:

    @Test
    public void testGetFormattedArticleNumberLeadingZero() {
        Article tested = new Article();
        tested.setArticleNumber("01234567");
        assertEquals("012.345.67", tested.getFormattedArticleNumber());
    }

As we suspected. We get a failure:

expected:<[0]12.345.67> but was:<[]12.345.67>

This can be fixed by setting the minimum integer size to 6:

df.setMinimumIntegerDigits(6);

We run the test suite again. Success! Great. We suspect that trailing zeros can also be troublesome. We add a few tests for that:

    @Test
    public void testGetFormattedArticleNumberSingleTrailingZero() {
        Article tested = new Article();
        tested.setArticleNumber("98765430");
        assertEquals("987.654.30", tested.getFormattedArticleNumber());
    }

    @Test
    public void testGetFormattedArticleNumberTrailingZeros() {
        Article tested = new Article();
        tested.setArticleNumber("98765400");
        assertEquals("987.654.00", tested.getFormattedArticleNumber());
    }

    @Test
    public void testGetFormattedArticleNumberAllZeros() {
        Article tested = new Article();
        tested.setArticleNumber("00000000");
        assertEquals("000.000.00", tested.getFormattedArticleNumber());
    }

We run the tests. The last three tests all fail, indicating that trailing zeros are lost. We fix that by setting the minimum fraction size to 2:

df.setMinimumFractionDigits(2);

Success! The complete method now looks like this:

/**
 * Retrieves the formatted article number.
 *
 * TODO I didn't find a nice generic formatting method, so I wrote this terrible hack.
 *
 * @return the formatted article number, eg 123.456.78
 */
public String getFormattedArticleNumber() {
    NumberFormat nf = NumberFormat.getNumberInstance();
    DecimalFormat df = (DecimalFormat) nf;
    df.setGroupingSize(3);
    df.setMinimumIntegerDigits(6);
    df.setMinimumFractionDigits(2);
    DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
    symbols.setDecimalSeparator('.');
    symbols.setGroupingSeparator('.');
    df.setDecimalFormatSymbols(symbols);
    BigDecimal number = new BigDecimal(articleNumber);
    number = number.divide(new BigDecimal(100));
    String str = df.format(number);
    return str;
}

It's not pretty, but it works. We check in the code, relax, and think for a while. Is there a simpler way? Of course there is:

/**
 * Retrieves the formatted article number.
 *
 * @return the formatted article number, eg 123.456.78
 */
public String getFormattedArticleNumber() {
    StringBuffer number = new StringBuffer(articleNumber);
    number.insert(3, '.');
    number.insert(7, '.');
    return number.toString();
}

Here, the power of unit testing shows. We don't even think twice about replacing the existing code. The tests still run, so we hook this code into the user interface, run the functional tests, check in, wait for a successful build, and finally ask the Product Owner to run the acceptance tests for the story.

This was the result that I got:

$ sudo port upgrade groovy
--->  Building groovy
...
Command output:     [javac] Compiling 699 source files to /opt/local/var/macports/build/_opt_local_var_macports_sources_rsync.macports.org_release_ports_java_groovy/work/groovy-1.6.2/target/classes
    [javac]
    [javac]
    [javac] The system is out of resources.
    [javac] Consult the following stack trace for details.
    [javac] java.lang.OutOfMemoryError: Java heap space
    ...
    [javac] 	at com.sun.tools.javac.Main.main(Main.java:54)

BUILD FAILED
/opt/local/var/macports/build/_opt_local_var_macports_sources_rsync.macports.org_release_ports_java_groovy/work/groovy-1.6.2/build.xml:173: Compile failed; see the compiler error output for details.

Looking in the directory mentioned above, we find a build.properties file that contains some settings:

$ cat /opt/local/var/macports/build/_opt_local_var_macports_sources_rsync.macports.org_release_ports_java_groovy/work/groovy-1.6.2/build.properties
...
groovycMain_mx = 512m
groovycTest_mx = 1G
groovycExamples_mx = ${groovycMain_mx}

javaDoc_mx = 512m
groovyDoc_mx = 640m

OK, plenty of memory, but nothing seems related to javac compilation. Let's check the line 173, that the error message mentioned:

sudo vi +173 /opt/local/var/macports/build/_opt_local_var_macports_sources_rsync.macports.org_release_ports_java_groovy/work/groovy-1.6.2/build.xml

The javac call there does not contain any memory setting, so we must assume that it uses the default heap size:

<javac srcdir="${mainSourceDirectory}" includeantruntime="false" destdir="${mainClassesDirectory}"
       deprecation="on" debug="yes" source="1.5" target="1.5" fork="true" classpathref="compilePath">

However, looking a few lines further down, we find the groovyc call:

<groovyc srcdir="${mainSourceDirectory}" destdir="${mainClassesDirectory}" fork="true" memorymaximumsize="${groovycMain_mx}">

Let's add the same memory setting as the groovyc call uses to the javac call:

<javac srcdir="${mainSourceDirectory}" includeantruntime="false" destdir="${mainClassesDirectory}"
       memorymaximumsize="${groovycMain_mx}" deprecation="on" debug="yes" source="1.5" target="1.5" fork="true" classpathref="compilePath">

Let's try the upgrade again:

$ sudo port upgrade groovy
--->  Building groovy
--->  Staging groovy into destroot
--->  Deactivating groovy @1.6.1_0
--->  Installing groovy @1.6.2_0
--->  Activating groovy @1.6.2_0
--->  Cleaning groovy

Success.

Update: The memory problem seems to be related to Java6. Switching to Java5 makes the build go through, and I've replicated that on two Macs.

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person(attr:'value')
}
println w

Resulting XML is:

<persons>
  <person attr='value' />
</persons>

Let's remove the seemingly redundant parenthesis on the call to 'person':

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person attr:'value'
}
println w

Resulting XML is:

<persons>
  <person attr='value' />
</persons>

Identical. Good, all is well, you think. But it's not. We add an empty closure to 'person', which really should not have any effect:

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person attr:'value' {}
}
println w

Resulting XML is:

<persons>
  <value />
  <person attr='value' />
</persons>

What happened here? An element was inserted with the same name as my attribute value.

Now, let's add something to the empty closure:

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person attr:'value' {
        kid()
    }
}
println w

Resulting XML is:

<persons>
  <value>
    <kid />
  </value>
  <person attr='value' />
</persons>

Even more strange. The 'kid' element ended up inside the 'value' element.

If I add parenthesis to 'person', then everything works as expected:

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person(attr:'value') {
        kid()
    }
}
println w

Resulting XML is:

<persons>
  <person attr='value'>
    <kid />
  </person>
</persons>

I don't want to turn this feather into something it is not. When using Builders, use parenthesis, end of story. However, for those of us that can't let something like this pass, here follows my analysis.

The Groovy Statements page says:

If a method takes parameters you can leave the closure outside of the parenthesis (provided that the closure parameter is the last parameter on the underlying method).

    def value = [1, 2, 3].inject(0) { count, item -> count + item }
    assert value == 6

The above code is equivalent to the following (but just neater)

    def value = [1, 2, 3].inject(0, { count, item -> count + item })
    assert value == 6

So what does that tell us? Well, if our closure is really the last parameter to the 'person' call, then we should be able to write this:

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person (attr:'value', {
        kid()
    })
}
println w

Note the comma after 'value'. Let's run that code:

<persons>
  <person attr='value'>
    <kid />
  </person>
</persons>

OK, it looks fine. However, when we skipped the parenthesis, we implicitly also skipped that crucial comma. In effect, we wrote what's equivalent to this:

def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person (attr:'value' {
        kid()
    })
}
println w

This is really interesting. It looks like the only parameter to 'person' now is a single map entry attr that maps to ... what exactly? Running this will result in the now well-known:

<persons>
  <value>
    <kid />
  </value>
  <person attr='value' />
</persons>

Can you see it yet?

This whole discussion started with the claim that parenthesis are optional to method calls. And that's exactly what 'value' is: a method call with a Closure as a parameter:

'value' { kid() }

It's OK to quote method names, for example if they contain illegal characters like '-', but it's of course also OK to quote a method name that doesn't contain illegal characters.

So, let's define a method 'value' that takes a Closure as parameter, in order to see if it gets called:

def value(Closure c) { println 'inside method value'; return 'returned value'}
def w = new StringWriter()
def builder = new groovy.xml.MarkupBuilder(w)
builder.persons() {
    person (attr:'value' {
        kid()
    })
}
println w

We get this:

inside method value
<persons>
  <person attr='returned value' />
</persons>

Pretty convincing, right?

Having code coverage of your unit tests is important, because it'll give you an indication of where you should focus your efforts next. The open source coverage tool Cobertura gives you not only code coverage, it also shows you the code complexity level of packages and classes. This directs you towards the untested parts that are the most complex and most likely also the most error-prone.

The Problem

Rumor has it that Maven2 in an upcoming release will support having integration tests in a source folder called src/it/java, and run those in the integration-test phase. That would be a welcome improvement. Currently, however, Maven2 lacks good support for integration tests, and so does Cobertura. It's really a pain to get coverage on both unit tests and integration tests.

Let's say that you want to keep your integration tests in the same module as the unit tests. In fact, this might be a wise decision, since it's even harder to get Cobertura to provide coverage on two separate modules. Still, you do want to separate them somehow, and for now you have named the integration tests IntTestSomething and the unit tests TestSomething.

src/test/java/
`-- org
    `-- springframework
        `-- ldap
            `-- samples
                `-- article
                    |-- dao
                    |   |-- AbstractIntTestPersonDao.java
                    |   |-- IntTestPersonDaoImpl.java
                    |   `-- IntTestTraditionalPersonDaoImpl.java
                    `-- domain
                        `-- PersonTest.java

Cobertura will run the tests through Surefire, which has a default pattern that picks up the unit tests, but not the integration tests. We don't want coverage on the integration tests all the time, so that's fine. But how do we include the integration tests on-demand?

The Solution

I will keep the unit tests in the src/test/java folder, but move the integration tests to a newly created src/it/java folder. Then I will use some magic to incorporate that folder into the Maven build path, but only if I specify a certain profile. I will be able to do this:

% mvn test
// runs unit tests only

% mvn cobertura:cobertura
// provides coverage on unit tests only

% mvn test -Pitcov
// runs unit tests and integration tests

% mvn cobertura:cobertura -Pitcov
// provides coverage on unit tests and integration tests

Create the folder src/it/java and move your integration tests there. Rename them to match the Surefire default pattern, like SomethingIntegrationTest. That will enable Surefire to pick them up without any extra configuration.

src/it/java/
`-- org
    `-- springframework
        `-- ldap
            `-- samples
                `-- article
                    `-- dao
                        |-- AbstractPersonDaoIntegrationTest.java
                        |-- PersonDaoImplIntegrationTest.java
                        `-- TraditionalPersonDaoImplIntegrationTest.java

The unit test source folder now looks like this:

src/test/java/
`-- org
    `-- springframework
        `-- ldap
            `-- samples
                `-- article
                    `-- domain
                        `-- PersonTest.java

Now add the following profile to your Maven pom:

 
<profiles>
<profile>
      <id>itcov</id>
      <build>
<plugins>
<plugin>
               <groupId>org.codehaus.mojo</groupId>
               <artifactId>build-helper-maven-plugin</artifactId>
               <version>1.1</version>
               <executions>
                  <execution>
                     <id>add-test-source</id>
<phase>generate-sources</phase>
                     <goals>
                        <goal>add-test-source</goal>
                     </goals>
                     <configuration>
                        <sources>
                          <source>src/it/java</source>
                        </sources>
                     </configuration>
                  </execution>
               </executions>
            </plugin>
         </plugins>
      </build>
   </profile>
</profiles>
 

Now we're ready to run coverage:

mvn cobertura:cobertura
...
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.springframework.ldap.samples.article.domain.PersonTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.048 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
...

Here we can see that only one test was run. The coverage report reveals that we only get coverage on the unit test of the Person domain object, giving us a total coverage of 7%:

We clean the target folder and run again, this time with the 'itcov' profile:

mvn clean
mvn cobertura:cobertura -Pitcov
...
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImplIntegrationTest
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.124 sec
Running org.springframework.ldap.samples.article.dao.PersonDaoImplIntegrationTest
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.12 sec
Running org.springframework.ldap.samples.article.domain.PersonTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.005 sec

Results :

Tests run: 9, Failures: 0, Errors: 0, Skipped: 0
...

This time we get both the unit tests and the integration tests, and the coverage report paints quite a different picture, with 75% coverage instead of 7%:

What we immediately see here is that we should focus our efforts on testing our web layer. But that's another story...

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="ldap://localhost:3901" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="secret" />
</bean>
 

In order to simplify deployment and maintenance, it's quite common to extract properties related to server names, ports, and user credentials from the Spring configuration file into a separate property file, like in this ldap.properties:

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=secret

In the configuration file, the previously hard-coded values are replaced with "property placeholders", ie variables enclosed with ${}:

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="${url}" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="${userDn}" />
<property name="password" value="${password}" />
</bean>
 

In order to perform the property value substitution in a transparent way, a PropertyPlaceholderConfigurer is configured:

 
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

Spring will pick up that one has been configured and run it before any beans are instantiated. It will read the property file and replace the placeholders with the actual values. Quite handy and very simple.

But what if your organization dislikes having sensitive information like passwords lying around in property files, in clear text? Let's say that your boss demands that all such passwords must be encrypted. Wouldn't it be great if the password then somehow could be automatically decrypted before being used? This can quite easily be achieved using the Jasypt library.

It's a two-step process. First we need to encrypt the password. Then we configure a different PropertyPlaceholderConfigurer that is capable of decrypting the property after it has been read.

Encrypting the password

The available encryption algorithms are currently limited to Password Based Encryptors (PBE). There are scripts for encrypting and decrypting in the Jasypt distribution. This is the procedure for encrypting a text (assuming the Jasypt library has been unpacked in JASYPT_HOME):

% cd $JASYPT_HOME/bin
% chmod +x *.sh
% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3

Let's verify that it can actually be decrypted:

% ./decrypt.sh input="p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Good. Note that the encryption is "salted", so you'll never get the same result twice. You'll always be able to decrypt it, though. Want to see? OK, one more time then:

% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq

% ./decrypt.sh input="Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Now, let's encrypt our password:

% ./encrypt.sh input="secret" password=MYPAS_WORD verbose=false
6mbJVZ6jozGYF1pjjqDQOQ==

We'll replace the password value in the properties file with the string above, surrounded by ENC():

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=ENC(6mbJVZ6jozGYF1pjjqDQOQ==)

Configure A Decrypting PropertyPlaceholderConfigurer

We'll simply replace our existing PropertyPlaceholderConfigurer with the Jasypt EncryptablePropertyPlaceholderConfigurer:

 
<bean class="org.jasypt.spring.properties.EncryptablePropertyPlaceholderConfigurer">
   <constructor-arg ref="configurationEncryptor" />
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

It delegates the actual decryption to a StringEncryptor implementation:

 
<bean id="configurationEncryptor" class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
<property name="config" ref="environmentVariablesConfiguration" />
</bean>
 

The encryptor in turn needs a configuration that provides information such as the algorithm to use and the encryption password. It delegates that responsibility to a PBEConfig implementation that expects the password to be available in an environment variable or a system property:

 
<bean id="environmentVariablesConfiguration"
      class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
<property name="algorithm" value="PBEWithMD5AndDES" />
<property name="passwordEnvName" value="APP_ENCRYPTION_PASSWORD" />
</bean>
 

Providing the encryption password as a system property is actually a good thing. A system property can be cleared just when the application has started, thereby minimizing considerably the time that the password is exposed.

Running The Application

It won't work with a Maven property:

% mvn test -DAPP_ENCRYPTION_PASSWORD=MYPAS_WORD
...
Tests run: 8, Failures: 0, Errors: 8, Skipped: 0
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] There are test failures.

Please refer to target/surefire-reports for the individual test results

We check the Surefire reports and find the cause of the error:

org.jasypt.exceptions.EncryptionInitializationException:
  Password not set for Password Based Encryptor

It does however work with an environment variable:

% export APP_ENCRYPTION_PASSWORD=MYPAS_WORD
% mvn test
...
Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
% unset APP_ENCRYPTION_PASSWORD

Issues With Java5

If we're on Java5 (or lower), we'll need ICU4J. Otherwise, we'll run into this:

org.jasypt.exceptions.EncryptionInitializationException:
  java.lang.NoClassDefFoundError: com/ibm/icu/text/Normalizer

There are two places where we'll need ICU4J: the command line tools and our Maven project.

ICU4J With The Command Line Tools

Reviewing the Jasypt scripts, we find that it's possible to customize the classpath:

export JASYPT_CLASSPATH=~/Downloads/icu4j-4_0.jar

ICU4J With Maven

Add this profile to the Maven pom.xml to get ICU4J in the classpath:

 
<profiles>
<profile>
      <id>jdk15</id>
      <activation>
         <jdk>1.5</jdk>
      </activation>
      <dependencies>
         <dependency>
            <groupId>com.ibm.icu</groupId>
            <artifactId>icu4j</artifactId>
            <version>3.8</version>
         </dependency>
      </dependencies>
   </profile>
</profiles>
 

Currently, the 4.0 version is not available in the central Maven repo, but 3.8 seems to work just fine.

Summary

Using Jasypt, it's actually quite easy to use encrypted values in your property files. In a Spring-based application, it's simply a question of replacing the existing PropertyPlaceholderConfigurer with the Jasypt encrypting equivalent, plus two more beans providing encryption and configuration. Choose how to provide the encryption password, and you're set to go.

If running on Java5 or lower, you'll also need to add ICU4J to your classpath, for the encryption scripts as well as your build and deployment environment.

References

• http://jasypt.org
• http://www.springframework.org
• http://icu-project.org/

On the Mac it was easy to get running (if you have MacPorts):

% sudo port install squid
% sudo squid -z (initialize stuff if you never ran Squid before)
% sudo squid -N -d 1 (no daemon, debug level 1)

Then it was running on the console, and you could test it like this:

% squidclient http://google.com
...
X-Cache: MISS from myhostname
Via: 1.0 myhostname:3128 (squid/2.7.STABLE2)

And again, this time fetching from the cache:

% squidclient http://google.com
...
X-Cache: HIT from myhostname
Via: 1.0 myhostname:3128 (squid/2.7.STABLE2)

You configure your browser by simply setting proxy server to localhost:3128, if you are running your Squid locally, that is.

Maven is probably best configured in ~/.m2/settings.xml:

<settings xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/xmlSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
    http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <proxies>
    <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>localhost</host>
      <port>3128</port>
    </proxy>
  </proxies>
</settings>

I used the Jungle Disk software to provide the mapping from the S3 web service interface to a network drive. You give Jungle Disk your S3 account information, and it provides a network disk which you can use as the backup device. I first tried my existing backup software (Synchronize! Pro X) and it happily began creating directories and copying files. I then tried the backup feature built into Jungle Disk, and it works fine too. It's not fast compared to a local FireWire disk. It's limited to your upload bandwidth, which often is substantially smaller than the download bandwidth.

Anyway, it has been tugging along today storing 5 GB of by digital photos. It feels pretty good to know that my photos are now stored encrypted and with 99.99% availability somewhere far far away, costing me only 75 cents per month after the initial $2 for the transfer.

Unexpected method call toString():
  toString(): expected: 0, actual: 1

You think nothing of it and happily add an expectation for toString. Then you get:

Unexpected method call toString():
  toString(): expected: 1, actual: 2

The reason is that EasyMock itself calls toString for each expectation, so it's a never-ending story. However, it appears only when your class under test has overridden any (or all) of toString, equals or hashCode. There is a way around it. You can tell EasyMock's MockClassControl which methods you want it to mock. Yes, you heard it right: "which methods you want it to mock". I know, you'd rather want to tell it which methods you don't want it to mock, like toString, equals and hashCode.

I'll show you a couple of utility classes that let you do that. We ran into this problem in a previous project and wrote the classes below. They let you get away with this neat code that should be used whenever you mock a class:

public class MyClassTest extends TestCase {
   private MockControl myClassControl;
   private MyClass myClassMock;
 
   public void setUp(){
      myClassControl = TestUtils.createClassControl(MyClass.class);
      myClassMock = (MyClass) myClassControl.getMock();
   }
   ...
}

Here are the classes:

package se.jayway.testutils; 
 
import org.easymock.MockControl; 
 
/**
 * Various utility functions for testing.
 *
 * @author Adam Skogman
 */
public final class TestUtils { 
 
    private TestUtils() {
        super();
    } 
 
    /**
     * Get a MockClassControl for the supplied class, using the first found
     * public or protected constructor and not mocking the toString(), equals()
     * and hashCode() methods.
     *
     * @param cls
     *            the class to create a MockClassControl for.
     * @return a MockClassControl for the class.
     * @see MockClassControlHelper
     */
    public static MockControl getMockClassControl(Class cls) {
        return getMockClassControl(
                cls,
                MockClassControlHelper.DONT_MOCK_STD_METHODS);
    } 
 
    /**
     * Get a MockClassControl for the supplied class, using the first found
     * public or protected constructor. If mockStdMethods is false, the
     * toString(), equals() and hashCode() methods will not be mocked.
     *
     * @param cls
     *            the class to create a MockClassControl for.
     * @param mockStdMethods
     *            whether toString(), equals() and hashCode() will be mocked.
     * @return a MockClassControl for the class.
     * @see MockClassControlHelper
     */
    public static MockControl getMockClassControl(
            Class cls,
            boolean mockStdMethods) {
        MockClassControlHelper helper = new MockClassControlHelper(
                mockStdMethods);
        return helper.getMockClassControl(cls);
    }
}

package se.jayway.testutils; 
 
import java.lang.reflect.Constructor;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashSet;
import java.util.Set; 
 
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.easymock.MockControl;
import org.easymock.classextension.MockClassControl; 
 
/**
 * Helper class to easily create mock class controls.
 *
 * EasyMockClassExtension v1.1 has a couple of undocumented 'features' which are
 * rather annoying.
 *
 * First of all, if the class we want to mock does not have any public
 * constructor, it is not possible to do
 * MockClassControl.createControl(MyClass.class), since the search for
 * constructors is limited to 'public' access modifier if class and parameter
 * values are not specified.
 *
 * Secondly, if toString(), equals() or hashCode() is overridden in the class we
 * want to mock, parameter matching on the resulting mock will not work, since
 * the above methods will be mocked by default, causing mock control validation
 * to fail.
 *
 * As a solution this helper class will by default instruct MockClassControl not
 * to mock toString(), equals() and hashCode() (alternatively any methods
 * specified by a call to setStdMethods()).
 *
 * Methods in Object will not be mocked.
 *
 * @author Mattias Arthursson
 */
public class MockClassControlHelper {
    Log log = LogFactory.getLog(MockClassControlHelper.class); 
 
    /**
     * Indicates that standard methods will be mocked.
     */
    public static final boolean MOCK_STD_METHODS = true; 
 
    /**
     * Indicates that standard methods will be mocked.
     */
    public static final boolean DONT_MOCK_STD_METHODS = false; 
 
    private boolean mockStdMethods; 
 
    private Collection stdMethods; 
 
    /**
     * Initialize to not mock standard methods.
     */
    public MockClassControlHelper() {
        this(DONT_MOCK_STD_METHODS);
    } 
 
    /**
     * Initialize to mock standard methods depending on supplied parameter.
     *
     * @param mockStdMethods
     *            whether standard methods should be mocked.
     */
    public MockClassControlHelper(boolean mockStdMethods) {
        this.mockStdMethods = mockStdMethods;
        stdMethods = Arrays.asList(new String[] { "toString", "equals",
                "hashCode" });
    } 
 
    /**
     * Get a MockClassControl for the supplied class using the first found
     * public or protected constructor. Standard methods will be mocked
     * depending on mockStdMethods.
     *
     * @param cls
     *            the class to mock.
     * @return a MockClassControl for the supplied class.
     */
    public MockControl getMockClassControl(Class cls) {
        Constructor constructorToUse = getConstructorToUse(cls); 
 
        Class[] parameters = constructorToUse.getParameterTypes();
        Object[] values = new Object[parameters.length]; 
 
        Method[] methodsToMock = getMethodsToMock(cls); 
 
        return MockClassControl.createControl(
                cls,
                parameters,
                values,
                methodsToMock);
    } 
 
    /**
     * Set the standard methods to omit if mockStdMethods is set to false
     * (default).
     *
     * @param methods
     *            Names of the methods to omit when mocking.
     */
    public void setStdMethods(String[] methods) {
        stdMethods = Arrays.asList(methods);
    } 
 
    /**
     * Set the standard methods to omit if mockStdMethods is set to false
     * (default).
     *
     * @param c
     *            Collection of names of the methods to omit when mocking.
     */
    public void setStdMethods(Collection c) {
        stdMethods = c;
    } 
 
    /**
     * Get the methods that will not be mocked.
     *
     * @return A collection of method names.
     */
    public Collection getStdMethods() {
        return stdMethods;
    } 
 
    /**
     * Find a constructor to use. If public constructors are found, the first of
     * these is selected. Otherwise we check for a protected constructor, and
     * the first of these is used.
     *
     * @param cls
     *            Class to select a constructor from.
     * @return a public or protected constructor for the class.
     */
    protected Constructor getConstructorToUse(Class cls) {
        Constructor[] constructors = cls.getConstructors();
        if (constructors.length == 0) {
            // No public constructors found.
            constructors = cls.getDeclaredConstructors();
            if (constructors.length == 0) {
                throw new IllegalArgumentException("Class '" + cls
                        + "' does not have any constructors");
            }
        } 
 
        for (int i = 0; i < constructors.length; i++) {
            int modifiers = constructors[i].getModifiers();
            if (Modifier.isPublic(modifiers) || Modifier.isProtected(modifiers)) { 
 
                // We've found a constructor which is public or
                // protected - use that one.
                return constructors[i];
            }
        } 
 
        // No public or protected constructor found.
        throw new IllegalArgumentException("Class '" + cls
                + "' does not have any public or protected constructors");
    } 
 
    /**
     * Figure out which methods of the class to mock. If mockStdMethods is set
     * to false, the standard methods are subtracted from all found methods for
     * the class. Otherwise all methods for the class is returned.
     *
     * @param cls
     *            The class to get methods for.
     * @return The methods to mock for the class.
     */
    protected Method[] getMethodsToMock(Class cls) { 
 
        Class currentClass = cls;
        Set methods = new HashSet(); 
 
        while (currentClass != null) {
            Method[] methodArray = currentClass.getDeclaredMethods(); 
 
            for (int i = 0; i < methodArray.length; i++) {
                Method method = methodArray[i];
                boolean isStandardMethod = stdMethods.contains(method
                        .getName());
                if (mockStdMethods || !isStandardMethod) {
                    methods.add(method);
                } 
 
                if ((method.getModifiers() & Modifier.FINAL) > 0) {
                    log.warn("Final method, cannot be mocked: " + method);
                }
            } 
 
            currentClass = currentClass.getSuperclass();
            if(currentClass == Object.class){
                currentClass = null;
            }
        } 
 
        return (Method[]) methods.toArray(new Method[methods.size()]);
    }
}

We turned to Ulrik Sandberg, one of the founders of the group.

Tell us how you got started with the Sweden Spring User Group.
The Sweden Spring User Group was started in early 2007. I had spoken to Rod Johnson at The Spring Experience 2006 about creating a user group for Swedish users, and he thought that was an excellent idea. We decided to use Google Groups as the tool for collabo- ration. Jayway would be our financial backup, since we wanted to provide the group members with first-class confer- ence facilities, as well as food and drink.

Which are your goals?
Our primary goal is to gather all Swedish Spring users in a community, in order to get a forum where you can ask questions and present ideas to peo- ple who share the interest for Spring. We also want to provide high-quality sessions when we meet. The sessions should be held by the community, but we also aim to get an external speaker from either Interface21 or other inter- esting companies related to Spring.

What have you been doing so far?
The first meeting was held in late March, in Stockholm. We managed to get Arjen Poutsma from Interface21 to hold a session about Duck Typing in the Spring WebServices framework. Before that, there had been an Introduction to Spring and a session about the Aspect- Oriented Programming (AOP) support in Spring 2.0. It was very crowded, and people really enjoyed the short break for beer and pizza.
The second meeting in early July was also in Stockholm. The main speaker at that event was Ben Alex from Inter- face21, the inventor of Spring Security, previously known as Acegi Security. He had come all the way from Australia and held a session about his Real Object- Oriented (ROO) framework. There was also a session about Spring JDBC and a very interesting case study about the use of Spring MVC at PriceRunner.
The third meeting took place in Malmö in late September. The guest of honor was Jonas Bonér from Terracotta. He talked about how easy it is to clus- ter Java applications using Terracotta. There was a session about Spring and Mule, as well as a session about Declara- tive Caching Using Spring.

So what is your final message to the readers?
In short, the Sweden Spring User Group arranges high-quality mini-con- ferences about Spring and related tech- nologies four times a year. For free. You should join us.

Ulrik Sandberg, Björn Granvik

Setup

Cable modem from ISP, network cable to a firewall, the private end of the firewall via network cable on to a switch. Pretty basic, I guess. No wireless base stations or anything. Just an iMac connected via network cable to the switch.

Problem

Share the iMac's network cable connection through its Airport wireless capability. The client is a MacBook Pro. Basically, I just want to get Internet access on my laptop via the iMac. Sounds simple, but hey, it took me half a day and plenty of research to figure out.

Useful pieces of information gathered during this adventure

1. Turning on Internet Connection Sharing (ICS) will start a DHCP server.
2. Turning on ICS will create a full Airport network (not a computer-to-computer network).
3. Turning on ICS will create a new network configuration for 10.0.2.1, which I understand is the same address as the Airport base stations use.

Solution

1. On the iMac, set the Airport network to "Use DHCP with manual address" and set the IP to 10.0.2.1. Set the DNS servers to the ones recommended by your ISP. Apply.
2. On the iMac, go to Sharing|Internet and choose AirPort Options. Enable WEP encryption (I chose 40-bit with a 5 character password). The default network name is your computer name. I added a postfix to the network name ("-ics") so I can distinguish it from the computer-to-computer network. Apply.
3. Now start sharing your Built-in Ethernet connection to computers using Airport. As I mentioned previously, this will create the new network and also start a DHCP server.
4. On the MacBook, set the Airport network to "Use DHCP". Leave all fields blank.
5. On the MacBook, connect to the newly created network, which should be named "hostname-ics" if you followed my naming advice earlier. Watch the network configuration. Eventually it shows the IP 10.0.2.2.

That's it. You should now have access to your other machines on your private network, but also to Internet.

I had seen somewhere that you could get the 403 error if you were using SSL (which I was) and the Sourceforge server svn.sourceforge.net. The correct server is the PROJECTNAME.svn.sourceforge.net, where PROJECTNAME in my case was springframework. So the correct URL to use is https://springframework.svn.sourceforge.net/svnroot/springframework/. This meant changing the checkout URL, which Subversion can do on an already checked-out working copy, using the switch command. Cool. When I tried this, it failed because it couldn't find the new server. The problem was that the DNS servers I was using at some point didn't find this server, and probably cached this negative hit. Eventually I found a DNS that could locate this server and performed the switch. Things have been working much better since.

Using the incorrect server, which most likely is a proxy server of some sort, could possibly have resulted in different physical servers being used for different requests during the Subversion transaction. It's not allowed to perform a svn copy operation between repositories. You'll get a 403 if you try it. Perhaps that rule applied to my situation as well.

Note that although this follows the Internet standard for email addresses (RFC 822), some sites simply ignore this and incorrectly disallows addresses with plus signs.

Read more here. More cool mail tips can be found here.

Entering [org.springframework.ldap.LdapTemplateListTest.]
Exiting [org.springframework.ldap.LdapTemplateListTest.]
Entering [org.springframework.ldap.LdapTemplateListTest.setUp]
  Entering [org.springframework.ldap.LdapTemplate.]
    Entering [org.springframework.ldap.DefaultNamingExceptionTranslator.]
    Exiting [org.springframework.ldap.DefaultNamingExceptionTranslator.]
  Exiting [org.springframework.ldap.LdapTemplate.]
  Entering [org.springframework.ldap.LdapTemplate.setExceptionTranslator]
  Exiting [org.springframework.ldap.LdapTemplate.setExceptionTranslator]
Exiting [org.springframework.ldap.LdapTemplateListTest.setUp]
Entering [org.springframework.ldap.LdapTemplateListTest.testList_Name]
  Entering [org.springframework.ldap.LdapTemplateListTest.expectGetReadOnlyContext]
  ...

The part that keeps track of the indentation level was written as a reusable aspect:

package org.springframework.ldap.aspects; 
 
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.aspectj.lang.JoinPoint; 
 
/**
 * Abstract logging aspect for producing indented logging. Override the
 * <code>loggingOperations</code> pointcut in order to provide the joinpoints
 * where you would like the logging to be applied. Also override the methods
 * <code>beforeLog</code> and <code>afterLog</code> to provide the actual
 * logging statements. The current indentation string will be provided to these
 * methods, along with an instance of <code>JoinPoint</code>.
 *
 * @author Ulrik Sandberg
 */
public abstract aspect IndentedLogging {
    Log log = LogFactory.getLog("trace"); 
 
    /**
     * The current number of indentation levels.
     */
    protected int indentationlevel = 0; 
 
    /**
     * Override and provide pointcut to log.
     */
    protected abstract pointcut loggingOperations(); 
 
    /**
     * Override and provide the actual logging statement for when the logged
     * method is entered.
     *
     * @param indent
     *            The string of spaces that provides the current indentation.
     * @param joinPoint
     *            Information about the current joinpoint.
     */
    protected abstract void beforeLog(String indent, JoinPoint joinPoint); 
 
    /**
     * Override and provide the actual logging statement for when the logged
     * method is exited.
     *
     * @param indent
     *            The string of spaces that provides the current indentation.
     * @param joinPoint
     *            Information about the current joinpoint.
     */
    protected abstract void afterLog(String indent, JoinPoint joinPoint); 
 
    Object around(): loggingOperations() {
        StringBuffer sb = new StringBuffer();
        if (log.isInfoEnabled()) {
            indentationlevel++;
            for (int i = 0, spaces = indentationlevel * 2; i &lt; spaces; i++) {
                sb.append(" ");
            }
            beforeLog(sb.toString(), thisJoinPoint);
        }
        Object result;
        try {
            result = proceed();
        } finally {
            if (log.isInfoEnabled()) {
                afterLog(sb.toString(), thisJoinPoint);
                indentationlevel--;
            }
        }
        return result;
    }
}

Since the reusable aspect does all the grunt work, the actual tracing aspect becomes rather small:

package org.springframework.ldap.aspects; 
 
import org.aspectj.lang.JoinPoint; 
 
public aspect TraceAspect extends IndentedLogging {
    declare precedence: TraceAspect, *; 
 
    protected pointcut loggingOperations():
        (execution(* *.*(..)) || execution(*.new(..)))
        && !within(IndentedLogging+); 
 
    protected void beforeLog(String indent, JoinPoint joinPoint) {
        log.info(indent + "Entering ["
                + joinPoint.getSignature().getDeclaringTypeName() + "."
                + joinPoint.getSignature().getName() + "]");
    } 
 
    protected void afterLog(String indent, JoinPoint joinPoint) {
        log.info(indent + "Exiting ["
                + joinPoint.getSignature().getDeclaringTypeName() + "."
                + joinPoint.getSignature().getName() + "]");
    }
}

Now, let's say we don't want to trace each and every method and constructor execution, but rather a small subset, like for example only the normal methods (no constructors) in any subclass of NameClassPairCallbackHandler. We'll remove the execution of new from the pointcut and add the handler subclass condition:

public aspect TraceAspect extends IndentedLogging {
    declare precedence: TraceAspect, *; 
 
    protected pointcut loggingOperations():
        execution(* *.*(..)) // just plain methods
        && !within(IndentedLogging+)
        && within(org.springframework.ldap.NameClassPairCallbackHandler+); // added
    ...

The output becomes:

Entering [org.springframework.ldap.CollectingNameClassPairCallbackHandler.handleNameClassPair]
  Entering [org.springframework.ldap.LdapTemplate$MappingCollectingNameClassPairCallbackHandler.getObjectFromNameClassPair]
  Exiting [org.springframework.ldap.LdapTemplate$MappingCollectingNameClassPairCallbackHandler.getObjectFromNameClassPair]
Exiting [org.springframework.ldap.CollectingNameClassPairCallbackHandler.handleNameClassPair]
Entering [org.springframework.ldap.CollectingNameClassPairCallbackHandler.getList]
Exiting [org.springframework.ldap.CollectingNameClassPairCallbackHandler.getList]

You might argue that it would be good to see the arguments to each call. That could easily be done by using JoinPoint.getArgs() in the tracing aspect. It would look like this:

package org.springframework.ldap.aspects; 
 
import org.aspectj.lang.JoinPoint; 
 
public aspect TraceAspect extends IndentedLogging {
    declare precedence: TraceAspect, *; 
 
    protected pointcut loggingOperations():
        (execution(* *.*(..)))
        && !within(IndentedLogging+)
        && within(*..NameClassPairCallbackHandler+); 
 
    protected void beforeLog(String indent, JoinPoint joinPoint) {
        log.info(indent + "Entering ["
                + joinPoint.getSignature().getDeclaringTypeName() + "."
                + joinPoint.getSignature().getName()
                + createParameterMessage(indent, joinPoint) + "]");
    } 
 
    protected void afterLog(String indent, JoinPoint joinPoint) {
        log.info(indent + "Exiting ["
                + joinPoint.getSignature().getDeclaringTypeName() + "."
                + joinPoint.getSignature().getName()
                + createParameterMessage(indent, joinPoint) + "]");
    } 
 
    private String createParameterMessage(String indent, JoinPoint joinPoint) {
        StringBuffer sb = new StringBuffer("(");
        Object[] args = joinPoint.getArgs();
        if (args.length > 0) {
            sb.append("\n    " + indent);
        }
        for (int i = 0; i < args.length; i++) {
            sb.append(args[i]);
            if (i != args.length - 1) {
                sb.append(',');
            }
        }
        sb.append(")");
        return sb.toString();
    }
}

And the output would be this:

Entering [org.springframework.ldap.CollectingNameClassPairCallbackHandler.handleNameClassPair(
    o=example.com: com.example.SomeClass)]
  Entering [org.springframework.ldap.LdapTemplate$MappingCollectingNameClassPairCallbackHandler.getObjectFromNameClassPair(
      o=example.com: com.example.SomeClass)]
  Exiting [org.springframework.ldap.LdapTemplate$MappingCollectingNameClassPairCallbackHandler.getObjectFromNameClassPair(
      o=example.com: com.example.SomeClass)]
Exiting [org.springframework.ldap.CollectingNameClassPairCallbackHandler.handleNameClassPair(
    o=example.com: com.example.SomeClass)]
Entering [org.springframework.ldap.CollectingNameClassPairCallbackHandler.getList()]
Exiting [org.springframework.ldap.CollectingNameClassPairCallbackHandler.getList()]

How bad are Date and Calendar?

Consider java.util.Date. It has been around since JDK 1.0, and it's actually not a date, but a date and a time. In order to get the date (and the time), you call the getTime() method. It uses two-digit years from 1900, day-of-month is one-based, while month and hours are zero-based, it should have been immutable, and most methods have been deprecated in JDK 1.1. Since it's not final, it's possible to hack it by overriding critical methods, like for example after.

The state of java.util.Calendar is not much better. Month is zero-based, it should have been immutable, and it allows only one hour offset for daylight savings time. Some years have more, you know. British timezone in 1943, 1944 and 1945, for example, had two hours. The worst part is that it uses two different representations internally: a value for each field, and milliseconds since 1970. The scary part is that these two representations are not continuously kept in synch. Instead they are resynched as a side effect of other method calls, like equals for example. Wouldn't that be something? You call equals on your Calendar and suddenly it changes to a different date.

Then we have java.util.SimpleDateFormat. It requires a Date object, it's not very fast, and it's not thread-safe. If concurrent threads call its format method on a shared instance, it can produce bizarre results.

They can't be that bad, can they?

Let's print out a date. We want July 2, 1945 and the time should be 12.30 PM. Here we go:

 
Date date = new Date(1945, 7, 2, 12, 30, 0);
System.out.println(date.toString());
 
// Sat Aug 02 12:30:00 CEST 3845
 

Oops. Forgot the two-digit year and the zero-based month. Let's try again:

 
int year = 1945 - 1900;
int month = 7 - 1;
Date date = new Date(year, month, 2, 12, 30, 0);
System.out.println(date.toString());
 
// Mon Jul 02 12:30:00 CEST 1945
 

Yes, I know that the constructor used above is deprecated. This is how it really should be done:

 
TimeZone tz = TimeZone.getTimeZone("Asia/Tokyo");
Calendar cal = Calendar.getInstance(tz);
cal.set(1945, Calendar.JULY, 2, 12, 30, 0);
DateFormat f= new SimpleDateFormat("yyyy-MM-dd hh:mm");
System.out.println(f.format(cal));
 
// java.lang.IllegalArgumentException: Cannot format given Object as a Date
// at java.text.DateFormat.format(DateFormat.java:279)
// at java.text.Format.format(Format.java:133)
 

Oops. DateFormat cannot take a Calendar. Let's try with a Date:

 
TimeZone tz = TimeZone.getTimeZone("Asia/Tokyo");
Calendar cal = Calendar.getInstance(tz);
cal.set(1945, Calendar.JULY, 2, 12, 30, 0);
DateFormat f= new SimpleDateFormat("yyyy-MM-dd hh:mm");
Date date = cal.getTime();
System.out.println(f.format(date));
 
// 1945-07-02 06:30
 

Well, almost right. I asked for the time to be 12.30, not 6.30. Ah, of course. It's not enough to set the timezone on the Calendar that we used to get the Date that we want to print. The DateFormat that prints the Date also needs the timezone. Silly me.

 
TimeZone tz = TimeZone.getTimeZone("Asia/Tokyo");
Calendar cal = Calendar.getInstance(tz);
cal.set(1945, Calendar.JULY, 2, 12, 30, 0);
DateFormat f= new SimpleDateFormat("yyyy-MM-dd hh:mm");
f.setTimeZone(cal.getTimeZone());
Date date = cal.getTime();
System.out.println(f.format(date));
 
// 1945-07-02 12:30
 

Finally.

The Contender: Joda-Time

There is a candidate that has all the characteristics we mentioned earlier, and more: Joda-Time. It's a single jar of 518k with no other dependencies. It replaces Date, Calendar and TimeZone. It has interfaces for datetimes, intervals and durations. The key classes are immutable. It has a pluggable calendar system where the default is ISO8601. And one more thing: it's easy to use.

DateTime

The most useful class in Joda-Time is the DateTime, which is immutable and thread-safe. It is measured in milliseconds since 1970, and it has simple getters for all fields. It supports timezones and multiple calendar systems. Its main purpose is to fill the most common needs as simple as possible:

 
DateTime now = new DateTime();
 
int y = now.getYear();
int hour = now.getHourOfDay();
int sec = now.getSecondOfMinute();
 
boolean leap = now.year().isLeap();
int daysInMonth = now.dayOfMonth().getMaximumValue();
 

Since it's immutable, all mutating methods return new objects:

 
DateTime now = new DateTime();
DateTime yesterday = now.minusDays(1).plusHours(3);
 

Partial

Partially defined datetimes have no timezone; they use local time. They are called "partial" because they don't have all the fields of a DateTime. We have YearMonthDay, TimeOfDay (hour, minute, second, and millisecond), and Partial (can store any fields). They can easily be converted to DateTime:

 
YearMonthDay ymd = new YearMonthDay(2005, 9, 20); // September 20, 2005
TimeOfDay tod = new TimeOfDay(14, 15);
 
DateTimeZone zone = DateTimeZone.forID("Asia/Tokyo");
DateTime dt = ymd.toDateTimeAtCurrentTime(zone);
DateTime dt2 = ymd.toDateTime(tod);
 

Period

A Period represents a period of time, like "5 years, 3 months, 2 days and 12 hours":

 
Period period = new Period(5, 3, 0, 2, 12, 0, 0, 0);
int years = period.getYears();
int days = period.getDays();
 

Interval

The class Interval represents an interval of time, represented by a start DateTime (included) and an end DateTime (excluded). Let's say we want to know how many complete weeks an interval is. To do that, we convert the Interval to a Period of the specific type we want. Using PeriodType, we can deduce that the interval below is 9 complete weeks (P9W is ISO8601-standard for a 9 week period):

 
DateMidnight start = new DateMidnight(2005, 7, 12); // July 12, 2005
DateMidnight end = new DateMidnight(2005, 9, 15); // September 15, 2005
Interval interval = new Interval(start, end);
Period period = interval.toPeriod(PeriodType.weeks());
System.out.println(period);
 
// P9W
 

Chronology

Joda-Time features a pluggable calendar system based on the Chronology class. There are for example ISO9601, Gregorian, Julian, GJ, Buddhist, Ethiopic, and Coptic. The default is ISOChronology. A Chronology can be passed in as extra parameter whenever needed, as in the following example where we print the year 2006 as the Buddhists see it:

 
Chronology buddhist = BuddhistChronology.getInstance();
DateTime now = new DateTime(buddhist);
int year = now.getYear(); // 2006
System.out.println(year);
 
// 2549
 

Time Zone

The DateTimeZone class encapsulates a time zone that contains not only the timezones in the current JDK implementations, but is also up to date with the most current time zone data available at the time zone database.

 
DateTimeZone.UTC;
DateTimeZone.forID("Asia/Tokyo");
DateTimeZone.forOffsetHours(6);
DateTimeZone.forTimeZone(TimeZone.getTimeZone("Europe/Stockholm"));
 

One problem with the JDK TimeZone is that it returns timezone UTC (also known as GMT) if the full name cannot be understood:

 
TimeZone validTz = TimeZone.getTimeZone("Asia/Tokyo");
System.out.println(validTz);
TimeZone invalidTz = TimeZone.getTimeZone("Asia/SomeUnknownCity");
System.out.println(invalidTz);
 
// sun.util.calendar.ZoneInfo[id="Asia/Tokyo",offset=32400000,dstSavings=0,useDaylight=false,...
// sun.util.calendar.ZoneInfo[id="GMT",offset=0,dstSavings=0,useDaylight=false,...
 

By contrast, Joda-Time's DateTimeZone throws an IllegalArgumentException if it cannot understand the time zone name:

 
DateTimeZone validTz = DateTimeZone.forID("Asia/Tokyo");
System.out.println(validTz);
DateTimeZone invalidTz = DateTimeZone.forID("Asia/SomeUnknownCity");
System.out.println(invalidTz);
 
// Asia/Tokyo
// java.lang.IllegalArgumentException: The datetime zone id is not recognised: Asia/SomeUnknownCity
// at org.joda.time.DateTimeZone.forID(DateTimeZone.java:198)
 

Interoperability

One of our requirements for a new framework was that it should be easy to convert to and from the standard classes. Constructors in Joda-Time take Date, Calendar, String, and long. From DateTime we can easily get JDK Date and Calendar. The DateTimeZone class can be constructed from a TimeZone and also return a TimeZone. In the example below, we easily convert from a standard Date to Joda-Time's DateTime to a GregorianCalendar, and from the DateTime back to a Date:

 
Date date = new Date(106, 8, 19); // Sep 19, 2006
DateTime dt = new DateTime(date);
GregorianCalendar c = dt.toGregorianCalendar();
Date d = dt.toDate();
 

Formatting

What about formatting then? Compared to SimpleDateFormat, the DateTimeFormatter is fast, flexible, thread-safe, and immutable. Formatting can be done in several ways: using a pattern, a style, or a format builder. You can either pass a formatter to the toString method for DateTime, or you can ask the formatter to print the DateTime:

 
DateTimeFormatter f = DateTimeFormat.longDateTime();
DateTime dateTime = new DateTime();
System.out.println(dateTime.toString(f));
System.out.println(f.print(dateTime));
 
// May 25, 2006 9:45:09 PM CEST
// May 25, 2006 9:45:09 PM CEST
 

DateTimeUtils

If you need to stop time, or go back or forward in time, you can use the DateTimeUtils class. This code shows that it's possible to stop time:

 
DateTime now = new DateTime();
DateTimeUtils.setCurrentMillisFixed(now.getMillis()); // time has stopped!
System.out.println(new DateTime());
Thread.sleep(2000);
System.out.println(new DateTime());
 
// 2006-05-25T23:21:37.562+02:00
// 2006-05-25T23:21:37.562+02:00
 

Turning back the clock is also possible:

 
DateTime now = new DateTime();
Period period = Period.months(-1);
Duration dur = period.toDurationFrom(now);
DateTimeUtils.setCurrentMillisOffset(dur.getMillis()); // we've gone back in time!
System.out.println(new DateTime());
 
// 2006-04-25T23:24:03.796+02:00
 

Don't forget to reset to system time:

 
DateTimeUtils.setCurrentMillisSystem(); // we're back to normal
System.out.println(new DateTime());
 
// 2006-05-25T23:29:41.281+02:00
 

Where were we?

Oh, yes. Printing dates. Let's print out the same date using Joda-Time. It was 12.30 PM on July 2, 1945:

 
DateTime date = new DateTime(1945, 7, 2, 12, 30, 0, 0);
DateTimeFormatter formatter = DateTimeFormat.forPattern("yyyy-MM-dd HH:mm");
System.out.println(date.toString(formatter));
 
// 1945-07-02 12:30
 

Couldn't be simpler.

Conclusion

The existing classes for date and time have drawbacks, some of them serious. The contender is Joda-Time, which is a complete rewrite and represents a mature API with a strong focus on usability, interoperability, stability and performance. What are you waiting for? Now is the time.

Update: It seems Java7 will be using JSR310, which basically is Joda-Time.

 
for (Iterator companies =
      database.getCompanies().iterator();
      companies.hasNext();) { 
 
   Company company = (Company)companies.next(); 
 
   if (company.getLocation().equals("CA")) { 
 
      for (Iterator departments =
            company.getDepartments().iterator();
            departments.hasNext(); ) { 
 
         Department department = (Department)departments.next(); 
 
         if (department.getEmployees().size() > 10) {
            System.out.println(department);
         }
      }
   }
}
 

Using JXPath you can simplify this:

 
// only needed once
JXPathContext context = JXPathContext.newContext(database); 
 
Iterator departments = context.iterate(
      "/companies[location='CA']" +
      "/departments[count(employees) > 10]");
while (departments.hasNext()) {
   System.out.println(departments.next());
}
 

Two points should be noted from this example:

• The code using JXPath is considerably shorter. The query is concisely expressed in one statement.
• You can take that expression out of the code and parameterize it, or put it in a configuration file.

Perfect for Unit Testing

Unit testing often requires checking object hierarchies for particular values. You can use JXPath to express the components to be tested. For example, you can write a helper method in a JUnit test:

 
/**
 * tests using a JXPath to express the required
 * component to test against. Note that nulls
 * aren't catered for!
 * @param path the path to find the object to
 *        test against
 * @param testable the base object to test
 * @param required the required result
 */
private void assertFromPath(String path,
                            Object testable,
                            Object required) { 
 
   JXPathContext context = JXPathContext.newContext(testable);
   assertTrue(required.equals(context.getValue(path)));
}
 

and then you can use this in tests:

 
public void testBankAccount() { 
 
   // you get a bank account object from some operation...
   Account account = .... 
 
   // then test against it
   assertFromPath("/accountHolder/name", account, "John Smith");
   assertFromPath("/accountHolder/opened", account, DATE_OPENED);
   assertFromPath("/accountHolder" + "/transactions[1]/amount",
         account, INITIAL_PAYMENT);
}
 

Read more in this java.net article.