Wildcard (Java)

In the Java programming language, the wildcard ? is a special kind of type argument^[1] that controls the type safety of the use of generic (parameterized) types.^[2] It can be used in variable declarations and instantiations as well as in method definitions, but not in the definition of a generic type.^[3][4] This is a form of use-site variance annotation, in contrast with the definition-site variance annotations found in C# and Scala.

Covariance for generic types

Unlike arrays (which are covariant in Java^[2]), different instantiations of a generic type are not compatible with each other, not even explicitly.^[2] For example, the declarations

Generic<Supertype> superGeneric; 
Generic<Subtype> subGeneric;

will cause the compiler to report conversion errors for both castings (Generic<Subtype>)superGeneric and (Generic<Supertype>)subGeneric.

This incompatibility can be softened by the wildcard if ? is used as an actual type parameter.^[2] Generic<?> is a supertype of all parameterizarions of the generic type Generic. This allows objects of type Generic<Supertype> and Generic<Subtype> to be safely assigned to a variable or method parameter of type Generic<?>.^[2] Using Generic<? extends Supertype> allows the same, restricting compatibility to Supertype and its children.^[5] Another possibility is Generic<? super Subtype>, which also accepts both objects and restricts compatibility to Subtype and all its parents.^[5]

Wildcard as parameter type

In the body of a generic unit, the (formal) type parameter is handled like its upper bound (expressed with extends; java.lang.Object if not constrained).^[5] If the return type of a method is the type parameter, the result (e.g. of type ?) can be referenced by a variable of the type of the upper bound (or java.lang.Object). In the other direction, the wildcard fits no other type, not even java.lang.Object: If ? has been applied as the formal type parameter of a method, no actual parameters can be passed to it. However, objects of the unknown type can be read from the generic object and assigned to a variable of a supertype of the upperbound.

Sample code for the Generic<T extends UpperBound> class:

class Generic<T extends UpperBound> {
    private T t;

    public Generic(T t) {
        this.t = t;
    }

    public void set(T t) {
        this.t = t;
    }

    public T get() {
        return t;
    }
}

Sample code that uses the Generic<T extends UpperBound> class:

Generic<UpperBound> concreteTypeReference = new Generic<>();
Generic<?> wildcardReference = concreteTypeReference;
UpperBound ub = wildcardReference.get(); // Object would also be OK

wildcardReference.set(new Object()); // type error
wildcardReference.set(new UpperBound()); // type error
concreteTypeReference.set(new UpperBound()); // OK

Bounded wildcards

A bounded wildcard is one with either an upper or a lower inheritance constraint. The bound of a wildcard can be either a class type, interface type, array type, or type variable. Upper bounds are expressed using the extends keyword and lower bounds using the super keyword. Wildcards can have at most one bound - either an upper bound or a lower bound, but not both.

Object creation with wildcard

No objects may be created with a wildcard type argument: for example, new Generic<?>() is forbidden. In practice, this is unnecessary because if one wanted to create an object that was assignable to a variable of type Generic<?>, one could simply use any arbitrary type (that falls within the constraints of the wildcard, if any) as the type argument.

However, new ArrayList<Generic<?>>() is allowed, because the wildcard is not a parameter to the instantiated type java.lang.ArrayList<E>. The same holds for new ArrayList<List<?>>().

In an array creation expression, the component type of the array must be reifiable as defined by the Java Language Specification, Section 4.7. This entails that, if the component type of the array has any type arguments, they must all be unbounded wildcards (wildcards consisting of only a ?). For example, new Generic<?>[20] is correct, while new Generic<SomeType>[20] is not.

For both cases, using no parameters is another option. This will generate a warning since it is less type-safe (see Raw type).

Example

In the Java Collections Framework, the class java.util.List<E> represents an ordered collection of objects of type E. Upper bounds are specified using extends: A List<? extends MyClass> is a list of objects of some subclass of MyClass, i.e. any object in the list is guaranteed to be of type MyClass, so one can iterate over it using a variable of type MyClass^[6]

import java.util.List;

public void doSomething(List<? extends MyClass> list) {
    for (MyClass object : list) { // OK
        // do something
    }
}

However, it is not guaranteed that one can add any object of type MyClass to that list:

import java.util.List;

public void doSomething(List<? extends MyClass> list) {
    MyClass m = new MyClass();
    list.add(m); // Compile error
}

The converse is true for lower bounds, which are specified using super: A List<? super MyClass> is a list of objects of some superclass of MyClass, i.e. the list is guaranteed to be able to contain any object of type MyClass, so one can add any object of type MyClass:

import java.util.List;

public void doSomething(List<? super MyClass> list) {
    MyClass m = new MyClass();
    list.add(m); // OK
}

However, it is not guaranteed that one can iterate over that list using a variable of type MyClass:

import java.util.List;

public void doSomething(List<? super MyClass> list) {
    for (MyClass object : list) { // Compile error
        // do something
    }
}

In order to be able to do both add objects of type MyClass to the list and iterate over it using a variable of type MyClass, a List<MyClass> is needed, which is the only type of List that is both List<? extends MyClass> and List<? super MyClass>.

The mnemonics PECS (Producer Extends, Consumer Super) from the book Effective Java by Joshua Bloch gives an easy way to remember when to use wildcards (corresponding to Covariance and Contravariance) in Java.^[5]

Type constraints in other languages

The closest equivalent feature to Java wildcard type parameters are Scala type wildcards; also denoted using a ? since Scala 3 (in Scala 2, they were denoted with _).^[7] Scala bounds work like those from Java: List[? <: Number] is equivalent to List<? extends Number>, while List[? >: Integer] is equivalent to List<? super Integer>.

In C++, generic type constraints can be expressed using concepts.^[8]

import std;

using std::derived_from;
using std::vector;

class Player {
    // ...
};

// T is required to be a type whose inheritance upper bound is Player,
// blocking any type that does not inherit from Player
template <derived_from<Player> T>
void processListOfPlayers(const vector<T>& players) {
    // ...
}

This example is equivalent to the following Java code:

import java.util.List;

class Player {
    // ...
}

public class Example {
    // T is constrained to types that inherit from Player
    public static <T extends Player> void processListOfPlayers(List<T> players) {
        // ...
    }
}

In C#, type bounds can be represented as X<out T> and X<in T> (compared to Java X<? extends T> and X<? super T> respectively) while a generic type constraint is expressed with a where clause. These are more expressive and powerful than Java wildcards.^[9]

using System;

public class MyGenericClass<T, U> 
    where T : IComparable<T>, allows ref struct
    where U : class, notnull, new()
{
    // ...
}

Kotlin, though also a JVM language, does not support Java-style type wildcards. However, it represents ? instead represented as * (for example, List<*>), as well as type bounds as X<out T> and X<in T> (compared to Java X<? extends T> and X<? super T> respectively). It otherwise has C#-style where clauses:^[10]

fun <T> copyWhenGreater(list: List<T>, threshold: T): List<String>
    where T : CharSequence, T : Comparable<T> {
    return list.filter { it > threshold }.map { it.toString() }
}

Rust also uses where clauses to bound traits.

use std::cmp::Ord;

struct MyStruct<T> where T: Ord + Default {
    value: T
}

impl<T> MyStruct<T> where T: Ord + Default {
    fn new(value: T) -> Self {
        MyStruct { value }
    }

    fn is_less_than(&self, other: &Self) -> bool {
        self.value < other.value
    }
}

See also

• Bounded quantification
• Covariance and contravariance (computer science)
• Generics in Java#Type wildcards section explains lower and upper wildcard bounds

Citations

References

• Bloch, Joshua (2018). "Effective Java: Programming Language Guide" (third ed.). Addison-Wesley. ISBN 978-0134685991.
• The Java Language Specification, Third Edition (Sun), ISBN 978-0-321-24678-3 http://java.sun.com/docs/books/jls/
• Java Tutorials, Lesson Generics http://download.oracle.com/javase/tutorial/java/generics/index.html
• Capturing Wildcards, http://bayou.io/draft/Capturing_Wildcards.html
• Typkompatibilität in Java http://public.beuth-hochschule.de/~solymosi/veroeff/typkompatibilitaet/Typkompatibilitaet.html#Joker (in German)