A short story about refactoring of a simple utility method - from boolean parameters to the fluent interface. All in the name of making the API perfect. :)

The Original Function

Once upon a time there was this method in TestUtils class (Javadocs omitted but we really had one!):

public static String createTemporaryNonWritableDir(String dirName)
            throws IOException {
    String destDir = TMP_DIR + FILE_SEPARATOR + dirName;
    File nonWritableDir = new File(destDir);
    // remove it if existed (this happens in /tmp so it is not cleaned by mvn clean)
    nonWritableDir.delete();

    // create and make NOT writable
    nonWritableDir.createNewFile();
    nonWritableDir.setWritable(false);
    return destDir;
}

The function worked fine, and you used it like this:

String destDir = TestUtils.createTemporaryNonWritableDir("non_writable_dir");

All Your Booleans Are Belong To Us!

Today when I came to work I noticed the function has evolved into this:

public static String createTemporaryDir
        (String dirName, boolean readable, boolean writable) throws IOException {
    String destDir = TMP_DIR + FILE_SEPARATOR + dirName;
    File directory = new File(destDir);
    // remove it if existed (this happens in /tmp so it is not cleaned by mvn clean)
    directory.delete();

    // create
    directory.createNewFile();
    // and make it NON readable if flag set
    directory.setReadable(readable);
    // and make it NON writable if flag set
    directory.setWritable(writable);
    return destDir;
}

I have to say I do not like this version. When using it, it is not clear what kind of directory will be created (which boolean relates to writing permission?)

String destDir = TestUtils.createTemporaryDir("non_writable_dir", true, false);

You will find much more about writing good tests in my book
"Practical Unit Testing
with TestNG and Mockito"

P.S. An additional downside was, that the original Javadoc was left as it was... eh.... as we all know: "documentation lies, tests never do" :)

Fluent Interface

I was thinking if I could improve this. An obvious way would be to create multiple methods like:

createTemporaryNonReadableDir(String dirName);
createTemporaryNonWritableDir(String dirName);
createTemporaryNonReadableNonWritableDir(String dirName);

but this would bloat the API, which I do not like.

So I gave it another try by using the builder pattern, like this:

public class TmpDirBuilder {

    private String dirName;
    private boolean readable = true;
    private boolean writable = true;

    public TmpDirBuilder withDirName(String dirName) {
        this.dirName = dirName;
        return this;
    }

    public TmpDirBuilder notReadable() {
        this.readable = false;
        return this;
    }

    public TmpDirBuilder notWritable() {
        this.writable = false;
        return this;
    }

    public String create() throws IOException {
        String destDir = TMP_DIR + FILE_SEPARATOR + dirName;
        File directory = new File(destDir);
        // remove it if existed (this happens in /tmp so it is not cleaned by mvn clean)
        directory.delete();
        // now create and set flags
        directory.createNewFile();
        directory.setReadable(readable);
        directory.setWritable(writable);
        return destDir;
    }
}

You can use it now like this:

String destDir = new TmpDirBuilder()
   .withDirName("non_writable_dir").notWritable().create();

Of course other combinations are also possible (e.g. notWritable().notReadable() etc.), and if one day we want to enhance this functionality with new features, it will be still possible.

The Question

So the question is if I improved the code or made it worse? What do you think?

Resources

Below few links to get you started with DSLs:

• http://www.infoq.com/articles/internal-dsls-java - a great introduction by Alex Ruiz (author of FEST Fluent Assertions http://fest.easytesting.org/) and Jeff Bay
• http://martinfowler.com/bliki/FluentInterface.html and http://martinfowler.com/bliki/DomainSpecificLanguage.html by Martin Fowler (not much about Java, but this is a must-read)
• http://code.google.com/p/make-it-easy/ an utility library which helps to use Test Data Builder pattern

BTW. Damn it, I have to spent additional 20 minutes at work now that have written this post! :) lol