Generics, the fine print

Generics were introduced in Java 5.

Generics help keeping the language safer by giving the compiler more ways to reason about the code and reject it when it is bad. That is what a strictly typed language is all about.

With generics also auto-boxing was introduced. The concept was borrowed from C# and the dot-net framework. Auto-boxing is auto-magically converting/wrapping an int into an Integer (auto-box) when a reference type is needed and backwards when the reference type Integer is given and an int is needed (auto-unboxing). This makes primitive types to play 'nicely' with generics to some degree.

Generics also helps avoiding code duplication, because you can have a something of anything like a List of Student without any code duplication or any code generation under the hood, to create specialized classes per anything type. So this List exists once and is just as applicable to Student as is to Donkey.

A strong point of Java has always been the preservation of investment (in code). What worked once should still work. So code that was legal (and compiled) in the Java 1.1 era should still run, even if used today in its binary format. Heck, in closed source stuff that might be the only form you have, but your investment is preserved because of this backwards compatibility.

This strong point has a flip side. Pré Java 5 does not understand generics, which would break the backwards compatibility. That is why the generic info, after being used by the compiler for correctness verification is then thrown away by the same compiler. Little if anything of the generic information is preserved for the run time. As a matter of fact, the JVM has no notion of generics, nor does it need it to function. This has all kind of consequences.

In modern Java code, in particular since Java 8 with Functional interfaces and Streams, generics are a must, because the provide safety in the one hand and the required flexibility in the other, required to make the Java 8 features possible at all.

   Map studentsMap = new HashMap(); 1

   studentsMap.put( Integer.valueOf( 313581 ) ,new Student( "Potter","Harry" ) );

   // some time later
   Student harry = (Student) studentsMap.get(Integer.valueOf( 313581 ) ); 2

   List<String> l1 = new ArrayList<>();
   List<Student> stuList = new ArrayList<>();
   Map<String,BiFunction<Double,Integer,Integer>> operatorMap;

class Person{}
class Student extends Person{}

// in some code
    void m(){
      Person paul = ....
      Student serena = ...
      List<Person> pl;
      List<Student> sl;

    }

Cheating the compiler

You can trick the compiler into breaking its promises. In the end, of course the compiler is not the victim, but the program is. It will generate a ClassCastException on retrieval of the non-fitting object. And as programs go when they generate uncaught exceptions: they will be aborted by the JVM.

public static void main( String[] args ) {
        List<Student> sl = new ArrayList<Student>();
        sl.add( new Student( "Hermione" )); 1
        List ol = (List) sl;                2
        ol.add( new Person("Voldemort") );  3

        // somewhere else in the scenario
        Student hermione = sl.get( 0 );       4
        Student lilly = sl.get( 1 );        5
        System.out.println( "lilly = " + lilly ); 6
    }

Wildcard and bounds

Read Horstmann section 8.8.

With the definition in the previous paragraphs, you are losing some flexibility, compared to raw types. In particular, you may want to insert sub types of a class into a collection, or retrieve sub types of a class from a collection.

Using wildcards and bounds will give back some of the flexibility while still upholding type-safety. The wildcard has been given the character symbol '?', the question mark.

Upper bound or Covariant

Quiz: Can you name the super types of circle in the class diagram above?

Shape, Object, Serializable, ArcLike, Surface, and Circle itself.

When you intend to write code with high flexibility, in particular when you use inheritance as in extends and implements, then there are a few rules to apply to your generic code. It all has to do with what a container, defined with generic types should accept or will produce.

We will refer to the picture above. We have two scenarios:

1. A class that makes or supplies shapes. Imagine reading the shape definitions from a drawing file with vector graphics.
2. A class that should accept shapes, like a canvas on which you can draw.

The supplier or Producer as it is called in the documentation, could be some collection such as a list of any of the types in the class diagram: Object, Serializable (that is probably how the Objects were read from disk), but the most likely and useful would be the Shape type.

  interface Canvas {
    void draw( List<Shape> shapes ); 1
  }

1. as far as the draw method is concerned, the list produces the shapes to be drawn.

Now imagine that you have a list of circles: List<Circle> circles = new ArrayList<>(). Then the above definition of the Canvas.draw() method forbids you to do canvas.draw( circles );, which is quite counter-intuitive, because the class diagram and the code says that a Circle is a Shape. The compiler will say: 'incompatible types: List<Circle> cannot be converted to List<Shape>'.

This is because, although a Circle is a sub-class of Shape, a List<Circle> is NOT a sub-class of List<Shape>. To amend this problem, you must change the definition of the draw method so that it accepts shapes but also any derived type. You do that by adding the wild-card which expresses anything (within limits or bounds).

  interface Canvas {
    void draw( List<? extends Shape> shapes ); 1
  }

1. This accepts Shape but also anything that is a sub type of Shape, so Circles, Triangles, Lines etc.

This makes the draw method more flexible and reusable, because the draw method can draw any shape now. Type theory calls this kind of relation between Shape and List of Shape Covariant. They both develop in the same direction, so semantically a List<? extends Shape> is covariant with Circle extends Shape. You could say, both extend down and therefor there is an upper bound, Shape in the example.

Lower bound or Contra variant

Now imagine that you have a method in some other class that wants to collect Shapes in a collection like a List. In the documentation such list, which should accept objects, would be called a Consumer.

  class Collector {
    // objects are added to be added to receiver or consumer
    void collect( List<Circle> receiver ){ 1
      Circle c =...
      receiver.add( c ); 2
    }
  }

Again, the compiler will complain if you call collect with your list of Circles as input. Use case: you want to tally up the total area covered by circles.

This time it says the same thing on the call statement collector.collect(circles). Let’s apply the same solution as above. If we define the collect method like void collect( List<? extends Circle> receiver ), the compiler will not complain on this line, but on the line receiver.add( c ); with a nasty curse:

incompatible types: Circle cannot be converted to CAP#1
  where CAP#1 is a fresh type variable:
    CAP#1 extends Shape from capture of ? extends Shape

So extends is not the way to go. You could infer that the list should be defined such that it accepts the Circle but also any type that circle extends or, from the stand point of the circle, a super type of Circle. You are actually saying that circle and any of its super types will be acceptable to the receiver. Circle is the lower bound in the example.

class Collector {
    // objects are added to receiver
      void collect( List<? super Circle> receiver ){ 1
        Circle c =...
        receiver.add( c ); 2
      }
}

The List<? super Circle> in the above example is now contra variant with Circle.

Self use in Generic definitions

Generics is not only applicable for collections, although that aspect of the standard Java library is a big customer of this language feature. But it can be used in other places too, as you have seen in the functional interfaces which define the shape of lambda expressions.

You may have come across a generic type definition that looks a bit weird as in, the type is used in its own definition. An example of that is the definition of the Enum class, which the abstract super class of all enums:

public abstract class Enum<E extends Enum<E>>
        implements Comparable<E>, Serializable {
}

This definition puts bounds or constraints on the type E, which must hence be a sub type (sub class) of Enum itself.

Another one is in the use of Comparable, like in the String class, it says among others String implements Comparable<String>, to make Strings comparable to each other, but not to other types. Again a bound or constraint of types, in the example the parameter of the int compareTo(T) method declared in Comparable.

Let us make a simple and silly but instructive example: A zoo. We want it to be such that a class inherits all the traits of its super, and we want to be able to use it in a fluent style of programming.

In our programs we want to express things like donald.fly().swim().walk(), which is a common sequence of operations for ducks. We want each of the methods in the chain to return the duck, so that Donald can do his operations in any order he likes.

This is also understood by the IDE, which will show completions fitting for the duck when the object is a Duck. For the Bird class on the other hand, the IDE will not complete with swim(), and for the Penguin not with fly().

To make this work, you need to make your classes as you could say self-aware. It means that the class in the hierarchy defines a method called self() whose return type is that of the class, not one of the super types. The self-use in the generics declaration makes this work, in combination with the fact that each leaf class [1] has a self() method which, through convincing the compiler with generics, returns an object of the correct type. In the definition of each leaf class, the leaf class itself is the type parameter, like in Penguin implements Bird<Penguin>, Swimmer<Penguin> etc. In particular, it is not parameterized any further such as Penguin<P>, because they themselves are the desired final type or leaf types.

If you want a non-leaf (abstract) class or interface, your have to further use the self reference in the generic definition.

public interface EBird<EB extends EBird<EB>>  extends Flyer<EB>, Walker<EB>{

     EB afterBurner(){
         System.out.println("VROOOAAAR");
         return self();
     }
}

public class ThunderBird implements EBird<ThunderBird>{
    public static void main( String[] args ) {
        ThunderBird tb = new ThunderBird();
        tb.fly().move().walk().fly().brood().fly().afterBurner();
    }
}

The code below shows what all this looks like for Bird (providing self), Flyer, and Duck:

package zoo;

public interface Animal<A extends Animal<A>> {

    default A move() {
        System.out.println( "twitch " );
        return self();
    }

    default A brood() {
        System.out.println( "cosy with my offspring " );
        return self();
    }

    // makes object self aware.
    default A self() {
        return (A) this;
    }

}

The common trait of animals is that they can move. It is in the name. Even coral can move, if not very far.

package zoo;

public interface Flyer<F extends Flyer<F>> extends Animal<F> {

    default F fly() {
        System.out.println( "swoosh" );
        return self();
    }
}

package zoo;

public class Duck implements  Flyer<Duck>, Swimmer<Duck>, Walker<Duck> {

}

This all provides the most benefit in Java 8 and up, because from Java 8 interfaces can have default and static methods, thereby implementing things, based on the abstract methods the implementing class must provide, as is the case with self(). And even self() is generified out by way of convincing the compiler that the default implementation does the trick. Minimal code with maximum effect.

The techniques described here are heavily used in the AssertJ library. The details of this SELF use can be found here .

isAssignableFrom. Will a cast work?

We can use this in a generic way too, by passing along the expected type.

public <T> List<T> filterForType(List<?> list, Class<T> typeToken) { 1
    List<T> result = new ArrayList<>();
    for ( Object object : list ) {
        if ( typeToken.isAssignableFrom( object.getClass() ) ) { 2
            result.add( typeToken.cast( object ) );
        }
    }
    return result;
}

1. T is the expected type of the elements in the result list.
2. The isAssignableFrom method checks if the type of the object is the same as, or a sub type of, the type represented by the type token. For instance to check if an object represents a number you can do

if ( Number.class.isAssignableFrom( object.getClass() ) ) { 1
    Number number = Number.class.cast( object ); 2
    Number number2 = (Number) object; 3
}

Note that this is different from the instanceof operator, which is a compile-time check, so it needs static , at compile time known type information. You can see that from the fact that the instanceof operator is used with a compile time type, and not with a Class object.

if ( object instanceof X ) { 1
    X x = (X) object;
}

The Class type is also used in the reflection API, which is a set of classes and interfaces that allow you to inspect the information of classes at run-time. We will see more on that in a later week.

Testing generics

As explained, generics is mainly used at the source code level and compiler to check the program for correct use of the declared types and methods. As such, testing of the generic aspect of your code is done when your compiler is happy with it AND you have expressed your real intent. Sometimes the last part is the trickiest.