While coming up with APIs or a framework, design forms a crucial part of the end result. While a solid design does indeed allow for flexible usage of an API, usability goes hand in hand with the design. What better way is there to create an API, than to learn from the mistakes and successes of other developers first ? Lets take a look at some examples in the java API where things could have been better…

Stack and Properties:

A java.util.Stack provides a standard Stack implementation in the java language. But did you know it extend a java.util.Vector ? Why is this wrong ? Because you can do this

package com.design;
 
import java.util.Stack;
import java.util.Vector;
 
public class StackTests
{
 
    public static void main(String... args)
    {
        new StackTests().go();
    }
 
    public void go()
    {
        Vector<String> vector = new Stack<String>();
        vector.add("first");
        Stack <String> stack = (Stack <String>) vector;
        String peek = stack.peek();
        System.out.println(peek);
 
        stack.push("next");
        stack.push("item");
        String remove = vector.remove(2);
        System.out.println("Removed: " + remove);
        peek = stack.peek();
        System.out.println(peek);
    }
}
 
Output:
 
first
Removed: item
next

There are so many things that are going on there that are wrong.

1. Vector is a slow DS. Its methods are synchronized and there is no way around this right now since this contract has been sealed. It cannot be changed without changing backward compatibility.
2. Vector has exposed its own methods to a stack. You should not be able to add() on to a stack.
3. Typecasting between Vector / Stack is plain weird.
4. Since the contract methods exposed by both classes operate on the same internal data structure, the outcome can often be confusing.

This is something the API folks got wrong. This is not the only class that should have used composition over inheritance. The java.util.Properties class is another example. It extends from HashTable and now there is no way around that.

Dummy variables:

This one is probably not well known. A HashSet() has a default constructor which takes a boolean variable called dummy. It is never used. So why does it exist ? Its there because a LinkedHashSet (which extends the HashSet) uses this constructor to tell its super class that the backing data structure should be a LinkedHashMap. The advantage of doing this is that LinkedHashSet will have very little code to house into its implementation.

From HashSet.java:

    /**
* Constructs a new, empty linked hash set.  (This package private
* constructor is only used by LinkedHashSet.) The backing
* HashMap instance is a LinkedHashMap with the specified initial
* capacity and the specified load factor.
*
* @param      initialCapacity   the initial capacity of the hash map
* @param      loadFactor        the load factor of the hash map
* @param      dummy             ignored (distinguishes this
*             constructor from other int, float constructor.)
* @throws     IllegalArgumentException if the initial capacity is less
*             than zero, or if the load factor is nonpositive
*/
HashSet(int initialCapacity, float loadFactor, boolean dummy) {
    map = new LinkedHashMap(initialCapacity, loadFactor);
}

It is not a great idea to write a separate constructor just because one sub class might need it. Secondly the javadoc explicitly mentions that only a LinkedHashSet uses this constructor. That message is a little confusing. Does that mean other subclasses are not meant to use this constructor ? Why does a subclass even need to know that ?

The side effect of this decision is not far reaching, as you may have already noted. Had the constructor been protected, the consequences would have been worse.

Usability:

The java community is pretty awesome. When a solution is too complicated, folks come out with a new framework / API to combat it. Take EJB for example. Versions 1 and 2 were pure horror. Version 3 is a little better. JEE6 has also learned a little from Spring.

This brings us to the java Date and its formatting APIs. Usability wise, many deprecated methods and confusing constructors make for a difficult time using the API. Which is why other solutions like Joda time and Apache commons date utils pop up. The ‘Why Joda Time?’ section helps explain what problem the API intends to solve where the JDK fell short.

In general, it will be hard to judge an API / framework without letting a few developers toy around with it first. The methods / constructors may well do what the contract defines them to do, but if it takes 100 steps against 10 to reach from point A to point B, guess which route a developer wants to take ?

In conclusion, these points are not about nitpicking the JDK / Java APIs in any manner. As long as developers learn from these mistakes, they can avoid them in their own code. The JDK is abundant with good usages of design patterns and some of its API are well thought out. Just avoid the bad design decisions whenever possible

I chanced upon a post a while back about how a switch statement should be replaced with the strategy pattern. If you have not had a chance to go through it, please do. The post is not very long.  I found myself disagreeing very strongly with the author of the post and I was surprised to find that people thought this was a good idea.

The gist of the post was that using the Strategy pattern was better than using switch statements to determine which logic to execute. Here is why I think the idea used there was bad

1. The introduction of the Strategy pattern, in the example, introduces three new classes. So for every case in a switch statement, we should go about replacing the corresponding code with a new class ? This could easily lead to an explosion in the number of classes.
2. Distributing logic across classes makes it harder for a developer to follow. When I traverse 2 / 3 links down a code path I might lose track of where I started.
3. Introducing a new case means I have to introduce one more class, remember to add that as a strategy and switch to that strategy correctly when the case is presented.
4. Introducing a new class to handle a ‘case’ might not make sense. Classes are supposed to cohesively carry out a function. Introducing a new class for every function that a class is supposed to perform, dilutes the purpose of the class.
5. The code that was supposed to perform the switch case is simply done else where and called a strategy.

Applying patterns where they do not belong, can be an anti pattern by itself. I can relate with what the author is trying to do. When I finished the ‘Head first design patterns’ book I was racing to implement a pattern for everything that was around me. The book stopped me right there and warned ‘HelloWorld does not need a design pattern’. And they are absolutely right. For a design pattern to succeed, you need

1. The right problem to apply the pattern.
2. Correct implementation of the pattern to solve the problem.
3. Knowledge and relevant documentation if necessary, to let the maintenance developer down the line know that this is how you used the pattern.

Patterns are meant to solve common design problems but trying to use them everywhere can lead to overly engineered code that is hard to read and maintain. Use patterns only when they are necessary and help you solve the problem.

Iterators can be designed so that they are fail fast or fail safe. Depending on the underlying implementation of the Iterator, a ConcurrentModificationException is thrown if the Collection is modified while Iterating over the data structure. It pays to understand how an Iterator will behave under both conditions. Lets try to implement fail fast Vs fail safe iterators of our own.

Our data structure for this example is pretty simple. It defines an interface that abstracts set and get operations on a structure. How the underlying classes handle invalid set operations or the size of the structure is implementation dependent

A data structure interface:

public interface Data<T> extends Iterable<T>
{
    int size();
    T getElement(int position);
    void setElement(int position, T t);
}

An underlying implementation of such an Interface, could be say an array of Integers whose size is fixed. Invalid indexes on bounds are not allowed and the internal structure will not grow or shrink. An implementation is given below

An array of integers implementing the interface:

public class ArrayOfIntegers implements Data<Integer>
{
    private static int DEFAULT_SIZE = 1024;
    private int mods = 0;
 
    private Integer[] integers = new Integer[DEFAULT_SIZE];
 
    @Override
    public Integer getElement(int position)
    {
        checkRange(position);
        return integers[position];
    }
 
    @Override
    public void setElement(int position, Integer integer)
    {
        checkRange(position);
        mods++;
        integers[position] = integer;
    }
 
    @Override
    public int size()
    {
        return integers.length;
    }
 
    @Override
    public Iterator<Integer> iterator()
    {
        // return new FailFastIter();
        // return new NoFailIter();
        return null;
    }
 
    private void checkRange(int position)
    {
        if (position > DEFAULT_SIZE || position < 0)
        {
            throw new ArrayIndexOutOfBoundsException(position);
        }
    }
 
    // Iterator implementations go here as a private class
}

If we wanted to Iterate over the ArrayOfIntegers structure, there are 2 ways to do it. Either ensure that the underlying data structure Integer[] integers is not modified while we iterate over ArrayOfIntegers, or make a copy of Integer[] integers so that any changes made to the internal structure will not affect the caller in any way. Let us look at 2 private Iterator classes that we can place into the ArrayOfIntegers class that will help us achieve both flavors of Iteration

Fail fast:

private class FailFastIter implements Iterator<Integer>
{
    int currentIndex = 0;
    int check = -1;
    int size = integers.length;
 
    public FailFastIter()
    {
        check = mods;
    }
 
    @Override
    public boolean hasNext()
    {
        checkForModification();
        if (currentIndex < size)
        {
            return true;
        }
        return false;
    }
 
    @Override
    public Integer next()
    {
        checkForModification();
        Integer result = integers[currentIndex];
        currentIndex++;
        return result;
    }
 
    @Override
    public void remove()
    {
        throw new UnsupportedOperationException();
    }
 
    private void checkForModification()
    {
        if (check != mods)
        {
            throw new ConcurrentModificationException();
        }
    }
}

The fail fast Iterator in this example, refers to the internal data structure directly. Every modification to the internal structure is tracked using the ‘mods‘ variable. Our iterator stores this value when it was initially created using the ‘check‘ variable. Both variables are compared every time the hasNext() or next() methods are called. If they are unequal then it means that the underlying structure was changed. This is when the code throws a ConcurrentModificationException

Fail safe:

private class NoFailIter implements Iterator<Integer>
{
    int currentIndex = 0;
    Integer[] internal = Arrays.copyOf(integers, size());
    int internalSize = -1;
 
    public NoFailIter()
    {
        internalSize = internal.length;
    }
 
    @Override
    public boolean hasNext()
    {
        if (currentIndex < internalSize)
        {
            return true;
        }
        return false;
    }
 
    @Override
    public Integer next()
    {
        if (hasNext())
        {
            Integer result = internal[currentIndex];
            currentIndex++;
            return result;
        }
        else
        {
            throw new NoSuchElementException();
        }
    }
 
    @Override
    public void remove()
    {
        throw new UnsupportedOperationException();
    }
}

The fail safe iterator makes a copy of the internal array data structure and uses it to iterate over the elements. This prevents any concurrent modification exceptions from being thrown if the underlying data structure changes. Of course, the overhead of copying the entire array is introduced. Both implementation can be tested using a program

Iterator test for both iterators:

public class IterTest
{
    public static void main(String... args)
    {
        new IterTest().go();
    }
 
    public void go()
    {
        Data<Integer> dataArray = new ArrayOfIntegers();
        for (int iCounter = 0; iCounter < 100; iCounter++)
        {
            dataArray.setElement(iCounter, iCounter);
        }
        Iterator<Integer> iterator = dataArray.iterator();
        while (iterator.hasNext())
        {
            System.out.println(iterator.next());
            dataArray.setElement(1, 12);
        }
    }
}

By changing the Iterator implementation that the iterator() method returns, this test program will either throw a ConcurrentModificationException or iterate over all the elements without knowing what changed under the hood.

It makes sense to throw ConcurrentModificationException from an Iterator in certain cases. Under other scenarios you just don’t care if the Iterator will fail or survive an internal structure change. Taking a leaf out of the java Collection API, take a look at the Iterator behavior of an ArrayList Vs that of a CopyOnWriteArrayList.

Iterator test for 2 iterators within the JDK API:

public class IterTest2
{
    public static void main(String... args)
    {
        new IterTest2().go();
    }
 
    public void go()
    {
        List<String> arList = new ArrayList<String>();
        List<String> copyList = new CopyOnWriteArrayList<String>();
        populate(arList);
        populate(copyList);
        iterate(arList);
        iterate(copyList);
    }
 
    private void populate(List<String> list)
    {
        for (int iCounter = 0; iCounter < 100; iCounter++)
        {
            list.add(new Integer(iCounter).toString());
        }
    }
 
    private void iterate(List<String> list)
    {
        try
        {
            for (String x : list)
            {
                System.out.println(x);
                list.add(x);
            }
        }
        catch (RuntimeException e)
        {
            e.printStackTrace();
        }
    }
}

The CopyOnWriteArrayList does not fail when the internal structure changes, but ArrayList does. This example better highlights the problem of fail fast Vs fail safe iterators. The next time your write a custom iterator for your classes, consider this decision.

PS: The data structure defined here was just to illustrate the problem. You could certainly design this better by first providing an Abstract implementation that houses a private Iterator class, which will provide the default Iterator implementation for all subclasses. If the previous sentence sounds confusing, have a look at the Itr private class within the AbstractList class in the java source. The interface and implementation are much richer than the example provided here.