generic types and methods

the picture

you know how a method has parameters, so one method body works for any value you pass in? a type parameter is the same trick, one level up: one class body that works for any type you pass in.

think of a printed form with a blank: "this box holds ______". the form is the class. filling the blank (String) gives you a specific kind of box, and from then on the clerk (javac) checks everything you put in against what's written there. the form itself never changes, however many ways it gets filled in.

the vocabulary, since people mix it up: in class Box<T>, T is the type parameter. in Box<String>, String is the type argument, and Box<String> is a parameterized type. Box by itself, with nothing in the brackets, is the raw type (why that's bad).

a whole generic class

here's a real one, with a generic method inside it. map declares its own type parameter R, separate from the class's T, because the result can be a different type than the contents:

class Box<T> {
    private final T value;
 
    Box(T value) { this.value = value; }
 
    T get() { return value; }
 
    <R> Box<R> map(Function<T, R> f) { return new Box<>(f.apply(value)); }
 
    public String toString() { return "Box[" + value + "]"; }
}
 
void main() {
    Box<String> name = new Box<>("ada");
    Box<Integer> len = name.map(String::length);   // R = Integer
    int n = len.get();                             // no cast
    IO.println(name + " " + len + " " + n);
}

Box[ada] Box[3] 3

T is fixed per object: name is a Box<String> for its whole life. R is fixed per call: every call to map can pick a different one. (the real JDK version of this, Optional.map, takes a Function<? super T, ? extends R>. those question marks are wildcards, and they make it accept more functions.)

the usual names are single capital letters, so you can tell a type parameter from a class at a glance:

T, U, S

a type. the first, second, third one.

E

an element of a collection: List<E>, Set<E>.

K, V

key and value: Map<K, V>.

R

a result: Function<T, R>.

X

an exception type, like the X in Optional.orElseThrow.

generic methods

a method can have type parameters of its own, even in a class that has none. the <T> goes right before the return type, and it's in scope for the parameters, the return type and the body:

static <T> List<T> repeat(T x, int times) {
    List<T> out = new ArrayList<>();
    for (int i = 0; i < times; i++) out.add(x);
    return out;
}
 
void main() {
    List<String> hey = repeat("hey", 3);                 // T = String
    List<Character> dots = repeat('.', 2);               // T = Character (boxed)
    List<Number> zeros = repeat(0, 2);                   // T = Number, from the target
    var empty = Collections.<String>emptyList();         // T = String, said out loud
    IO.println(hey + " " + dots + " " + zeros + " " + empty.size());
}

[hey, hey, hey] [., .] [0, 0] 0

nobody wrote a type argument on the first three calls. javac worked out T each time. and look at zeros: the argument is an Integer, but T came out as Number, because the result was going into a List<Number>. inference doesn't just look at the arguments.

how inference picks T

javac treats T like an unknown in an equation. every argument adds a clue ("T must be able to hold an Integer"), the target adds another ("the result must be a List<Number>"), and then it solves for the one type that satisfies all of them. try it on List.of, whose element type is called E:

the rules, roughly: if the target pins E down exactly, that's the answer (as long as the arguments fit). otherwise E is the most specific type that's a supertype of every argument (the least upper bound), which can be an intersection like Number & Comparable<...> that you could never type yourself. and with no clues at all, E is just its bound, Object.

var list = new ArrayList<>();
list.add("ada");
list.add(42);
IO.println(list);

the diamond, and where it gets smart

<> (java 7) is inference for constructors. new HashMap<>() asks javac to fill the type arguments from the target, exactly like a generic method call. since java 9 it also works on anonymous classes, as long as the inferred type is something you could have written:

Comparator<String> byLength = new Comparator<>() {     // java 9+
    public int compare(String a, String b) { return a.length() - b.length(); }
};