Earlier, we showed how new and legacy code can interoperate. Now, it's time to look at the harder problem of "generifying" old code.

If you decide to convert old code to use generics, you need to think carefully about how you modify the API.

You need to make certain that the generic API is not unduly restrictive; it must continue to support the original contract of the API. Consider again some examples from java.util.Collection. The pre-generic API looks like:

interface Collection {
    public boolean containsAll(Collection c);
    public boolean addAll(Collection c);
}

A naive attempt to generify it would be the following:

interface Collection<E> {

    public boolean containsAll(Collection<E> c);
    public boolean addAll(Collection<E> c);
}

While this is certainly type safe, it doesn't live up to the API's original contract. The containsAll() method works with any kind of incoming collection. It will only succeed if the incoming collection really contains only instances of E, but:

• The static type of the incoming collection might differ, perhaps because the caller doesn't know the precise type of the collection being passed in, or perhaps because it is a Collection<S>,where S is a subtype of E.
• It's perfectly legitimate to call containsAll() with a collection of a different type. The routine should work, returning false.

In the case of addAll(), we should be able to add any collection that consists of instances of a subtype of E. We saw how to handle this situation correctly in section Generic Methods.

You also need to ensure that the revised API retains binary compatibility with old clients. This implies that the erasure of the API must be the same as the original, ungenerified API. In most cases, this falls out naturally, but there are some subtle cases. We'll examine one of the subtlest cases we've encountered, the method Collections.max(). As we saw in section More Fun with Wildcards, a plausible signature for max() is:

public static <T extends Comparable<? super T>> 
        T max(Collection<T> coll)

This is fine, except that the erasure of this signature is:

public static Comparable max(Collection coll)

which is different than the original signature of max():

public static Object max(Collection coll)

One could certainly have specified this signature for max(), but it was not done, and all the old binary class files that call Collections.max() depend on a signature that returns Object.

We can force the erasure to be different, by explicitly specifying a superclass in the bound for the formal type parameter T.

public static <T extends Object & Comparable<? super T>> 
        T max(Collection<T> coll)

This is an example of giving multiple bounds for a type parameter, using the syntax T1 & T2 ... & Tn. A type variable with multiple bounds is known to be a subtype of all of the types listed in the bound. When a multiple bound is used, the first type mentioned in the bound is used as the erasure of the type variable.

Finally, we should recall that max only reads from its input collection, and so is applicable to collections of any subtype of T.

This brings us to the actual signature used in the JDK:

public static <T extends Object & Comparable<? super T>> 
        T max(Collection<? extends T> coll)

It's very rare that anything so involved comes up in practice, but expert library designers should be prepared to think very carefully when converting existing APIs.

Another issue to watch out for is covariant returns, that is, refining the return type of a method in a subclass. You should not take advantage of this feature in an old API. To see why, let's look at an example.

Assume your original API was of the form:

public class Foo {
    public Foo create() {
        ...
    } // Factory. Should create an instance of whatever class it is declared in.
}

public class Bar extends Foo {
    public Foo create() {
        ...
    } // Actually creates a Bar.
}

Taking advantage of covariant returns, you modify it to:

public class Foo {
    public Foo create() {
        ...
    } // Factory. Should create an instance of whatever class it is declared in.
}

public class Bar extends Foo {
    public Bar create() {
        ...
    } // Actually creates a Bar.
}

Now, assume a third party client of your code wrote the following:

public class Baz extends Bar {
    public Foo create() {
        ...
    } // Actually creates a Baz.
}

The Java virtual machine does not directly support overriding of methods with different return types. This feature is supported by the compiler. Consequently, unless the class Baz is recompiled, it will not properly override the create() method of Bar. Furthermore, Baz will have to be modified, since the code will be rejected as written--the return type of create() in Baz is not a subtype of the return type of create() in Bar.