Bounded types

Written Explanation

The problem: T can do too little

Try to write max for any two values:

static <T> T max(T a, T b) {
    return a.compareTo(b) >= 0 ? a : b;
}

It does not compile:

error: cannot find symbol
        return a.compareTo(b) >= 0 ? a : b;
  symbol:   method compareTo(T)
  location: variable a of type T

The compiler is right. T could be a Contact, an Event, or anything. Not every class has a way to compare itself, so compareTo cannot be allowed.

Upper bounds with extends

You restrict T by writing extends and a type after its name:

static <T extends Number> double average(List<T> nums) {
    double total = 0;
    for (T n : nums) {
        total += n.doubleValue();   // allowed: every Number has doubleValue()
    }
    return total / nums.size();
}

T extends Number means: T must be Number or a subclass of it (Integer, Double, Long, ...). Two things follow:

1. Callers are limited. average(List.of(1, 2, 4)) and average(List.of(1.5, 2.5)) work. average(List.of("a", "b")) is rejected, because String is not a Number.
2. The body gains abilities. Since T is at least a Number, you may call Number's methods, such as doubleValue(), on a T.

This is the Oracle tutorial's description of bounded type parameters: restrict the types allowed as type arguments, and gain access to the bound's methods.

The word extends is used here for both classes and interfaces. In a bound it means "is a subtype of": it covers "extends" for a class and "implements" for an interface. You never write implements inside the angle brackets.

The most common bound: Comparable<T>

Comparable<T> is a JDK interface with one method, int compareTo(T other). A class that implements it says "I know how to compare myself with another T". It returns a negative number if this object is less than the other, zero if they are equal, and a positive number if it is greater. Integer, Double, and String implement it, so they have a natural order.

To use it as a bound:

static <T extends Comparable<T>> T max(T a, T b) {
    return a.compareTo(b) >= 0 ? a : b;
}

Read the bound aloud: "T is some type that can be compared with T". The T appears twice because the comparison must be between two values of the same type: an Integer compares with an Integer, a String with a String. You cannot compare an Integer with a String, and the signature makes that impossible.

Now it works for many types and rejects the others:

Utils.max(3, 9);            // 9
Utils.max("pear", "apple"); // pear (compared alphabetically)
Utils.max(List.of(4.5, 2.0, 8.25)); // with a list version: 8.25

A class of your own, such as Contact, is rejected unless it implements Comparable<Contact>. The compiler's message mentions upper bounds: Comparable<T#1> and lower bounds: Contact.

Bounds on classes

A class can bound its parameter in the same way. A Range that tells whether a value lies between a low and a high end needs comparison:

public class Range<T extends Comparable<T>> {
    private final T low;
    private final T high;

    public Range(T low, T high) {
        if (low.compareTo(high) > 0) {
            throw new IllegalArgumentException("low must not exceed high");
        }
        this.low = low;
        this.high = high;
    }

    public boolean contains(T value) {
        return value.compareTo(low) >= 0 && value.compareTo(high) <= 0;
    }
}

Range<Integer> and Range<String> are valid. Range<Object> is not, because Object does not implement Comparable.

More than one bound

A parameter can have several bounds, joined with &:

static <T extends Number & Comparable<T>> T largestAbove(List<T> nums, T limit)

Here T must be both a Number and comparable to itself, so the body can call both doubleValue() and compareTo. If one of the bounds is a class, it must come first; any further bounds must be interfaces. Multiple bounds are less common. You will mostly see a single bound.

A note on what bounds do not do

A bound does not change what the compiler treats as the same type. List<Integer> is still not a List<Number>, even if T extends Number. A method taking List<T> with T extends Number still ties all its list elements to one concrete T. Lesson 5 shows how wildcards loosen this.