Java Generics “capture of ?”

1. Introduction

When we work with wildcards in generics in Java, we sometimes see a compile-time error that contains the phrase “capture of ?”.

In this article, we’ll explore what a “capture” is, in which cases we see such an error message, and how we can solve the problem.

2. What Is a Capture?

2.1. Parameterized Lists

Let’s define a method that takes a list of Numbers as a parameter:

void updateNumbers(List<Number> numbers) {
}

As the type Integer extends Number, we might want to call this method with a list of Integers:

List<Integer> integers = Arrays.asList(1, 2, 3);
updateNumbers(integers);

This code doesn’t compile because even though Integer extends Number, the parameterized list List<Integer> does not extend List<Number>. Therefore, we’ll get a compile-time error:

java: incompatible types: java.util.List<java.lang.Integer> cannot be converted to java.util.List<java.lang.Number>

2.2. Wildcards

To be able to pass a list of any type that extends Number to our method, we can change the method signature to:

void updateNumbers(List<? extends Number> numbers) {
}

This seems to work fine. However, if we want to update one of the elements of the list inside our method:

numbers.set(0, Integer.getInteger("1"));

We’ll get another compile-time error:

java: incompatible types: java.lang.Integer cannot be converted to capture#1 of ? extends java.lang.Number

Let’s understand this error message. The compiler attempts to convert the type “java.lang.Integer” to a type “capture#1 of ? extends java.lang.Number”.

Integer is the type of the element that we pass to the method, so that part of the message is straightforward. We have, however, not defined the second type anywhere ourselves. That’s where the Java compiler comes in. During the compilation process, the Java compiler creates a new, temporary type for us that represents the generic parameter with the wildcard. 

We can see even better what happens when we call set() several times:

numbers.set(0, Integer.getInteger("1"));
numbers.set(1, Long.valueOf(20));
numbers.set(2, 30);

Here, the compiler produces the following error messages:

java: incompatible types: java.lang.Integer cannot be converted to capture#1 of ? extends java.lang.Number
java: incompatible types: java.lang.Long cannot be converted to capture#2 of ? extends java.lang.Number
java: incompatible types: int cannot be converted to capture#3 of ? extends java.lang.Number

We see that for every call to the set() method, the compiler has created a dedicated, internal type with a counter (note the #1, #2, and #3) as part of the name.

Simply put, a capture is an internal type that the compiler creates to represent a generic type that uses a wildcard.

In the following sections, we’ll look at the reasons for this behavior and how we can solve the compilation error.

3. Type Safety

3.1. Raw Lists and Casting

The reason for the compile-time error we saw is type safety. Generics were introduced to guarantee type-safety at compile type. If we define a raw list:

List numbers = new ArrayList();

We can add elements of any type to that list:

numbers.add("a string");

As a result, the compiler cannot know which types the list actually contains and can only assume all elements are of type Object. Therefore, we can’t call any method that belongs to the class Integer on elements of our list:

List numbers = new ArrayList();
numbers.add(1);
numbers.add(2);
numbers.add(3);

int integer = numbers.get(0); // compilation error

We can get the code to compile using a cast:

int integer = (int) numbers.get(0);

However, a cast isn’t type-safe, as we cannot be sure that the list contains only integers.

3.2. Using Wildcards

Let’s revisit our example where we pass a list of integers to the update method:

List<Integer> integers = Arrays.asList(1, 2, 3);
updateNumbers(integers);

And the method:

void updateNumbers(List<? extends Number> numbers) {
    numbers.set(0, Double.valueOf(1.2));
    numbers.set(1, Long.valueOf(20));
}

Here, we pass a list of Integers to a method that accepts a list of anything that extends Number. That’s fine. However, we cannot add values of type Double or Long.

The compiler doesn’t allow us to add an element of any type to the list; within the method, it only knows that it’s a list of elements that extend number, but doesn’t know the exact type.

3.3. Solving the Error Using Type Parameters

We can solve the problem using type parameters:

public <T extends Number> void updateNumbers(List<T> numbers, T element, int index) {
    numbers.set(index, element);
}

Now, the compiler knows that the list is of one specific type T which extends Number, and that the type of the element is the same as the type of the list.

4. Arrays and Type Safety

We can better understand why type-safety at compile time is an important feature by looking at the following method that takes an array as input:

public static void updateArrayOfNumbers(Number[] numbers) {
    numbers[0] = 10;
    numbers[1] = 2.3;
}

Unlike the generic version of this method, the code compiles. However, if we call the method:

methodWithArray(new Integer[]{1, 2, 3});

We’ll get an ArrayStoreException exception at runtime:

Exception in thread "main" java.lang.ArrayStoreException: java.lang.Double

This example shows why the Java compiler is very strict when using wildcards with generics.

5. More Wildcards

In Java, we can define unbounded wildcards, upper-bounded wildcards, and lower-bounded wildcards:

List<?> unboundedList;
List<? extends Number> upperBoundedList;
List<? super Number> lowerBoundedList;

In this article, we’ve only covered upper-bounded wildcards, however, the same compile-time error can occur with unbounded and lower-bounded wildcards as well.

6. Conclusion

A compiler error message that contains the phrase “capture of ?” is best understood if we understand the underlying concepts of generics in Java.

In this article, we’ve learned that such an error message occurs when the compiler cannot guarantee type safety when we use wildcards. We also saw how we can solve the problem using type parameters.