Java and Immutability: Creating a Simple Builder

The more I look back on what I learned about programming in school (junior high, high school, college, etc.) I realize that although it made a great base on which to learn, it really does not get you ready for problems you’re going to see in the real world.  Of course, even then the problems are always changing and what you thought was the best approach a year ago, a month ago, or even within the last hour, isn’t.

One of the largest hurdles to jump over (besides recursiveness), in my opinion, is mutable versus immutable.  The main reason is because you’re taught from the time you start programming through college (ignoring those of you who took a Haskell class) you’re only taught using C, C++, or Java.  All languages that are mutable state programming languages (yes, you can apply immutability to them and I’m getting to that) and although (perhaps) easier to learn can lead to some hard problems down the line when you have to start thinking about scalability and parallelism.  Josh Bloch, of Effective Java fame, has said that unless you have a really good reason to make a mutable class, you shouldn’t.  And if you have to make a mutable class, limit the scope of it’s mutability.

Now, as the title of the post implies, I’m going to talk about how to make immutable objects in Java and touch on some of the issues that you might run into along with how to make a builder class to instantiate this new immutable object.  There are a few conventions that you apply to an object that will normally make it immutable with a few small exceptions.

  • make the class final
  • make all fields final and private
  • if a field is mutable make a defensive copy on a get
  • only set the fields in the constructor
  • do not allow setter methods

Now, these steps will get you there but, there are a few gotchas that people normally don’t think about.  For instance, most classes with the Iterable interface or an interface that allows removal from a set or list even if it is defined as final in the class if you pass it out to the caller using this pattern:

public Iterable<SomeType> getSomething() {
  return this.myIterableSomething;
}

are in for a big surprise (unless you’re using an immutable list) because the caller can then use the remove() method on that Iterable list that you returned.

Now that you’ve got this wonderful (and hopefully) immutable class, another awesome thing you can do is make a builder class to help construct the object.  This is especially helpful if your class takes a large number of inputs into the constructor.  There are many ways to make builder classes but I’m going to demonstrate my favorite one: a static class inside of the class you want to create.

Creating the builder is really very simple.  First, have a class you want to make a builder for, in this case, let’s use SimpleClass.

final public class SimpleClass {
  private final int a;
  private final int b;

  public SimpleClass(int a, int b) {
    this.a = a;
    this.b = b;
  }

  public int getA() { return this.a; }
  public int getB() { return this.b; }
}

Now, lets create the builder class inside of the SimpleClass, like this:

final public class SimpleClass {
  .. snip ..

  public static class Builder {
    private int a;
    private int b;

    public Builder() {
      //assign some default values...
      this.a = 0;
      this.b = 0;
    }

    public Builder setA(int a) { 
      this.a = a;
      return this;
    }

    public Builder setB(int b) {
      this.b = b;
      return this;
    }

    public SimpleClass build() { return new SimpleClass(this.a, this.b); }
  }
}

With this, we now have a very barebones builder class for SimpleClass.  In practice you’d take values that absolutely have to be set in the builder’s constructor and set reasonable defaults for the optional values.  You’d then use the set* methods to set the optional values for the class.  Additionally, if you only want the user to construct objects through the builder class you can set the constructor on the class to private, leaving you with a SimpleClass listing:

final public class SimpleClass {
  private final int a;
  private final int b;

  private SimpleClass(int a, int b) {
    this.a = a;
    this.b = b;
  }

  public int getA() { return this.a; }
  public int getB() { return this.b; }

  public static class Builder {
    private int a;
    private int b;

    public Builder() {
      //assign some default values...
      this.a = 0;
      this.b = 0;
    }

    public Builder setA(int a) { 
      this.a = a;
      return this;
    }

    public Builder setB(int b) {
      this.b = b;
      return this;
    }

    public SimpleClass build() { return new SimpleClass(this.a, this.b); }
  }
}

To actually instantiate this class in practice you’d make a call like this in your code:

  SimpleClass mySimpleClass = new SimpleClass.Builder().setA(10).setB(11).build();

And, whala! You’ve created an immutable class using a builder!

With this, you’ve taken the first step toward better coding in the real world and on problems that have you dealing with scale and parallelism.  I’ll hopefully write about scale and parallelism in later posts, so stay tuned, and if you have anything you think I should write about or a place where I’ve screwed up, let me know in the comments below! 🙂

If you’d like this source code in a nice form, check it out on GitHub.

JewelCLI: a simple CLI interface for Java

I’ve been working on a command-line interface for my PhD work and was initially doing the parsing of arguments by hand which was becoming extremely unwieldy so I decided it was time to jump into the OpenSource waters and see what was available.  I took a look at many CLI libraries (you can see a whole list of them here from JOpt) but settled on JewelCLI due to it’s simple, powerful interace and ease of use.  It might not be as powerful as Apache’s Commons CLI or CLI2 but it fit my needs perfectly.

Not to steal any thunder from it’s website, but as a quick example, all you have to do to use it (other than managing the dependency through Maven or whatever your tool of choice maybe) is three steps.

First, create an interface class.

public interface MyInterface {
  public String getFilename();
}

Second, annotate that interface class with the JewelCLI annotations.

public interface MyInterface {
  @Option
  public String getFilename();
}

Third, use JewelCLI’s factory methods to parse the command line arguments.

...
try {
  MyInterface myInterface = CliFactory.parseArguments(MyInterface.class, argsFromMain);
  String filename = myInterface.getFilename();
  ...
} catch (ArgumentValidationException e) {
  System.out.println(e.getMessage());
}

As a bonus, it even creates it’s own help output from the annotations so you don’t even have to write that (it appears as the message to the exception)!  Overall, I’m quite impressed with JewelCLI; it takes care of the mundane and lets me focus on what is important in my programming.

Java Security: The Finalizer Attack

Anyone who is familiar with Java (or other object-oriented) programming has more than likely heard of the SOLID development principles and knows that the O is for ‘Open / Closed Principle.’  In Java the use of the final keyword helps enforce the principle and a second programming ideal discussed in Bloch’s Effective Java book: composition over inheritance.  These two principles most developers should be able to rattle off fairly quickly, however there is a third aspect that the final keyword assists with that not many developers think about.

That is, the final keyword provides is prevention of the finalizer attack.  In short, the finalizer attack is a technique to take over a class through the use of the class’ finalizer method.  Using the final keyword on your class (or the finalize method) prevents classes from injecting malicious code or short-circuiting security routines.

As a note, if you’d like to see more about various secure coding techniques you can read through them here.

Stupid Java Trick: Rethinking how to handle creating the comma-separated list

Everyone knows the simple problem of outputting a comma-separated list.  It’s an easy problem to solve and it’s normally done like this:

int[] ints = {1, 2, 3, 4, ...};
StringBuilder sb = new StringBuilder();
for (int i = 0; i < ints.length; i++) {
   sb.append(ints[i]);
   if (i+1 != ints.length) {
     sb.append(",");
   }
 }
System.out.println(sb.toString());

 

And the code will return the following output:

1,2,3,4,....

 

Which is all well and good, however, you normally don’t deal with simple arrays or Lists most of the time, you have to deal with Iterable or you’re using Java’s enhanced for loop.  Neither of these has a way to easily notify the programmer that you’re at the last item in the Iterable.  So how do you take care of this?  Simple, insert the comma before outputting the value.

int[] ints = {1, 2, 3, 4, ...};
StringBuilder sb = new StringBuilder();
for (int i : ints) {
  if (sb.length() != 0) { 
    sb.append(",");
  }
  sb.append(i);
}
System.out.println(sb.toString());

 

And the code returns the exact same output as above.

Nifty little change and you can use with any class that implements the Iterable interface.

Mocks, Fakes, and Stubs. What are they and when do I use them?

I know there has been tons of things already written about mock, fakes, and stubs available all over the Internet, but I’ve decided to add to that glut and give my spin on these wonderful testing ideas.  The first questions are: why should I care what the difference between the three is and how do I use them?  Well, I’m glad you asked those questions because, it’s really quite simple.  You use mocks, fakes, and stubs during unit testing such that you can test a small section of code in a safe manner without requiring the entire system to be instantiated to run the test.  Depending on how and what you are going to test determines which of the three methodologies you’ll use.

Now, this is all well and good, but let’s define the three methodologies.  I tend to feel Martin Fowler gives the definitions that I agree with the most, so I’ll use those:

Mock objects pre-programmed with expectations which form a specification of the calls they are expected to receive.

Fake objects actually have working implementations, but usually take some shortcut which makes them not suitable for production.

Stub objects provide canned answers to calls made during the test, usually not responding at all to anything outside what’s programmed in for the test. Stubs may also record information about calls, such as an email gateway stub that remembers the messages it ‘sent’, or maybe only how many messages it ‘sent’.

I have a large preference for using fakes and stubs.  I’m not a huge fan of mocks since sometimes the coding gymnastics you do to get the mock behaving like you want, writing a fake could be written.  Also, mocks point to the fact, that you probably should have written an interface and implemented that instead of a single concrete implementation.  However, since I’m talking about all three of them, here are some examples on how I use each of them (and I can start with my least favorite one to get it out of the way).

Mock objects are best used when the the code being tested uses a library not under your control and you need to test very specific actions on the library.  For instance, you’ve written a wrapper to a database connector and you want to test to make sure that data read from the database is converted correctly.  In this case, I’d use a mock library (like Mockito in Java) to mock the calls to the database for the test harness.

Fakes, which are my favorite testing helper, can take the most work to get running, but they are far more flexible in my opinion once they are completed.  As described before, a fake is a working implementation of an interface that takes shortcuts in it’s implementation such that it behaves as the full implementation acts but without the overhead.  I find them most useful when testing database interactions with higher level code.  A good example of this is business logic in a server.  There is no reason to instantiate all the database layers in order to test the business logic.  It’s much easier to provide a fake implementation of the interface to the database and let the business logic do it’s thing.  In addition, these fake implementation can be used throughout your codebase anytime a database connection is needed.

Finally, there are stub objects.  Stub objects are meant to be used when only a small piece of functionality is used from a collaborating class within the codebase.  For instance, if there is a larger class being used, but only two simple methods are being used — a stub is more than likely a great choice.  Stub objects are often implemented as private inner classes to the test class such that all relevant code is kept close.    This old Spring Source blog article does a pretty good job of describing the difference between Mocks and Stubs.

In conclusion, these are three basic unit testing techniques and a quick overview of when to use each of them.  Personally, I find fakes to be the most helpful and reusable and mocks to be the least effective; however, different strokes for different folks (and codebases).  The bottom line is pick the best approach for the codebase and job at hand and test that code!

Java, what I’d like to see in a future version

Almost all of my coding for work is done in Java; so I stick pretty close to that all the time (although it isn’t to say I don’t dislike coding some C and C++ every once-in-a-while :).  However, it does limit the amount of time I have to look at other languages and the large amount of alternative JVM languages such as Scala, Fantom, and a large amount of other ones I can’t recall.

The thing about all these alternative languages is they work on solving problems where Java has just fallen down on the job trying to solve.  Two things that were shown to me by a co-worker who has been playing with Fantom really were great ideas and seem like they’d be easy to pull into Java.  They were fully immutable classes and variables specified by the const keyword (in Fantom) and the ability to specify if a class could be null when used as a method parameter.

At first, I wasn’t too sold on them being special since I have no problem writing code that is immutable by the fact that I can write it as such in Java (preventing setters, providing builders, etc) and then nullability issues can just be taken care of by defensive coding on inputs into the system.  Of course, I was thinking about this just from my perspective.  I don’t need these features.. but when you’re working on a team — these features make a lot of sense.  Not everyone programs on the same level.  There is always some variability on how good people are at things.  This is where these features are really nice.

If you don’t want someone to modify the class or variables inside of a class, that const keyword takes care of it.  It guarantees that the values of the class and the variable cannot be changed.  Hence, it gives you guaranteed immutability which is a very nice thing when doing concurrent programming.  The second point, on having the compiler catch parameters that can be null or not was initially in C# but brought into Fantom would hopefully stop all these NullPointerExceptions from being thrown (of course, it still can’t stop you from sending in something as null — but at least it’ll stop someone from doing it programmatically).

Now, I don’t see myself programming in Fantom professionally (but you never know, it could change) but I think all these alternative JVM languages have a lot of good ideas that should be pulled into the Java Language Specification or through JSRs, helping make Java a stronger, more robust language.