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.