Wildcards: reading the JDK's signatures

Written Explanation

The gap that wildcards fill

You met this in lesson 2: List<Integer> is not a List<Number>. Suppose we want a method that sums numbers:

static double sum(List<Number> nums) { ... }

Then sum(List.of(1, 2, 3)) is rejected, because List.of(1, 2, 3) is a List<Integer>:

error: incompatible types: List<Integer> cannot be converted to List<Number>

The reason is safety. If a List<Integer> could be used as a List<Number>, then the method could add a Double to it, and your list of integers would contain a double. The Oracle tutorial puts it this way: generic types are not related merely because their type arguments are.

We could write one sum per type, but that is what generics are meant to avoid. A wildcard states what the method really needs.

? extends T: a producer you read from

static double sum(List<? extends Number> nums) {
    double total = 0;
    for (Number n : nums) {
        total += n.doubleValue();
    }
    return total;
}

List<? extends Number> means "a list of some type that is Number or a subtype, and I do not know which". Now List<Integer>, List<Double>, and List<Number> are all accepted:

sum(List.of(1, 2, 3));      // 6.0
sum(List.of(1.5, 2.5));     // 4.0

Inside the method, whatever comes out of the list is at least a Number, so reading is safe. Oracle's wording is that an upper bounded wildcard relaxes the restriction so a method can accept a type argument that is a given type or any subtype.

But you cannot put anything in. The list might really be a List<Integer>, or a List<Double>; the compiler cannot know which kind of number is safe to add:

List<? extends Number> nums = new ArrayList<Integer>();
nums.add(5);

error: incompatible types: int cannot be converted to CAP#1
  where CAP#1 is a fresh type-variable:
    CAP#1 extends Number from capture of ? extends Number

"CAP#1" is the compiler's name for the unknown type. Read the error as "I do not know what is allowed in, so nothing is." The one value you can add is null.

? super T: a consumer you write into

The opposite wildcard has a lower bound:

static void fillWithInts(List<? super Integer> target) {
    for (int i = 1; i <= 3; i++) {
        target.add(i);
    }
}

List<? super Integer> means "a list of Integer or of some supertype of Integer". A List<Integer>, a List<Number>, and a List<Object> all qualify, and in each of them adding an Integer is safe. This matches Oracle's lower-bounded wildcard example.

The price is on the reading side. What comes out of such a list is only known to be an Object:

List<? super Integer> sink = new ArrayList<Number>();
sink.add(5);                 // fine
Integer x = sink.get(0);     // does not compile

error: incompatible types: CAP#1 cannot be converted to Integer

? alone: I do not care about the type

List<?> means a list of unknown type. You can read items as Object and ask for the size, but you cannot add anything except null. It is right for methods that only look at the elements as objects:

static void printAll(List<?> items) {
    for (Object o : items) {
        System.out.print(o + " ");
    }
}

The rule of thumb: producer extends, consumer super

Oracle's wildcard guidelines distinguish "in" and "out" variables. The popular short form is PECS: producer extends, consumer super.

Reading real JDK signatures

Now the signatures make sense. These come from the Java SE 21 documentation:

You do not have to write the third form yourself. You only have to recognize its parts: a bound on T, a wildcard on the parameter, and ? super T inside the Comparable. It means the method accepts, for example, a collection of a subclass whose parent class implements Comparable.