Proxies love the Void.class

You probably have asked yourself quite a long time: “What’s the class Void for?”, since you can’t create any object of it. You might be tempted to say that it’s just a placeholder to indicate that a generic method returns nothing, but it may serve you well beyond that, because these methods actually return something. As strange as it sounds they return something that is meant to be nothing: null.
In my previous blog “Reflection without Strings” I have constructed a “MethodFinder” class that enables you to get method objects from any interface without referencing the methods by its name. So you’d have a refactoring-proof way to use reflection on interfaces. The trick was to create a dynamic proxy for the interface, which will remember the last method call that it got, call it and then ask it what it has remembered. You could then pass the method object on to any object that can deal with it.
With some little syntax-trickery and a static import it was possible to get a nice and concise syntax that made it look like this:

import static de.plush.brix.tools.reflection.MethodFinder.*;
//…
 final Method getter = method(call(IArticle.class).getPrice());

The method “call(IArticle.class)” will return a proxy implementing the “IArticle” interface, this is where you call “getPrice()” on. Now the MethodFinder class will remember (per thread), the method you have just called and return the default for the method’s return type, which is either null, 0, (byte)0, (short)0, 0, 0L, 0d or 0f. That useless result of the proxy call becomes the parameter of the “MethodFinder.method(Object)” method and the parameter solely exists to make the expression a one-liner.
Mocking frameworks like Easymock work the same way. If you’re into unit tests, you might recognize this:

final IArticle mock = EasyMock.createMock(IArticle.class);
EasyMock.expect(mock.getPrice()).andReturn(testPrice).anyTimes();
//…
EasyMock.replay(mock);

Now the problem is, that for calling a setter, which is a void method, you cannot use the return value as parameter for “MethodFinder.method(Object)”, because void methods don’t return anything it won’t compile. So for void methods, the syntax looks like that:

import static de.plush.brix.tools.reflection.MethodFinder.*;
//…
 call(IArticle.class).setPrice(null);
 final Method setter = method();

At this point you should consider biting the bullet and refactoring your IArticle interface as follows:

public interface IArticle{
 Price getPrice();
 Void setPrice(final Price newPrice) ; //note the uppercase “V”
}

This will make a setter look like this:

public class Article implements IArticle{
 //…
 public Void setPrice(final Price newPrice) {
  price = newPrice;
  return null; //works, as “null” has no type
 };
}

As a result your reflection code can now look like this:

import static de.plush.brix.tools.reflection.MethodFinder.*;
//…
 final Method getter = method(call(IArticle.class).getPrice());
 final Method setter = method(call(IArticle.class).setPrice(null));
 final Binding<IArticle,Price> binding = new Binding<IArticle,Price>(getter, setter);
 binding.setModel(Article.none());
//..

The same happens with the EasyMock example:

final IArticle mock = EasyMock.createMock(IArticle.class);
EasyMock.expect(mock.setPrice(testPrice)).andReturn(null).anyTimes();
//…
EasyMock.replay(mock);

This looks a lot slicker, doesn’t it? The “return null” in Article.class sucks however, but since we’d probably like some event handling anyway, we can beef it up too. More on that follows.

Inline assignments beautify your setters

You have for sure seen something like this before, haven’t you?

public class Article implements IArticle{
 //…
 public Void setPrice(final Price newPrice) {
  final Price oldPrice = price;
  price = newPrice;
  firePropertyChange(“price“, oldPrice, newPrice);
  return null;
 };
}

This method stinks in many ways: The property key is referenced by a String, we have a temporary variable for the old price and just because of our neat “Void” type, we have a “return null” here. Don’t worry; Salvation is near. Let’s tackle one problem after the other.
First we kill the temporary variable with a simple inline-assignment, which is discouraged by some style guides and is hardly used elsewhere than in loops to read streams, but it serves very well in this case:

public class Article implements IArticle{
 //…
 public Void setPrice(final Price newPrice) {
  firePropertyChange(“price“, price, (price = newPrice));
  return null;
 };
}

To understand how this works is to understand how parameters are evaluated, which is from left to right: To call firePropertyChanged, the runtime must first push all 3 parameters on the Stack in order of appearance, which is the String “price”, the value of the price itself and finally the value of the bracketed statement. Now the statement in brackets not only results in the new price, it also assigns the new price to the price field.
Getting rid of the ugly “return null”, is as easy as it can get: Just change the “firePropertyChange” method to return the “Void” type instead of the “void” primitive and you can write it like that:

public class Article implements IArticle{
 //…
 public Void setPrice(final Price newPrice) {
  return firePropertyChange(“price“, price, (price = newPrice));
 };
}

Its seems a little bit awkward to return anything after firing a property change, but I can live with it, can you?
The last thing that looks so incoherent is that even though we’ve now managed to access the method without referencing it by its name, we identify the property by the name. And there’s really no way around throwing a string around, when you need to stay compatible with the existing property change mechanism of the java beans framework, which you should. But then again we can get the string automagically by assuming the convention “setX”, “addX” and “removeX” for modifier methods. We just ask the stack trace which method we’re in and analyse the string and I’m using a little utility for that to not repeat myself. Alas, working with the stack trace is a bit of a mess, because call depths matter and these may change when refactoring, but that’s where testing getters and setters with unit tests pays off.
I like to have some sweet little methods in a utility class to get me the current property name:

public static String propertyName(){
 final StackTraceElement x = Thread.currentThread().getStackTrace()[2];
 return extractPropertyName(x.getMethodName());
}
public static String propertyName(Method method){
 return extractPropertyName(method.getName());
}
private static String extractPropertyName(String methodName){
 final String[] prefixes={"get","set","add","remove"};
 for (final String prefix : prefixes){
  if (methodName.startsWith(prefix)
   && methodName.length() > prefix.length()){
   return Character.toLowerCase(methodName.charAt(prefix.length()))
   + methodName.substring(prefix.length()+1);
  }
 }
 throw new IllegalStateException(methodName
 +" is not a property get, set, add or remove method");
}

With this method in place and a static import to get it, my business object now looks as follows:

public class Article implements IArticle{
 //…
 public Price getPrice(){
  return price;
 }
 public Void setPrice(final Price newPrice) {
  return firePropertyChange(propertyName(), price, (price = newPrice));
 };
}

Et Voilà! Here is your business object with property change support, Void return type and no need to keep any property name strings in sync, in other words “fully refactoring-proof”. Thanks to the “strange” Void class and a little utility, property change support looks pretty much like straightforward Java code without magic constants:

 String priceProperty = propertyName(method(call(IArticle.class).setPrice(null)));
 article.addPropertyChangeListener(priceProperty, updatePriceView);

So what is the take-home message of this blog? The Void.class is a quite useful replacement for the void primitive. Inline-assignments may seem like a black sheep in the Java language and are prone to be misread, in non-complex situations like these, they beautify the code considerably.
Mind you the Java bean was just an example to demonstrate possible uses of these rare tools – in the real world a setter that returns the old value is usually more beneficial.

The actor model is a different way of modeling concurrent processes. Rather than threads interacting via shared memory with locks, the actor model leverages “actors” that pass asynchronous messages using mailboxes. A mailbox, in this case, is just like one in real life — messages can be stored and retrieved for processing by other actors. Rather than sharing variables in memory, the mailbox effectively separates distinct processes from each other.

First I notice something fundamentally wrong here: Actors do interact via shared memory. It’s the mailbox, which is both shared with the outside world and synchronized. Well, to be fair a mailbox does not need to be synchronized, it may well be implemented using a lock free algorithm. If you look at Kilim’s implementation, however, you will find a lot of synchronization over a shared array there.

And there was another thing that bugged me:

There are no locks and synchronized blocks in the actor model, so the issues that arise from them — like deadlocks and the nefarious lost-update problem — aren’t a problem.

As a user of actors I don’t need the synchronized keyword, true, and in fact you don’t find any synchronization in the user code. But seriously: Do we need a framework for that?

Translating the example to plain Java SE

What else is an actor like a (lightweight) thread and what else is a mailbox than a thread safe container? Let me translate the example code from the article to use only classes from the Java Standard Edition.
The “calculation type message” (I’ll try to use the same terms as in the article) is exactly the same as the original:

public class Calculation{
 private BigDecimal dividend;

 private BigDecimal divisor;

 private BigDecimal answer;

 public Calculation(BigDecimal dividend,BigDecimal divisor){
  this.dividend=dividend;
  this.divisor=divisor;
 }

 public BigDecimal getDividend(){
  return dividend;
 }

 public BigDecimal getDivisor(){
  return divisor;
 }

 public void setAnswer(BigDecimal ans){
  this.answer=ans;
 }

 public BigDecimal getAnswer(){
  return answer;
 }

 public String printAnswer(){
  return "The answer of " + dividend + " divided by " + divisor + " is " + answer;
 }
}

The DeferredDivision class, which is our first actor, looks almost the same as in the article. Instead of a mailbox class it uses a blocking queue, it implements Runnable, instead of extending the framework class “Task” and it handles InterruptedExceptions:

public class DeferredDivision implements Runnable{

 private BlockingQueue<Calculation> mailbox;

 public DeferredDivision(BlockingQueue<Calculation> mailbox){
  this.mailbox=mailbox;
 }

 @Override
 public void run(){
  try{
   Random numberGenerator=new Random(new Date().getTime());
   MathContext context=new MathContext(8);
   while(true){
    System.out.println("I need to know the answer of something");
    mailbox.offer(
     new Calculation(new BigDecimal(numberGenerator.nextDouble(),context),
      new BigDecimal(numberGenerator.nextDouble(),context)));
    Thread.sleep(1000);
    Calculation answer=mailbox.poll(); // no block
    if(answer != null && answer.getAnswer() != null){
     System.out.println("Answer is: " + answer.printAnswer());
    }
   }
  }catch(InterruptedException e){
   e.printStackTrace();
  }
 }
}

The Calculator class, which is the second actor, is not very different either. The modifications to the original code are exactly the same as in the DeferredDivision:

public class Calculator implements Runnable{

 private BlockingQueue<Calculation> mailbox;

 public Calculator(BlockingQueue<Calculation> mailbox){
  this.mailbox=mailbox;
 }

 @Override
 public void run(){
  try{
   while(true){
    Calculation calc=mailbox.take(); // blocks
    if(calc.getAnswer() == null){
     calc.setAnswer(
      calc.getDividend().divide(calc.getDivisor(),8,RoundingMode.HALF_UP));
     System.out.println("Calculator determined answer");
     mailbox.offer(calc); // no block
    }
    Thread.sleep(1000);
   }
  }catch(InterruptedException e){
   e.printStackTrace();
  }
 }
}

We don’t need the Ant script for Kilim’s Weaver here, because we don’t need to weave anything. So we don’t need to understand and maintain any XML definition either, which is great. Instead we can continue with the runner, which looks as simple as the original from the article, but I can give it an own maximum amount of messages. I chose 300, the same value that is hard coded in the Kilim framework:

public class CalculationCooperation{
 public static void main(String[] args){
  BlockingQueue<Calculation> sharedMailbox
   =new ArrayBlockingQueue<Calculation>(300);

  Runnable deferred=new DeferredDivision(sharedMailbox);
  Runnable calculator=new Calculator(sharedMailbox);

  new Thread(deferred).start();
  new Thread(calculator).start();
 }
}

Voila! This code does not only look very similar to the original, it also acts very similar. There are just two differences: It doesn’t use lightweight threads and there’s a difference in the way it fails. It fails? Wait! I was told that…

When an example backfires on a bold claim

There are no locks and synchronized blocks in the actor model, so the issues that arise from them — like deadlocks and the nefarious lost-update problem — aren’t a problem.

The funny thing is: That particular article itself is probably the best proof that it’s wrong. The code that the author presents is free of deadlocks, sure, but ironically it contains a huge lost-update problem, as does my no-framework translation.

The mailbox from the original will silently reject new messages (returning “false”), when it is full, while the BlockingQueue in my version will throw an IllegalStateException in the same situation. So this is the first obvious flaw in the code from the article and its translation. If the mailbox is full, we have a problem: We lose updates or we crash. Since I am a great fan of “fail fast” programming, I’d prefer the exception, because it enables me to quickly analyze what went wrong and take countermeasures, I don’t simply lose something without notice. Fortunately the fix for both of these problems is easy: Use a blocking “put” that waits for space in the mailbox.

There is a second bug, which is not that obvious. It’s also shared by the original code and the translation. Just follow the program: The DeferredDivision posts a Calculation, waits a second and takes a calculation from the mailbox. If the calculation has been solved it prints the result, else it just starts over. It reads good, it looks good and it’s wrong. Imagine this situation:
The DeferredDivision posts a Calculation, but before the calculator can take it from the mailbox (because it’s still busy), the DeferredDivision wakes up again, takes the unsolved calculation from the mailbox, and omits it. Now the calculator wakes up, can’t find that calculation and blocks until the DeferredDivision posts another. As a result the calculation has been lost.
Fortunately the second problems can also be fixed: One could use a blocking “get”, so the program doesn’t progress until there is a result in the mailbox/queue. Or one could repost the unsolved calculation and progress. Still the second solution may re-evoke the first problem: If you use a putnb (non blocking) with Kilim you could lose the new and reposted calculations as soon as the mailbox is filled (so you’d need to evaluate the return param of the putnb call) or with my alternative implementation a non blocking put (=offer) would throw an IllegalStatetException that indicates the queue is full. So you’d better use a blocking “put” here aswell. As a result the worst case scenario would be a constantly filled queue, and threads waiting to do something. Which is annoying but normal under heavy load.

So what is the take-home-message of this blog? Without the need for any actor abstraction framework I have recreated this example with nearly the same code. And, as I’ve shown, the actor model has not saved the author of the article from introducing a lost-update problem on two occasions in just about 20 lines of code. In fact it is equally easy to create the spaghetti eating philosopher’s problem with actors (the forks being messages in the shared mailboxes). So does that actor framework really make our life simpler as programmers?
And what’s left besides lightweight threads? What’s it really worth having lightweight threads anyway, facing multicore chips like AMD’s and Intel’s current consumer line or even SUN/Oracle’s Ultrasparc T2 chips, that eat entire thread pools for breakfast? Could it even hurt performance based on the fact that these CPU base their internal scheduling partly on the information that threads are independent instruction streams?
To be honest, I am not convinced this framework solves me any problem, I’m terribly sorry. Or is it just that I’m missing something important here?

It all started when I got a pixel-exact specification on how to draw some round borders, which I implemented and one of the next reports that we got said that our application’s resizing/repainting behavior showed undesirable lags. As I recently made a lot of changes in the way the look and feel paints the borders, I instantly felt guilty of it and luckily the report was also assigned to me, so I took my profiler to identify the slowest methods. The repainting of the borders took in fact most of the time when you resized the window, if not the most. It turned out that the borders were still painting fast enough. But I produced this little micro benchmark in my eager attempt to optimize that part of the code in order to see if a bit less load would make a difference (I suspected it could be flooding the EDT with lots of short repaints enough to cause that effect, so I thought reducing the time could change something – unfortunately it didn’t). And I got pretty surprised!

Here’s a little demo:

public class DrawingPixels extends JPanel {

  private int index = 0;
  private List<Color> colors;
  private long totalTimes;
  private long measures;

  public DrawingPixels() {
    final Dimension dim = new Dimension( 800, 800 );
    setMinimumSize( dim );
    setPreferredSize( dim );
    setMaximumSize( dim );
    setSize( dim );
    final Timer timer = new Timer();
    timer.scheduleAtFixedRate( new TimerTask() {
      @Override
      public void run() {
        repaint();
      }
    }, 1000, 1000 );

    colors = new ArrayList();
    for ( int t = 0; t < 256; t += 8 ) {
      colors.add( new Color( t, t, t ) );
    }
    for ( int t = 254; t > 0; t -= 8 ) {
      colors.add( new Color( t, t, t ) );
    }
  }

  @Override
  protected void paintComponent( final Graphics g ) {
    super.paintComponent( g );
    index = ( index + 1 ) % colors.size();
    System.out.println( index );
    final Color color = colors.get( index );
    final long start = System.currentTimeMillis();
    paintStuff( g, color );
    final long end = System.currentTimeMillis();
    final long elapsed = end - start;
    totalTimes += elapsed;
    ++measures;
    g.setColor( Color.WHITE );
    g.drawString(
      String.valueOf( totalTimes / measures ), 100, 100 );
  }

  public static void main( String[] args ) {
    EventQueue.invokeLater( new Runnable() {
      public void run() {
        final JFrame f = new JFrame();
        f.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
        f.setContentPane( new DrawingPixels() );
        f.pack();
        f.setVisible( true );
      }
    } );
  }

  private void paintStuff( final Graphics g, final Color color ) {
    g.setColor( color );
    for ( int y = 0; y < getHeight(); ++y ) {
      for ( int x = 0; x < getWidth(); ++x ) {
        g.drawLine( x, y, x, y );
      }
    }
  }
}

You don’t have to understand and read most of the code. The important part is the last method “paintStuff” which does the drawing. It fills this 800×800 pixel panel one pixel at a time. My development-machine back then took a whopping 2300 milliseconds to do that, which was quite frankly insane.

The next try got me a quite interesting result:

  private void paintStuff( final Graphics g, final Color color ) {
    final BufferedImage image =
      new BufferedImage( getWidth(), getHeight(), BufferedImage.TYPE_INT_ARGB );
    final Graphics imageGfx = image.getGraphics();
    imageGfx.setColor( color );
    for ( int y = 0; y < getHeight(); ++y ) {
      for ( int x = 0; x < getWidth(); ++x ) {
        imageGfx.drawLine( x,y,x,y);
      }
    }
    g.drawImage( image, 0, 0, this );
  }

This code just needed 590 ms, so painting into a buffered image and painting the buffered image onto the panel was faster than painting directly onto the panel and that took me by complete surprise!

Since a BufferedImage allows for setting the RGB-values of a pixel directly, I also tried that aswell and see if that would improve things:

  private void paintStuff( final Graphics g, final Color color ) {
    final BufferedImage image =
      new BufferedImage( getWidth(), getHeight(), BufferedImage.TYPE_INT_ARGB );
    final Graphics imageGfx = image.getGraphics();
    for ( int y = 0; y < getHeight(); ++y ) {
      for ( int x = 0; x < getWidth(); ++x ) {
        image.setRGB( x, y, color.getRGB() );
      }
    }
    g.drawImage( image, 0, 0, this );
  }

This version did it in just 96 miliseconds – quite an improvement to the 2500 milliseconds the first version needed!

Improvements with JRE 1.6

Now I’m sitting at home at a machine which is not exactly as fast as my development machine these days, but this test is not so much about raw CPU-Power, is more about the graphics subsystems sending data and commands to the graphics adapter, so it is rather testing how well Swing implements its drawing-machanisms. Back then, when I timed it, we were running Java 1.5 and now I am repeating this test with version 1.6.0_18 of SUNs Java virtual machine.
These are the results:

Things got considerably faster with the 1.6 runtimes. The results finally look sane.

The framework we are using in my current Project uses a UI abstraction layer, made of so-called “adapters”, which represent a GUI-toolkit independent representation of UI widgets to be used in the controllers. In the simplest case these adapters are just bound to a model and fire PropertyChangeEvents, which are handled by a GUI toolkit dependent adapter that translates these events to method calls on the UI-widget. So what this framework does is to separate the GUI toolkit from the controller side and it does that really well.
For the rest of this blog, I will stay on the controller side, where we find the GUI toolkit independent adapters. Now to bind an adapter to a model one possible technique is to give it a so-called ValueProvider, which has a simple interface (there are no generics yet):

public interface IValueProvider{
 Object getValue();
 void setValue(Object o);
}

These value providers sometimes hold some conversion logic or lazy initializations on write access, which is just what happened in my case. In my controller I had 11 of these value providers and 9 of them were similar, except the called another method in the business object:

IValueProvider newFooValueProvider(){
  return new IValueProvider(){
    public Object getValue(){
     return convertToUi(getOptions().getFoo());
    }
    public void setValue(final Object value){
      ensureOptionsInitialized();
      getOptions().setFoo(convertToModel(value));
    }
  };
}
IValueProvider newBarValueProvider(){
  return new IValueProvider(){
    public Object getValue(){
     return convertToUi(getOptions().getBar());
    }
    public void setValue(final Object value){
      ensureOptionsInitialized();
      getOptions().setBar(convertToModel(value));
    }
  };
}
//…seven more like these …

Pretty repetitive and screaming to be refactored, you’d think. I first thought of using an abstract ValueProvider class, but that meant I still needed a new class per attribute, which still cluttered my code. This is one of these moments where you probably wished you had closures to avoid the clutter. Without closures I decided to use the next best thing: Reflection.

An intermediate solution

Reflection is a mighty tool in cases like this: I could just create a ValueProvider that takes a proper getter and setter method and let it invoke those after doing the standard stuff. This is almost as easy said than done:

private IValueProvider newValueProvider(final Method getter, final Method setter){
  return new IValueProvider(){
    public Object getValue(){
     try{
       return convertToUi(getter.invoke(getOptions()));
     }catch ( IllegalAccessException e){
       ExceptionHelper.toRuntimeException(e);
     }catch( InvocationTargetException){
       ExceptionHelper.toRuntimeException(e);
     }
    }
    public void setValue(final Object value){
      try{
        ensureOptionsInitialized();
        setter.invoke(getOptions(),convertToModel(value));
     }catch ( IllegalAccessException e){
       ExceptionHelper.toRuntimeException(e);
     }catch( InvocationTargetException){
       ExceptionHelper.toRuntimeException(e);
     }
    }
  };
}
//…

Now I had nine methods which looked like:

IValueProvider newFooValueProvider(){
  Method getter = ReflectionHelper.getMethod(IOptions.class,“getFoo");
  Method setter = ReflectionHelper.getMethod(IOptions.class, “setFoo", Integer.class);
  return newValueProvider(getter,setter);
}
IValueProvider newBarValueProvider(){
  Method getter = ReflectionHelper.getMethod(IOptions.class,“getBar");
  Method setter = ReflectionHelper.getMethod(IOptions.class, “setBar", Integer.class);
  return newValueProvider(getter,setter);
}
//…seven more like these…

This looks pretty slick, don’t you think so? The best thing is: it saved me 33 lines of cluttered code. Only thing is: it has a smell, because it references methods by strings and when you rename or move a method your compiler won’t tell you a thing if you mess it up. Your unit tests may uncover your mistake, but then again: It could be so much easier. How nice would it be, if you had fist class methods, so you could write something like: Method getter = #IOptions.getFoo(); to get a reference on the Method object?

Dynamic proxies make your day

A co-worker asked me if there was a way to reference a method without using strings, to make it refactoring-proof. And I told him that I didn’t know how and that this problem has bugged ever since, but as I spoke it out, I happened to have one of the brighter moments in my life, because: As far as interfaces are concerned, this is actually quite easy and the solution was always right in front of me: Dynamic proxies. I love them, for real. The Proxy class probably belongs to the 5 most underrated additions to the Java runtime ever. Application servers make extensive use of dynamic proxies to wrap aspects like thread pooling, remoting, load balancing, transaction logic and similar stuff around beans and services and there are of course some tiny handy tools which use them, some of you might use a particular one on a regular basis, like me: EasyMock.
As it turned out the API of the tool I am about to develop in this blog shared some characteristics with EasyMock in the end.

Let’s start with the simple idea and refine the API step by step.

The basic idea: The tool creates a dynamic proxy that can implement any interface. Its InvocationHandler hands over the last method that was called on the proxy.

I first started with a class of stateful objects that provide a proxy and a simple getter to provide the user access to the called method:

class MethodFinder {
  private Method method;
  public <T> call(final Class<? extends T> clazz){
    return (T) Proxy.newProxyInstance(
     getClassLoader(),
     getInterfaces(clazz),
     new InvocationHandler(){
      public Object invoke(final Object proxy, final Method method,
          final Object[] args) throws Throwable{
        this.method = method;
        return null;
      }
    });
  }

  private static Class<?>[] getInterfaces( final Class<?> clazz ) {
    final List<Class<?>> interfaces
     = new ArrayList<Class<?>>( Arrays.asList( clazz.getInterfaces() ) );
    if ( clazz.isInterface() ) {
      interfaces.add( clazz );
    }
    return interfaces.toArray( new Class<?>[interfaces.size()] );
  }
  public Method method(){return method;}
}

This was the basic draft and it was flawed: It would throw NullPointerExceptions with primitive return types and using it looked like this:

  final MethodFinder mf = new MethodFinder();
  mf.call(IOptions.class).getFoo();
  final Method getter = mf.method();

I liked to get rid of the new-operator. To achieve that I would need to use a static method and a static field. That would get me into new trouble: Multithreaded access. I don’t want to see unpredictable results because one thread might overwrite another one’s current method reference. Luckily I can have an own variable per thread by using a ThreadLocal object, so we can avoid this conflict easily. This way I could also move the proxy’s invocation handler to a constant field and avoid unnecessary object creation. Here’s a second take on the tool:

public class MethodFinder {

  private static final InvocationHandler HANDLER = new InvocationHandler() {
    public Object invoke( final Object proxy, final Method method,
      final Object[] args ) throws Throwable {
      tlMeth.set( method );
      return null;
    }
  };

  private static final ThreadLocal<Method> tlMeth = new ThreadLocal<Method>();

  public static <T> T call( final Class<? extends T> clazz ) {
    return (T) Proxy.newProxyInstance(
      getClassLoader(),
      getInterfaces( clazz ),
      HANDLER );
  }

  private static Class<?>[] getInterfaces( final Class<?> clazz ) {
    final List<Class<?>> interfaces
    = new ArrayList<Class<?>>( Arrays.asList( clazz.getInterfaces() ) );
    if ( clazz.isInterface() ) {
      interfaces.add( clazz );
    }
    return interfaces.toArray( new Class<?>[interfaces.size()] );
  }

  public static Method method() {
    try {
      return tlMeth.get();
    } finally {
      tlMeth.remove();
    }
  }

  private static ClassLoader getClassLoader() {
    ClassLoader cl = Thread.currentThread().getContextClassLoader(); //primary
    return cl != null ? cl : MethodFinder.class.getClassLoader(); // fallback
  }
}

With this modification, using this tool looks a little bit better:

  MethodFinder.call(IOptions.class).getFoo();
  final Method getter = MethodFinder.method();

There is still room for improvement. By introducing a new method, I can nest those proxy-calls that call methods, which have a return value. This is the idea expressed in Java code:

  public static Method method() {
    return method(null);
  }

  public static Method method(Object doesntMatter) {
    try {
      return tlMeth.get();
    } finally {
      tlMeth.remove();
    }
  }

So we can now use this shortcut for non-void-methods:

  final Method getter = MethodFinder.method(MethodFinder.call(IOptions.class).getFoo());

I’d like to add static imports at this point. That makes it look a lot better. Likewise I’d like to notice that for void-methods we cannot use the nested method, but use the two-liner we have used before. Here’s how it looks:

  import static de.plush.brix.tools.reflection.MethodFinder.*;
  //…
  final Method getter = method(call(IOptions.class).getFoo());
  call(IOptions.class).setFoo(null);
  final Method setter = method();

As you can see this is pretty much like configuring expectations with EasyMock. The only thing that keeps us from using this tool in production is that it can’t handle primitive return types yet, but that is easily fixed. Here’s the final result:

import static java.lang.Boolean.FALSE;
import java.lang.reflect.*;
import java.util.*;

public class MethodFinder {

  private static final InvocationHandler HANDLER = new InvocationHandler() {
    public Object invoke( final Object proxy, final Method method,
        final Object[] args ) throws Throwable {
      tlMeth.set( method );
      final Class<?> returnType = method.getReturnType();
      if ( Boolean.TYPE.equals( returnType ) ) {
        return FALSE;
      } else if ( Byte.TYPE.equals( returnType ) ) {
        return (byte) 0;
      } else if ( Short.TYPE.equals( returnType  ) ) {
        return (short) 0;
      } else if ( Integer.TYPE.equals( returnType ) ) {
        return 0;
      } else if ( Long.TYPE.equals( returnType ) ) {
        return 0L;
      } else if ( Float.TYPE.equals( returnType ) ) {
        return 0f;
      } else if ( Double.TYPE.equals( returnType ) ) {
        return 0d;
      }
      return null;
    }
  };

  private final static ThreadLocal<Method> tlMeth = new ThreadLocal<Method>();

  public static <T> T call( final Class<? extends T> clazz ) {
    return (T) Proxy.newProxyInstance(
      getClassLoader(),
      getInterfaces( clazz ),
      HANDLER );
  }

  private static Class<?>[] getInterfaces( final Class<?> clazz ) {
    final List<Class<?>> interfaces
    = new ArrayList<Class<?>>( Arrays.asList( clazz.getInterfaces() ) );
    if ( clazz.isInterface() ) {
      interfaces.add( clazz );
    }
    return interfaces.toArray( new Class<?>[interfaces.size()] );
  }

  public static Method method(){
    return method(null);
  }

  public static Method method(final Object doesntMatter){
    try{
      return tlMeth.get();
    }finally{
      tlMeth.remove();
    }
  }

  private static ClassLoader getClassLoader() {
    ClassLoader cl = Thread.currentThread().getContextClassLoader(); //primary
    return cl != null ? cl : MethodFinder.class.getClassLoader(); // fallback
  }
}

Now here it is: A surprisingly small and simple tool which can ease your pain with refactoring code that relies on reflection.

public class Unchecked {

 public static void rethrow( final Throwable checkedException ) {
  Unchecked.<RuntimeException>thrownInsteadOf( checkedException );
 }

 @SuppressWarnings("unchecked")
 private static <T extends Throwable> void thrownInsteadOf(Throwable t) throws T {
  throw (T) t;
 }

 public static void main( final String[] args ) {
  // throw new IOException(); // we don’t want to declare this exception
  Unchecked.rethrow( new IOException() );
 }
}

In case you haven’t tried this: what this code does is stripping the “checked” attribute from the checked IOException! So with this little generic magic, you may now throw any checked exception without having to catch or declare it, as you can see in the main method.

Why does it work?

At first sight, this looks like an ugly hack which won’t be available in future Java versions, but will it? I dare to say there is little danger. To understand why I think so, let me get into more depth.

JLS 14.18 The throw Statement
A throw statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the throw completes abruptly for that reason. If evaluation of the Expression completes normally, producing a non-null value V, then the throw statement completes abruptly, the reason being a throw with value V. If evaluation of the Expression completes normally, producing a null value, then an instance V’ of class NullPointerException is created and thrown instead of null. The throw statement then completes abruptly, the reason being a throw with value V’.

What the Java Language Specification tells us in this paragraph is that the cast should be executed before the throws is executed, and in fact it is! Here is the proof:

 private static <T extends Throwable> void thrownInsteadOf(Throwable t) throws T {
  throw (RuntimeException) t;
 }

When we execute our class with this changed method we get a ClassCastException. Wait: if a cast is executed before throwing the exception, how can the hack work then? I cannot cast this IOException to RuntimeException! To explain this, let’s dive into Type-Erasure. Type erasure happens when generic methods are compiled. The generic type information is erased according to the given type bounds. Applied to our hack, the rules for type erasure would make the compiler create this method signature:

 private static void thrownInsteadOf(Throwable t) throws Throwable {
  throw (Throwable) t;
 }

As we can see the cast is unnecessary and can be eliminated by the compiler. Let’s test if it really is: I will change the generic method to just return the exception and have the caller throw it instead and see what happens.

 public static void rethrow( final Throwable checkedException ) {
  throw Unchecked.<RuntimeException>thrownInsteadOf( checkedException );
 }

 @SuppressWarnings("unchecked")
 private static <T extends Throwable> T thrownInsteadOf(Throwable t) {
  return (T) t;
 }

When I execute my hack with these changes, this is what I get:

Exception in thread "main" java.lang.ClassCastException:
java.io.IOException cannot be cast to java.lang.RuntimeException
	at de.plush.brix.exeptions.Unchecked.rethrow(Unchecked.java:4)

Interesting, isn’t it? I’ve got a ClassCastException, but not where one would expect it to be. This is the proof, that the cast in the “thrownInsteadOf”-method got eliminated. It is the caller who does the cast and from what we’ve seen from the type erasure, placing the cast there is the only correct way to do it. If we think about it for a while: how else would it be possible to keep the method generic? For private methods the compiler could create synthetic methods for every generic type it is called with, but for the sake of simplicity, behavioural consistency and memory consumption, this should be avoided. For public methods it would be impossible anyway. The compiler’s behaviour is sane. Since the caller does the cast it is not executed, because the Java runtime must abort abuptly and pass the exception up the call graph until it is caught or terminates the thread. So by specification the outer cast must never be executed, no matter how bonkers it is. Which means the Java runtime’s behaviour is also sane and the compiler knows what it’s doing.

Revisiting type erasure for throws clauses:

Type erasure and throws clauses are a strange couple, no really! In order to understand how the hack works I had to shed a little light on how those two work together. To analyze this, let’s start with the signature of our generic method:

 @SuppressWarnings("unchecked")
 private static <T extends Throwable> void thrownInsteadOf(Throwable t) throws T {
  throw (T) t;
 }

If I used this method like this:

 Unchecked.thrownInsteadOf(new IOException());

The compiler would infer the type signature and ask me to catch or declare the Exception. However, if I used the method like this:

 Unchecked.thrownInsteadOf(new RuntimeException());

Then the type interference would see it is a RuntimeException and not ask me to do any exception handling. Now here’s the surprising bit: As I stated above, type erasure would translate this method to this:

 private static void thrownInsteadOf(Throwable t) throws Throwable {
  throw t;
 }

You see: This method, at runtime, would always throw checked exceptions, but the compiler would always have to force me to handle exceptions, wouldn’t it? Funny thing is: The compiler cannot, because that would break the semantics for RuntimeExceptions. This may seem inconsistent, but it is legal because of what is the really weird part: While in the Java language the unchecked RuntimeException is a subtype of the checked Exception, the Java runtime environment itself knows no such thing as a checked exception. This is why the above method will work at runtime, after type erasure has made it throw a “checked” exception type.
Sun could have avoided this by making the checked Exception a subtype of the unchecked RuntimeException, but they haven’t. God knows why. But this is why we got that sweet loophole.

Bottom line is: If I’m not heavily mistaken this is no “hack”, but perfectly legal loophole which is not likely to change in the future. This is a good thing for all those among us who are really annoyed by handling all those checked exceptions, but please don’t overuse it: Checked exceptions are really not that bad, if they are used with care.

public class Foo{

 private String from;
 private String to;
 private Date when;
 private boolean valid;

 void setFrom(String x){
  if(x == null || x.isEmpty()){
   from="";
   valid=false;
  }else{
   from=x;
   valid=true;
  }
 }

 void setTo(String x){
  if(x == null || x.isEmpty() || x.equals(from)){
   to="";
   valid=false;
  }else{
   to=x;
  }
 }

 void setDate(Date x){
  if(x.after(new Date())){
   when=null;
   valid=false;
  }else{
   when=x;
   setFrom(from);
   setTo(to);
  }
 }

 boolean isValid(){
  return valid;
 }
}

The original code included some UI-widgets, asynchronous web service calls, more sophisticated validation, but it roughly boils down to something like the code you can see above. This example is fairly small, but he ugliest part of it is the “valid” state, which gets updated on any change.
Code like this is harder to follow than necessary, because you have to track the state-change, especially if you try to change the code. Now just compare that to this code:

public class Foo{

 private String from;
 private String to;
 private Date when;

 void setFrom(String x){
  if(x == null || x.isEmpty()){
   from="";
  }else{
   from=x;
  }
 }

 void setTo(String x){
  if(x == null || x.isEmpty() || x.equals(from)){
   to="";
  }else{
   to=x;
  }
 }

 void setDate(Date x){
  if(x.after(new Date())){
   when=null;
  }else{
   when=x;
  }
 }

 boolean isValid(){
  return !from.isEmpty() && !to.isEmpty()
    && when != null && !when.after(new Date());
 }
}

Just by removing the extra “valid” state and replacing it with a query method, the code got dramatically more readable and it was even possible to remove some ugly code in the “setDate” method, which existed solely to manage that field correctly, plus it is absolutely obvious when this object’s state is considered valid and when it’s not.
This simple example shows a basic rule: Each modified field in your class represents state and each state which can be substituted by a query is usually unnecessary and should be avoided, unless it causes an unbearable performance-penalty.

Update:
I just found another example, which has nothing to do with queries, but in general it’s the same problem with unnecessary state:

class Bar{
 private List<Object> items = new ArrayList<Object>();
 private boolean save;

 public void reset(){
  items.clear();
  save = true;
 }

 public void buzz(int x){
  for(int t = 0; t<x; ++t){
   items.add(SomeFactory.create(x,t));
  }
  if(save){
   save();
  }
 }

 public void bell(int x){
  save = false;
  buzz(x);
  save = true;
  for(int t = 0; t<x; ++t){
   items.add(SomeOtherFactory.create(x,t));
  }
  save();
 }

 private void save(){
  for(Object item : items){
   SomeService.save(item);
  }
 }
}

Believe it or not, but I just had to work on code structured exactly like that, only it had 3 times as many public methods like that. I can hardly express how much I hate it! First it is easy to get wrong, because the callee always has to reset(); before using any of the public method. Second, this class has way too much state and is hard to follow. Third: I didn’t mention that this is a shared class in a multithreaded context. The callee must make sure no two calls use the object at the same time. Please, please with sugar topping, please: Beware of writing code like that! In this case pass the list as a parameters, make the boolean field a parameter and replace it with a meaningful enum. If you want to keep the public API clean, introduce new public methods without these parameters. And what you’ll get is this:

class Bar{
 private enum Save{REQUESTED, SKIPPED}

 public void buzz(int x){
  buzz(x, new List(), Save.REQUESTED);
 }

 public void bell(int x){
  bell(x, new List());
 }

 private void buzz(int x, List items, Save save){
  for(int t = 0; t<x; ++t){
   items.add(SomeFactory.create(x,t));
  }
  if(save == REQUESTED){
   save(items);
  }
 }

 private void bell(int x, List items){
  buzz(x, items, Save.SKIPPED);
  for(int t = 0; t<x; ++t){
   items.add(SomeOtherFactory.create(x,t));
  }
  save(items);
 }

 private void save(List<Object> items){
  for(Object item : items){
   SomeService.save(item);
  }
 }
}

This may be more code, but it is easier to refactor, the public API is hard to use in a wrong way (and has less methods by the way), the code is easy to follow because you don’t have to keep global variables in mind and any object of this class is safe to share.
Let me repeat the mantra once again: Avoid unnecessary state if you can.

Just to keep you interested in case this blog might have been too trivial in your opinion: My next Blog will contain some cool reflection magic.

Not exposing inner state

How often do you see code like this?

class Foo{
 private final List<Data> list = new ArrayList<Data>();
 public List<Data> getData(){
  return list;
 }
}

This code is simple and looks good, but even if it looks completely harmless – it isn’t! The first thing I notice is that this class exposes inner state, it exposes its list, which is stateful. Any class could get the list and modify it, potentially breaking your class. Your class can, in no way, control its inner state. Which also means that you cannot get a class like this thread safe. You cannot work on this list safely from within the class. Modifying the list from inside your class will potentially break every class that uses it. Even switching to another List-implementation can ruin the performance of any algorithm that works on this list. And what happens if you decide to use a set instead? Every class that expected a list would need to adapt! As a user of this class you would need to copy the result of the list to your favourite data-structure to be safe.

class Bar{
 private final Foo foo = new Foo();
 public void doSomething(){
    //might break foo:
    foo.getData().add(new Data()); 

    //runtime is sensitive to changes in the list type:
    final Iterator<Data> itr = foo.getData().iterator();
    while(itr.hasNext()){
     final Data data = itr.next();
     if(condition(data)){
      itr.remove();
     }
    }

    //what foo returns might not be what you like
    final Set<Data> set = new TreeSet<Data>(foo.getData());
  }
}

Now let’s imagine you had to change Foo from using lists to using sets:

class Foo{
 private final Set<Data> set = new HashSet<Data>();
 public List<Data> getData(){ //legacy API
  return new ArrayList<Data>(set);
 }
}

Wait… this one will break every class which relies on the fact that the getter always returns the same list instead of a copy! So you need to do this:

class Foo{
 private final List<Data> list = new ArrayList<Data>();
 public List<Data> getData(){
  return list;
 }
 private void doSomeWork(){
  final Set<Data> set = new HashSet<Data>(list);
  //work with data
  list.clear();
  list.addAll(set);
 }
}

You can see the ugly creeping into the source code, can’t you? No matter what you’re trying to achieve, problems are all over you. You can’t change the return type of the method without hassles, you can’t even change the inner workings of your class without running into problems. Imagine a full blown, complex application code with thousands lines of code all built on classes like this and now watch your Eclipse workspace. Do you see something familiar? I’m sure! And I guess that would be a safe bet, because I see this happening everywhere. Can a programming style suck more than that? Why is it, that even experienced programmers keep on using this kind of style, even though they must feel the pain every time they need to change their code? I guess this pattern is used a lot because beans are used a lot, because it is quickly written without a lot of boilerplate code and because it’s just like a bad habit. The worst thing is: I can’t deny that I frequently fall into the same pit over and over again. I’m trying to improve though, as the solution is astonishingly simple.
Let’s get rid of the problems by simply moving the responsibility for copying the list from outside of the class to the inside, pepper it with generics and serve it:

class Foo{
 private final List<Data> list = new ArrayList<Data>();
  public <T extends Collection<? super Data>> T dataTo(final T target){
   for(final Data data : list){
    target.add(data);
   }
   return target;
 }
}

Any user is now free to chose the type he likes, he can control which collection instances share the data and which don’t and the user-side code doesn’t look too bad either:

class Bar{
 private  Foo foo = new Foo();
 public void doSomething(){
    final Set<Data> set = foo.dataTo(new TreeSet<Data>());
    //...
  }
}

The class Foo can be thread-safe and changing the collection implementation in Foo won’t affect the performance of any class that obtained data from it, it will not break the build of dependent classes and you don’t need ugly workarounds inside of Foo to honor a legacy API: you could even make Foo use a HashMap internally and all you needed was to change the method to copy the HashMap’s values instead. And if you need to share state with Foo, you can still use listeners, at the expense of some annoying boilerplate code though.
But wait! Doesn’t „copy on get“ mean you waste performance? Sure. But how often does performance matter and how often do ripple effects matter? If you measure a real performance problem somewhere, you can still tune this particular class, use a caching proxy or build a workaround. It’s better to have a small amount workarounds to fix performance problems than to have hundreds of them to cope with structural problems.

Hiding Structure

This is very similar to the stuff above, but rather concentrating on the data structure. Let’s take a look at some piece of code you might see once in a while, after we have learned something from the stuff above:

class Foo{
 public void doSomething(final Fizz fizz){
    final Iterable<Data> datas
     = fizz.getBar().getBuzz().dataTo(new ArrayList<Data>());
    for(final Data data : datas){
     if(attrib.equals(data))){
      //...
     }
    }
  }
}

The problem is almost the same as with the list-example. As you can easily see, Foo depends on three other classes: Fizz, Bar and Buzz. As soon as any of these classes needs a change in its API, for example if Bar needs a list of Buzz, the class Foo is subject to a change. This means Foo is a target of ripple effects. To avoid that, the Law of Demeter should always be in the back of your mind. The Law Of Demeter roughly says that an object should only talk to its closest friends, which are own fields, own parameters and objects it created on its own. It’s a rule, which is sometimes hard to follow and you shouldn’t waste your time hacking up your code like mad just to follow it perfectly. It’s enough to follow its intent: keep dependency-chains very short!
The example above would violate the Law Of Demeter, because Foo talks to Bar, even though it has to ask Fizz for it. It would be better if Foo only talked to Fizz and let Fizz handle it’s business with Bar and Buzz.
As a result the code could look like this:

class Foo{
  public void doSomething(final Fizz fizz){
    final Iterable<Data> datas= fizz.dataTo(new ArrayList<Data>());
    for(final Data data : datas){
     if(attrib.equals(data))){
      //...
     }
    }
  }
}

Alas, the example above means that Fizz would have to delegate the call to Bar and Bar would have to delegate the call to Buzz which obviously creates a lot of boilerplate code. If you like to avoid some of that it may be a good idea to just eliminate some of the dependency but not everything of it. But it may be worth it. Since Foo will have no business with any of the intermediate objects any more, we’re rid of some of the ripple effects with this kind of style.
Unfortunately, Foo still has to iterate over a copy of Fizz’ data, which means that this approach will fail if the Data objects are stored in a structure that is not easy to iterate, say, because it’s so huge that it won’t fit into memory. Therefore it might be a good idea to just pass the algorithm and let the data owner do the iteration. We wouldn’t need to copy anything either, which is good for the application’s performance and memory consumption. This is how it works:

interface Function<R,A>{
  R execute(A param);
}

class Foo{
  public void doSomething(final Fizz fizz){
    final Function<Void, Data> something = new Function<Void, Data>(){
      public Void execute(final Data candidate){
        if(attrib.equals(data){
         //...
        }
        return null;
      }
    };
    fizz.forEachDataDo(something);
  }
}

Alas, this solution requires a new Interface which means even more code and the creation of a class that implements the interface is rather cumbersome and hard to read.

Enter Closures

With Java 7 Sun promised to bring Closures to the Java language. Closures, or Lambda Expressions, will in most situations save you from writing just another interface. Following the recent Java Closure proposal by Alex Buckley the code above would look as follows:

class Foo{
  public void doSomething(final Fizz fizz){
    final #void(Data) something = #(Data data){
     if(attrib.equals(data){
      //...
     }
   };
   fizz.forEachDataDo(something);
  }
}

Or shorter:

class Foo{
  public void doSomething(final Fizz fizz){
   fizz.forEachDataDo(#(Data data){
    if(attrib.equals(data){
     //...
    }
   });
  }
}

The code with closures is almost as short as the naïve original but it has none of it’s shortcomings, apart from the delegation. So there we are stuck between a rock and a hard place: you can clearly see that this code doesn’t look quite as readable and requires more boilerplate than the first, naïve example, but it decouples way better which will pay off when you have to apply changes later. Since we don’t have closures yet, thus with the interface still necessary for this coding style, it is especially hard to break the habit of writing it the way you always do. You should consider it though.

@Immutable
public final class Address{

 private final String street;
 private final String zipcode;
 private final String town;
 private final String country;

 private Address(final AddressBuilder b){
  street=b.street;
  zipcode=b.zipcode;
  town=b.town;
  country=b.country;
 }

 public String getStreet(){
  return street;
 }
 //..

 public static AddressBuilder build(){
  return new AddressBuilder();
 }
 //..

 public static class AddressBuilder{
  private final SingleThreadBarrier barrier
   = new SingleThreadBarrier(getClass());
  private String street;
  private String zipcode
  //..
  public AddressBuilder withStreet(final String street){
   barrier.pass();
   this.street=street;
   return this;
  }

  //..

  public Address noNullPropertyAllowed(){
   barrier.pass();
   if(Arrays.asList(street, zipcode, town, country).contains(null)){
     throw new NullPointerException();
   }
   return new Address(this);
  }

 }
}

Now, the last method was pretty interesting. I wrote a very short method to keep the example small, alas that method won’t deliver a rather useless error message. If you really want to make things more concise in terms of debugging, the naive approach could look a little something like this:

  public Address noNullPropertyAllowed(){
   barrier.pass();
   if(street==null){throw new IllegalArgumentException(“street is null“);}
   if(zipcode==null){throw new IllegalArgumentException(“zipcode is null“);}
   if(town==null){throw new IllegalArgumentException(“town is null“);}
   if(country==null){throw new IllegalArgumentException(“ country is null“);}
   return new Address(this);
  }

This code is repetitive and as soon as the validation involves more than just a little check like this, it will become the coleslaw-and-beer equivalent for method bodies: it expands and expands and expands and at some point you will wish your co-workers away, so nobody will notice when you release the stink. Time to build a better tool to do the job, really! Why not chose annotations?

A basic annotation based validation mechanism

Update (March 24, 2010): After reading a blog about the JSR 303 for bean validation, I’m pretty amazed that my idea was not that dumb at all. I do like the idea of binding the validator to its annotation woth a @Constraint-annotation and I initially thought of something similar. There was just one sole reason why I didn’t do it: I had no idea how to retrofit any of the the NotNull annotations around. But I’m thinking about changing my code accordingly and just have a special Mapping for @NotNull.

Lets start with defining an interface for checking an object’s field against an annotation:

interface AnnotationCheck<A extends Annotation> {
 void check(final Object o,final Field field,final A annotationType)
           throws IllegalAccessException;
}

And implement that for the NotNull annotation:

class NotNullCheck implements AnnotationCheck<NotNull> {
 @Override
 public void check(Object o,Field field,NotNull annotationType)
                   throws IllegalAccessException {
  if ( field.get( o ) == null ) {
   throw new IllegalArgumentException(
   "Field "+o.getClass().getName()+'#'+field.getName()+" must not be null");
  }
 }
}

To have something a little more sophisticated, let’s create a Range annotation to check numbers:

@Target(ElementType.FIELD)
@Retention(RUNTIME)
public @interface Range {
 double from()  default Double.NEGATIVE_INFINITY ;
 double to()  default Double.POSITIVE_INFINITY;
}

Here’s a simple check against a number range. Note that this won’t work perfectly with BigDecimals and doesn’t care for Double.NaN, but let’s keep things simple:

class RangeCheck implements AnnotationCheck<Range>{

 private static int LESS=-1;
 private static int EQUAL=0;
 private static int GREATER=1;

 @Override
 public void check(final Object o,final Field field,final Range range)
                   throws IllegalAccessException{
  final Object value=field.get(o);
  if(value != null){ //null-checks are @NotNull's business.
   if(value instanceof Number){
    final Double number=((Number)value).doubleValue();
    final int lowerBound
     =compareTolerant(range.from(),number,Math.ulp(number));
    if(lowerBound == GREATER){
     throw new IllegalArgumentException(message(o,field,
      "must be greater or equal "+range.from()+" but is: "+value));
    }
    final int upperBound
      =compareTolerant(range.to(),number,Math.ulp(number));
    if(upperBound == LESS){
     throw new IllegalArgumentException(message(o,field,
      "must be less or equal "+range.to() + " but is: "+value));
    }
   }else{
    throw new IllegalArgumentException(message(o,field,
     "must reference a number. Found: "+value.getClass()+": "+value));
   }
  }
 }

 private static String message(final Object o,final Field field,final String details){
  return "Field "+o.getClass().getName()+'#'+field.getName() + " "+details;
 }

 private static int compareTolerant(final double a,final double b,final double tolerance){
  return a == b ? EQUAL //
    : a == Double.POSITIVE_INFINITY ? GREATER
    : b == Double.NEGATIVE_INFINITY ? GREATER
    : b == Double.POSITIVE_INFINITY ? LESS
    : a == Double.NEGATIVE_INFINITY ? LESS
    : b - tolerance <= a && b + tolerance >= a ? EQUAL
    : a < b - tolerance ? LESS : GREATER;
 }
}

Now as we have the checks ready for action, it’s time to implement an API to use these checkers in a concise way:

public final class Check{

 @SuppressWarnings("unchecked")
 private static Map<Class<? extends Annotation>,AnnotationCheck> strategies
 =new HashMap<Class<? extends Annotation>,AnnotationCheck>();

 static{
  strategies.put(NotNull.class,new NotNullCheck());
  strategies.put(Range.class,new RangeCheck());
 }

 private Check(){
  // utility class
 }

 public static void declaredFieldsOf(final Object o){
  for(final Field field:o.getClass().getDeclaredFields()){
   for(final Annotation annotation:field.getAnnotations()){
    checkField(o,field,annotation);
   }
  }
 }

 private static void checkField(final Object o,final Field field,final Annotation annotation){
  final Class<? extends Annotation> annotationType=annotation.annotationType();
  @SuppressWarnings("unchecked")
  final AnnotationCheck<Annotation> checkStrategy=strategies.get(annotationType);
  if(checkStrategy != null){
   final boolean acs=field.isAccessible();
   try{
    field.setAccessible(true);
    checkStrategy.check(o,field,annotation);
   }catch(final IllegalAccessException e){
    throw new RuntimeException(e); // not expected to happen
   }finally{
    field.setAccessible(acs);
   }
  }
 }

}

Voilà, c’est prêt à l’emploi! Now using this thing becomes a breeze:
Let’s take a look at an immutable class with it’s builder, which used this new tool:

@Immutable
public final class Position{

 private final Article article;
 private final int amount;

 private Position(final OrderBuilder b){
  article=b.article;
  amount=b.amount;
 }

 public String getAmout(){
  return amount;
 }
 //..

 public static OrderBuilder order(){
  return new OrderBuilder();
 }

 //..

 public static class OrderBuilder{
  private final SingleThreadBarrier barrier
   = new SingleThreadBarrier(getClass());

  @NotNull
  private Article account;
  @Range(from=1)
  private int amount;
  //..
  public OrderBuilder ofArticle(final Article article){
   barrier.pass();
   this.article=article;
   return this;
  }

  //..

  public Position received(){
   barrier.pass();
   Check.declaredFieldsOf(this);
   return new OrderPosition(this);
  }

 }
}

The methods may have some rather odd names, as they don’t seem to do what they’re called, but this is the programmers perspective from inside the API. Actually you should write a decent javadoc to accompany this. If you leave the inside-view and start looking at the API from the user’s perspective, you may notice that writing code against an API like this is a bit cumbersome, as the methods don’t do what they’re called. But remember: Code is read more often than written and just look how beautiful this one reads:

Position pos=Position().order() //get a builder object
 .ofArticle(kermitTheFrog) //initialize the builder
 .withAmount(10)
 .received(); //check and construct the object

Now the reason why I validate the builder and not the built object is that I don’t want to lose flexibility. I could well design another builder for a return shipment, which builds a position with a negative amount only:

public static class ReturnShipmentBuilder{
   //..
  @NotNull
  private Article account;
  @Range(to=-1)
  private int amount;
  //..

And it would still look good:

Position pos=Position().returnShipment()
 .ofArticle(kermitTheFrog)
 .withAmount(10) //boom! This should be negative!
 .received();

Alas, setting up multiple builders which just have some differently annotated fields stinks. Here we could create one common builder and just let it use another internal mutable class to hold the data, just what a C++-programmer would call a struct. One builder, but different structs with different annotations. The common builder would run the check against its struct and everything is honkey dory. But I’m gonna leave you that as a little homework. Right now my mind fills with ideas for a flexible validation mechanism, where a validator nothing more than some annotated fields and a method which fills those from a model and calls the checker. I’m not sure yet, whether I want to write about that or find something different to fiddle with. We will see. Stay tuned!

There is a common case you may have encountered more than once, which is long constructors with repeating types. You’re likely to see them in immutable classes. I’m not going to discuss why immutable classes are desirable, I’m going to talk about easing the pain to construct them. Take this for example, I must admit that I tended to write code like this quite often.:

@Immutable
public Address(String street, String zipcode, String town, String country){
 //...
}

True, the IDE may help you with displaying the parameter names in a pop up, but no one will warn you if you get the order wrong and if Murphy loves your company, you’ll end up with a pile of unusable data in a productive database. It gets worse if you decide to re-factor the class. If you change the parameter order of example, it just needs a bad moment for a CVS-commit to cause major mayhem, which gets more likely the bigger the team and the higher the fan-in-complexity of the class is.

This can be avoided, unfortunately at the price of complexity. Let me introduce to you two approaches: The copy-mutator-method and the builder-class.

Copy-Mutator

This pattern is quite nice to enforce immutability and at the same time avoid problems with ambiguous constructor arguments plus it is easy to write, but it has downsides. Let me first show the source code and discuss the rest later.

@Immutable
public final class Address{

  private String street;
  private String zipcode;
  private String town;
  private String country;

  public Address(){}

  private Address(final Address a){
   street=a.street;
   zipcode=a.zipcode;
   town=a.town;
   country=a.country;
  }

  public String getStreet(){
   return street;
  }
  //..

  public final Address withStreet(final String steet){
   final Address a=new Address(this);
   a.street=street;
   return a;
  }

  public final Address withZipcode(final String zipcode){
   final Address a=new Address(this);
   a.zipcode=zipcode;
   return a;
  }

   //..
}

Here we go. To initialize an object with this pattern is a nice and fluent expression:

Address home=new Address()
 .withStreet("Sesame St. 10")
 .withZipcode("12345")
 .withTown("Muppetcity")
 .withCountry("USA");

So why not simply use a bean and setters? Well, it may be just as readable, but objects made like this can be immutable and beans can not. So if you want to enforce immutability, here’s a solution.

But there are downsides to this pattern:
First, the fields are not final, which requires a little more care when you touch and change the internals of the class, so you don’t introduce mutable state to an immutable class by accident. I would consider that a low risk, but it’s there.

Secondly this pattern creates a lot of intermediate objects that get thrown away immediately. This may seem to be a problem if you want to create a lot of these objects in a tight loop, but it isn’t. It isn’t, because you will rarely find yourself in a situation, where such a constant cost is a real issue – and if you do you can still tune this hot spot and keep the rest of the code tidy. And it isn’t because a modern JVM can handle these kind of object allocations very well, as pointed out in this excellent article by Brian Goetz. So consider this a non-issue.

The last downside with this pattern I’d like to mention is the only real downside in my humble opinion: If your requirement is to disallow “null” for any fields, you have a problem.
You’d have to write a method to check the fields against null, but you are not forced to call it right after initialization. And if you install a check at field-access time, your object may cause an exception way after initialization, which makes it hard to impossible to find the cause, because you needed to check every initialization.
In short: If you need to check invariants on initialization, this pattern is not an option.

Luckily there is another pattern which allows to avoid this particular downside at the expense of some more lines of code:

The Builder

The builder is a mutable object which creates the immutable object after checking everything is set up as required. Because the builder is mutable it cannot be shared safely among threads (thanks for the hint, Theo!). It is therefore wise to prevent any other thread from accessing the builder than the one that created it. A simple barrier will do the job:

public class SingleThreadBarrier{
 private final Class<?> c;
 private final Thread thread;

 public SingleThreadBarrier(final Class<?> c){
  this.c=c;
  thread=Thread.currentThread();
 }

 void pass(){
  if(thread != Thread.currentThread()){
   throw new IllegalStateException("Multithreaded access to "+c+" forbidden.");
  }
 }
}

Now with our barrier ready to go, let me show you the sourcecode for the builder:

 @Immutable
 public final class Address{

  private final String street;
  private final String zipcode;
  private final String town;
  private final String country;

  private Address(final AddressBuilder b){
   street=b.street;
   zipcode=b.zipcode;
   town=b.town;
   country=b.country;
  }

  public String getStreet(){
   return street;
  }
  //..

  public static AddressBuilder build(){
   return new AddressBuilder();
  }
  //..

  public static class AddressBuilder{
   private final SingleThreadBarrier barrier
    = new SingleThreadBarrier(getClass());
   private String street;
   private String zipcode
   //..
   public AddressBuilder withStreet(final String street){
    barrier.pass();
    this.street=street;
    return this;
   }

   public AddressBuilder withZipcode(final String zipcode){
    barrier.pass();
    this.zipcode=zipcode;
    return this;
   }

   //..

   public Address noNullPropertyAllowed(){
    barrier.pass();
    if(Arrays.asList(street, zipcode, town, country).contains(null)){
      throw new NullPointerException();
    }
    return new Address(this);
   }

  }
 }

As you can see building an address with this pattern is just a tiny bit longer, but still a very fluent expression which almost reads like a book:

Address home=Address.build() //get a builder object
 .withStreet("Sesame St. 10") //initialize the builder
 .withZipcode("12345")
 .withTown("Muppetcity")
 .withCountry("USA")
 .noNullPropertyAllowed(); //check builder's setup and construct the address

One nice thing about this pattern is, for a start, that the fields of the immutable object are final, so you can’t create a mutable state by accident. The more important goodie is the method which finally checks and constructs the immutable object. Because you can have more than one! In other words: it’s an extensible design. I just wrote a very basic implementation to keep it short, but you may add other validation methods without breaking anything and when you start thinking about it for a moment, things like “@NotNull”, annotations in general, “Reflection” and “Strategy Pattern” might spring to mind. Maybe I’ll revisit this topic in a later blog posting, but for now I’ll call it a day and leave you with your own thoughts or even the urge to comment, which is highly appreciated.

Code is more often read than written, so readability is a great concern in programming and often it’s the small things that make things worse and can it get smaller than a boolean? The other big issue with programming in general is that code must be maintainable, so it must be easy to change it. Sometimes it needs to be cleaned up, sometimes functionality has to be added, so ripple effects is something we don’t need.
For both reasons I have noticed myself using less boolean parameters every day.  Today I would even state that using a boolean parameter is a bad idea in most cases. Let me demonstrate my point with a little example:

<T extends Component> T find(final Class<T> type,String name,final boolean descend,final Component... components){
 T result=null;
 if (components != null){
  for (int t=0; result==null && t<components.length; ++t){
   final Component candidate=components[t];
   if (type.isInstance(candidate) && equals(name, candidate.getName())) {
    return type.cast(candidate);
   } else if (descend && candidate instanceof Container){
    result = find(type,name,descend,((Container)candidate).getComponents());
   }
  }
 }
 return result;
}

This code doesn’t look suspicious, but the ugly gets apparent when this method gets used:

Component x = find( Button.class, "button", true, root );

If you see a line like this in a program, you usually have no idea what ‘true’ stands for, until you dig into the code of the method – which gets worse if the sourcecode is not available.
And what if you need to introduce scanning upwards in the hierarchy? You would need to change the API significantly and break every method that uses this API. Or you’d need to introduce a new method which will probably make you copy code or deprecate the old method (which you will never get rid of).

So usually it’s a better strategy to use an enumeration, which creates a few more lines of code, but just have a look:

static enum Search{
 FLAT, DESCENDING;
}

<T extends Component> T find(final Class<T> type,String name,final Search strategy,final Component... components){
 T result = null;
 if(components != null){
  for(int t=0; result==null && t<components.length; ++t){
   final Component candidate = components[t];
   if(type.isInstance(candidate) && equals(name,candidate.getName())){
    return type.cast(candidate);
   } else if (strategy==Search.DESCENDING && candidate instanceof Container){
    result=find(type,name,strategy,((Container)candidate).getComponents());
   }
  }
 }
 return result;
}

The full beauty of this API is visible when it is used, just have a look at this:

Component x = find( Button.class, "button", Search.DESCENDING, root );
Component y = find( JPanel.class, "rightPanel", Search.FLAT, root );

Just by looking at the code you could guess what the parameter does.

This API also supports enhancing the functionality way better. To implement scanning upwards the hierarchy, just modify the enumeration and add some lines to the method:

static enum Search{
 ASCENDING, FLAT, DESCENDING;
}

<T extends Component> T find(final Class<T> type,String name,final Search strategy,final Component... components){
 T result = null;
 if(components != null){
  for(int t=0; result==null && t<components.length; ++t){
   final Component candidate = components[t];
   if(type.isInstance(candidate) && equals(name,candidate.getName())){
    return type.cast(candidate);
   } else if (strategy==Search.DESCENDING && candidate instanceof Container){
    result=find(type,name,strategy,((Container)candidate).getComponents());
   }
  }
  if (strategy==Search.ASCENDING){
   result=find(type,name,strategy,candidate.getParent());
  }
 }
 return result;
}

So here it is: I’ve enhanced the functionality without breaking the old API just by adding an enumeration and another branch.

Component x = find( Button.class, "button", Search.DESCENDING, root );
Component y = find( JPanel.class, "rightPanel", Search.FLAT, root );
Component z = find( TabbedPane.class, "tabs", Search.ASCENDING, textField );

The old stuff still works, it is still readable. A much better solution than a boolean.

Now just imagine the Swing API, if it looked a little bit like:

jFrame1.setState(State.MAXIMIZED);
jFrame2.setState(State.RESTORED);
jFrame3.setState(State.MINIMIZED);
jFrame4.setState(State.ICONIFIED);
jFrame5.setState(State.INVISIBLE);