JavaPro Online, May 2004
Angelika Langer & Klaus Kreft

Wildcard Instantiations of Parameterized Types

What is the purpose of wildcards?
More Details Regarding the Wildcard Language Feature
    Access Restrictions
        Rules for Unbounded Wildcards
        Rules for Upper Bound Wildcards
        Rules for Lower Bound Wildcards

Using Wildcard Instantiations

Using Wildcards With An Upper Bound
Using Unbounded Wildcards
Using Wildcards With A Lower Bound
    Remaining Limitations

Summary
References

1 Wildcard Instantiations of Parameterized Types

1.1 What is the purpose of wildcards?

public abstract class Shape {
   public abstract void draw();
}
public final class Circle {
   ...
   public void draw() { ... }
   ...
}
public final class Triangle {
   ...
   public void draw() { ... }
   ...
}
...

public void drawAllShapes(Collection<Shape> c) {
   for (Shape s : c) {
      s.draw();
   }
}

Collection<Shape> c = new LinkedList<Shape>();
... fill the collection with shapes ...
drawAllShapes(c);

Collection<Triangle> c = new LinkedList<Triangle>();
... fill the collection with triangles ...
drawAllShapes(c);

In order to make up for the lack of covariance among instantiations of a parameterized type, the language designers invented wildcards.  Using wildcards we can declare the drawAllShapes() method as follows:

public void drawAllShapes(Collection<? extends Shape> c) {
   for (Shape s : c) {
      s.draw();
   }
}

Given this parameter declaration we can invoke the drawAllShapes() method as before, supplying a collection of shapes to the method:

Collection<Shape> c = new LinkedList<Shape>();
... fill the collection with shapes ...
drawAllShapes(c);

Collection<Triangle> c = new LinkedList<Triangle>();
... fill the collection with triangles ...
drawAllShapes(c);

1.2 More Details Regarding the Wildcard Language Feature

• “? extends Type” is a wildcard with an upper bound; it stands for the family of types that are subtypes of Type.
• “? super Type” is a wildcard with a lower bound; it stands for the family of types that are supertypes of Type.
• “?” is an unbounded wildcard; it stands for “all types”.

The wildcard instantiations of parameterized types can be used as argument and return types of methods, as type arguments to other parameterized types and for declaration of variables.  They can not be used for creation of objects or arrays, that is, a wildcard instantiation is not permitted in a new expression.  Wildcard instantiations are not types, they are placeholders for a member from a family of types.  In a way, a wildcard instantiation is similar to an interface:  we can declare variables of interface types, but we cannot create objects of interface types; the created objects must be of a class type that implements the interface.  Similar with wildcard instantiations: we can declare variables of a wildcard instantiated type, but we cannot create objects of such a type; the created objects must be of a concrete instantiation from the family of instantiations designated by the wildcard instantiation.  Here is an example:

LinkedList<?> list1 = new LinkedList<String>();  // fine
LinkedList<?> list2 = new LinkedList<?>();  // error: cannot create objects of a wildcard type

LinkedList<? extends Shape> list3 = new LinkedList<Triangle>(); // fine
LinkedList<? extends Shape> list4 = new LinkedList<String>(); // error: does not belong to the family
 

1.2.1 Access Restrictions

1.2.1.1 Rules for Unbounded Wildcards

List<?> list = new LinkedList<String>();

void f(List<?> list) {
   list.add(new Date());  // error: must not invoke methods that take arguments of the „?“ type
}

The general rule is that through a reference variable of an unbounded wildcard type we cannot invoke any method of the referenced object that takes an argument of the unknown type that the “?” wildcard stands for.  The only exception from this rule is invocation with null as an argument, because null has no type.  Hence the following invocation would be permitted:

void f(List<?> list) {
   list.add(null);  // fine
}

void f(List<?> list) {
   Object ret = list.get(0); // fine
}

1.2.1.2 Rules for Upper Bound Wildcards

void f(List<? extends Shape> list) {
   list.add(new Triangle());  // error: must not invoke methods that take arguments of the „? extends Shape“ type
}

Again, retrieving an element from the list is safe, because all elements in the list are guaranteed to be Shapes.

void f(List<? extends Shape> list) {
   Shape ret = list.get(0);   // fine
}

1.2.1.3 Rules for Lower Bound Wildcards

void f(List<? super Triangle> list) {
   Triangle ret = list.get(0); // error: must not invoke methods that return the „? super Triangle“ type
   Object   obj = list.get(0); // fine
}

Addition of elements to the list is permitted, but it must be visible to the compiler that the elements are within bounds.  Here is an example:

void f(List<? super Triangle> list) {
   list.add(new Triangle());  // fine

   Shape shape = new Triangle();
   list.add(shape);  // error: argument must be of type Triangle
}

2 Using Wildcard Instantiations

2.1 Using Wildcards With An Upper Bound

public void drawAllShapes(Collection<? extends Shape> c) {
   for (Shape s : c) {
      s.draw();
   }
}
Collection<Triangle> c = new LinkedList<Triangle>();
... fill the collection with triangles ...
drawAllShapes(c);

Programmers familiar with parameterized methods might have noticed that the same effect can be achieved without wildcards as well:  if we declare the drawAllShapes() method as a parameterized method we would also allow collections of subtypes of Shape as arguments.  The parameterization would look like this:

public <T extends Shape> void drawAllShapes(Collection<T> c) {
   for (Shape s : c) {
      s.draw();
   }
}

2.2 Using Unbounded Wildcards

void printAll(Collection<?> c) {
   for (Object o : c)  System.out.println(o.toString());
}

Note the difference between use of a Collection<?> and use of a Collection<Object>: a method declared as void printAll(Collection<Object> c) would not accept a LinkedList<String> as an argument, while a method declared as void printAll(Collection<?> c) permits it.  Both expressions look like they denote a “collection of anything”.  The difference is that Collection<Object> is a concrete type, while Collection<?> is not a type.  It just stands for a representative from the family of types that are instantiations of Collection.  Hence a method parameter declared as Collection<Object> must be of exactly that type, or a subtype thereof.  A method parameter declared as Collection<?> can be of any type that is an instantiation of Collection, or a subtype of any of these types.

The type Collection<?>  is also different from the raw type Collection.  Invocation of methods that would be flagged as errors when invoked via a reference of type Collection<?> would lead to “unchecked warning” when invoked via a reference of type Collection.  Also, the raw type is a concrete type, of which objects and arrays can be created, while Collection<?>  must not appear in new expressions.

Unbounded wildcards are also used for partial instantiations and express that no requirements are imposed on a type. Here is an example.  Say, we have a parameterized pair class with two fields of different unknown types:

class Pair<S,T> {
   private S first;
   private T second;
   ...
   <A extends S> void setFirst(Pair<A,?> p) {
     first = p.first;
   }
   ...
}

2.3 Using Wildcards With A Lower Bound

class Person {
   private String firstName;
   private String lastName;
   private Date   dateOfBirth;
   ...
}
class Employee extends Person {
   private Person Supervisor;
   ...
}

class Person implements Comparable<Person> {
   private String firstName;
   private String lastName;
   private Date   dateOfBirth;
   ...
   public int compareTo(Person other) {
     ...
   }
}
class Employee extends Person implements Comparable<Employee> {  // error: already implements Comparable
   private Person Supervisor;
   ...
   public int compareTo(Employee other) {
     ...
   }
}

The result is that the superclass determines which instantiation of a parameterized interface all its subclasses implement.  This, on the other hand, renders it impossible to pass the subclass to certain methods, unless the methods use wildcards with lower bounds.  Below is an example of such a method. But  let us first fix our class hierarchy, so that all classes in the hierarchy of  Person classes would implement Comparable<Person>:

class Person implements Comparable<Person> {
   private String firstName;
   private String lastName;
   private Date   dateOfBirth;
   ...
   public int compareTo(Person other) {
     ...
   }
}
class Employee extends Person {
   private Person Supervisor;
   ...
   public int compareTo(Person other) {
     ...
   }
}

<T extends Comparable<T>> void someMethod(T arg1, T arg2) {
   ... arg1.compareTo(arg2) ...
}

Person p1 = new Employee(“Peter”, “Miller”, new Date(4,3,69));
Person p2 = new Employee(“Jim”, “Anderson”, new Date(10,8,84));

someMethod(p1, p2);  // fine

Employee e1 = new Employee(“Peter”, “Miller”, new Date(4,3,69));
Employee e2 = new Employee(“Jim”, “Anderson”, new Date(10,8,84));

someMethod(e1, e2);  // error:  arguments are not within bounds

Let us relax the method signature. If we declare the method using an upper bound wildcard instantiation – instead of the concrete instantiation - the method accepts super- and subclass objects as arguments, that is, Person and Employee objects would be permitted.

<T extends Comparable<? super T>> void someMethod(T arg1, T arg2) {
   ... arg1.compareTo(arg2) ...
}

Note also, that lower bound wildcards – different from upper bound wildcards – cannot be replaced by a parameterization of the method itself.  This is because type variables can only have upper bounds, but no lower bounds, while for wildcards both variants exist.

2.3.1 Remaining Limitations

interface Copyable<T> {
   T copy();
}
class Person implements Copyable<Person> {
   ...
   public Person copy() { ... }
}
class Employee extends Person {
...
   public Employee copy() { ... }
}

<T extends Copyable<T>> T produceCopy(T arg) {
   return arg.copy();
}

Person p1 = new Employee(“Peter”, “Miller”, new Date(4,3,69));

Person p2 = produceCopy(p1);// fine

Employee e1 = new Employee(“Peter”, “Miller”, new Date(4,3,69));

Employee e2 = produceCopy(e1); // error:  arguments are not within bounds

<T extends Copyable<? super T>> T produceCopy(T arg) {
   return arg.copy();  // error: type „? super T“ incompatible with type T
}

3 Summary

4 References

If you are interested to hear more about this and related topics you might want to check out the following seminar:

Seminar   Effective Java - Advanced Java Programming Idioms  5 day seminar (open enrollment and on-site)