How is my implementation of an immutable stack?
Writing an elegant immutable stack is difficult in Java, mainly due to the lack of multiple return values. But your code does look quite fine.

I am comparing your API with Scala's immutable stack. One interesting bit is that there the signature of push translates to:

public &lt;T2 super T&gt; ImStack&lt;T2&gt; push(T2 e)


which looks uncomfortable but makes a lot of sense too: Adding elements to a stack can widen the type but never narrow it down. Keeping the current type is a special case of this.

Your isEmpty method is unfortunately flawed. Assume I have created a stack of one element, like:

Object myObject = null;
ImStack&lt;Object&gt; stack = new ImStack&lt;Object&gt;(myObject, null);


Now stack.peek() is correctly null. On an empty stack, this should have created an exception, not returned a null.

One solution to solve this problem is to have isEmpty() always return false. We also create a private subclass¹ of ImStack called ImEmptyStack, where isEmpty() returns true, and peek() throws an exception. In your constructor, you create a new empty stack as tail when that argument would be null:

ImStack(T head, ImStack&lt;? extends T&gt; tail) {
  this.head = head;
  this.tail = tail != null ? tail : new ImEmptyStack&lt;T&gt;();
}


1: Actually, subclassing here leads to problems. The two classes should both be subtypes of a common interface. So basically, the Composite Pattern.

By overriding the size() in the ImEmptyStack, you can simplify that as well:

class ImStack&lt;T&gt; {
  public int size() {
    return 1 + tail.size();
  }
}

class ImEmptyStack&lt;T&gt; extends ImStack&lt;T&gt; {
  public int size() {
    return 0;
  }
}


Back to your isEmpty() method, code like this should never happen:

if ( head == null &amp;&amp; tail == null)
    return true;
else return false;


because it is equivalent to return(head == null &amp;&amp; tail == null). Every time you write code like return foo() ? true : false, you know you can simplify that.

I'd like to sketch your reverse() method in a more functional manner, using an accumulator argument:

public ... reverse() {
  return this.reverse(new ImEmptyStack&lt;T&gt;());
}

private ... reverse(ImStack&lt;...&gt; acc) {
  return tail.reverse(acc.push(head));
}

// Empty stack:

private ... reverse(... acc) {
  return acc;
}


This is as efficient as your solution, because your size call also traverses the whole stack recursively. The advantage of my solution is the simplicity. Of course, it is trivial to rewrite this to an iterative solution, because the above sketch is tail recursive:

reverse() {
  ImStack&lt;T&gt; accumulator = new ImEmptyStack();
  ImStack&lt;T&gt; current     = this;
  while(!( current instanceof ImEmptyStack&lt;T&gt; )) {
    accumulator = accumulator.push(current.peek());
    current     = current.pop();
  }
  return accumulator;
}


Note that .pop() can never return null in my adaption of your code (an empty stack should throw an exception).



Something minor that I noticed is your inconsistent spacing around the argument lists of your methods:

ImStack ( T head, ImStack&lt;T&gt; tail)  // left outer and inner space
pop()  // no space
push( T e) // left inner space


This is no problem in itself, but it would be better to settle for one style.