In any nontrivial software project, bugs are simply a fact of life. Careful planning, programming, and testing can help reduce their pervasiveness, but somehow, somewhere, they’ll always find a way to creep into your code. This becomes especially apparent as new features are introduced and your code base grows in size and complexity.
Fortunately, some bugs are easier to detect than others. Compile-time bugs, for example, tell you immediately that something is wrong; you can use the compiler’s error messages to figure out what the problem is and fix it, right then and there. Runtime bugs, however, can be much more problematic; they don’t always surface immediately, and when they do, it may be at a point in time that’s far removed from the actual cause of the problem.
Generics add stability to your code by making more of your bugs detectable at compile time. Some programmers choose to learn generics by studying the Java Collections Framework; after all, generics are heavily used by those classes. However, since we haven’t yet covered collections, this chapter will focus primarily on simple “collectionslike” examples that we’ll design from scratch. This hands-on approach will teach you the necessary syntax and terminology while demonstrating the various kinds of problems that generics were designed to solve.
Let’s begin by designing a nongeneric Box
class that operates on objects of any type. It need only provide two methods: add
, which adds an object to the box, and get
, which retrieves it:
public class Box { private Object object; public void add(Object object) { this.object = object; } public Object get() { return object; } }
Since its methods accept or return Object
, you’re free to pass in whatever you want, provided that it’s not one of the primitive types. However, should you need to restrict the contained type to something specific (like Integer
), your only option would be to specify the requirement in documentation (or in this case, a comment), which of course the compiler knows nothing about:[1]
public class BoxDemo1 { public static void main(String[] args) { // ONLY place Integer objects into this box! Box integerBox = new Box(); integerBox.add(new Integer(10)); Integer someInteger = (Integer)integerBox.get(); System.out.println(someInteger); } }
The BoxDemo1
program creates an Integer
object, passes it to add
, then assigns that same object to someInteger
by the return value of get
. It then prints the object’s value (10) to standard output. We know that the cast from Object
to Integer
is correct because we’ve honored the “contract” specified in the comment. But remember, the compiler knows nothing about this—it just trusts that our cast is correct. Furthermore, it will do nothing to prevent a careless programmer from passing in an object of the wrong type, such as String
:[2]
public class BoxDemo2 { public static void main(String[] args) { // ONLY place Integer objects into this box! Box integerBox = new Box(); // Imagine this is one part of a large application // modified by one programmer. integerBox.add("10"); // note how the type is now String // ... and this is another, perhaps written // by a different programmer Integer someInteger = (Integer)integerBox.get(); System.out.println(someInteger); } }
Here we’ve stored the number 10 as a String
, which could be the case when, say, a GUI collects input from the user. However, the existing cast from Object
to Integer
has mistakenly been overlooked. This is clearly a bug, but because the code still compiles, you wouldn’t know anything is wrong until runtime, when the application crashes with a ClassCastException
:
Exception in thread "main" java.lang.ClassCastException: java.lang.String cannot be cast to java.lang.Integer at BoxDemo2.main(BoxDemo2.java:6)
If the Box
class had been designed with generics in mind, this mistake would have been caught by the compiler, instead of crashing the application at runtime.
Let’s update our Box
class to use generics. We’ll first create a generic type declaration by changing the code “public class Box
” to “public class Box<T>
”; this introduces one type variable, named T
, that can be used anywhere inside the class. This same technique can be applied to interfaces as well. There’s nothing particularly complex about this concept. In fact, it’s quite similar to what you already know about variables in general. Just think of T
as a special kind of variable, whose “value” will be whatever type you pass in; this can be any class type, any interface type, or even another type variable. It just can’t be any of the primitive data types. In this context, we also say that T
is a formal type parameter of the Box
class:
/** * Generic version of the Box class. */ public class Box<T> { private T t; // T stands for "Type" public void add(T t) { this.t = t; } public T get() { return t; } }
As you can see, we’ve replaced all occurrences of Object
with T
. To reference this generic class from within your own code, you must perform a generic type invocation, which replaces T
with some concrete value, such as Integer
:
Box<Integer> integerBox;
You can think of a generic type invocation as being similar to an ordinary method invocation, but instead of passing an argument to a method, you’re passing a type argument—Integer
in this case—to the Box
class itself. Like any other variable declaration, this code does not actually create a new Box
object. It simply declares that integerBox
will hold a reference to a “Box
of Integer
,” which is how Box<Integer>
is read.
An invocation of a generic type is generally known as a parameterized type. To instantiate this class, use the new
keyword, as usual, but place <Integer>
between the class name and the parenthesis:
integerBox = new Box<Integer>();
Or, you can put the entire statement on one line, such as:
Box<Integer> integerBox = new Box<Integer>();
Once integerBox
is initialized, you’re free to invoke its get
method without providing a cast, as in BoxDemo3
:[3]
public class BoxDemo3 { public static void main(String[] args) { Box<Integer> integerBox = new Box<Integer>(); integerBox.add(new Integer(10)); Integer someInteger = integerBox.get(); // no cast! System.out.println(someInteger); } }
Furthermore, if you try adding an incompatible type to the box, such as String
, compilation will fail, alerting you to what previously would have been a runtime bug:
BoxDemo3.java:5: add(java.lang.Integer) in Box<java.lang.Integer> cannot be applied to (java.lang.String) integerBox.add("10"); ^ 1 error
It’s important to understand that type variables are not actually types themselves. In the above examples, you won’t find T.java
or T.class
anywhere on the filesystem. Furthermore, T
is not a part of the Box
class name. In fact during compilation, all generic information will be removed entirely, leaving only Box.class
on the filesystem. We’ll discuss this later in the Type Erasure section (page 178).
Also note that a generic type may have multiple type parameters, but each parameter must be unique within its declaring class or interface. A declaration of Box<T,T>
, for example, would generate an error on the second occurrence of T
, but Box<T,U>
, however, would be allowed.
By convention, type parameters are single, uppercase letters. This stands in sharp contrast to the variable naming conventions (see the Naming section, page 44) that you already know about, and with good reason: Without this convention, it would be difficult to tell the difference between a type variable and an ordinary class or interface name.
The most commonly used type parameter names are:
S
, U
, V
, etc. 2nd, 3rd, 4th types
You’ll see these names used throughout the Java SE API and the rest of this tutorial.
Type parameters can also be declared within method and constructor signatures to create generic methods and generic constructors. This is similar to declaring a generic type, but the type parameter’s scope is limited to the method or constructor in which it’s declared:
/** * This version introduces a generic method. */ public class Box<T> { private T t; public void add(T t) { this.t = t; } public T get() { return t; } public <U> void inspect(U u){ System.out.println("T: " + t.getClass().getName()); System.out.println("U: " + u.getClass().getName()); } public static void main(String[] args) { Box<Integer> integerBox = new Box<Integer>(); integerBox.add(new Integer(10)); integerBox.inspect("some text"); } }
Here we’ve added one generic method, named inspect
, that defines one type parameter, named U
. This method accepts an object and prints its type to standard output. For comparison, it also prints out the type of T
. For convenience, this class now also has a main
method so that it can be run as an application.
The output from this program is:
T: java.lang.Integer U: java.lang.String
By passing in different types, the output will change accordingly.
A more realistic use of generic methods might be something like the following, which defines a static method that stuffs references to a single item into multiple boxes:
public static <U> void fillBoxes(U u, List<Box<U>> boxes) { for (Box<U> box : boxes) { box.add(u); } }
To use this method, your code would look something like the following:
Crayon red = ...; List<Box<Crayon>> crayonBoxes = ...;
The complete syntax for invoking this method is:
Box.<Crayon>fillBoxes(red, crayonBoxes);
Here we’ve explicitly provided the type to be used as U
, but more often than not, this can be left out and the compiler will infer the type that’s needed:
Box.fillBoxes(red, crayonBoxes); // compiler infers that // U is Crayon
This feature, known as type inference, allows you to invoke a generic method as you would an ordinary method, without specifying a type between angle brackets.
There may be times when you’ll want to restrict the kinds of types that are allowed to be passed to a type parameter. For example, a method that operates on numbers might only want to accept instances of Number
or its subclasses. This is what bounded type parameters are for.
To declare a bounded type parameter, list the type parameter’s name, followed by the extends
keyword, followed by its upper bound, which in this example is Number
. Note that, in this context, extends
is used in a general sense to mean either “extends” (as in classes) or “implements” (as in interfaces):
/** * This version introduces a bounded type parameter. */ public class Box<T> { private T t; public void add(T t) { this.t = t; } public T get() { return t; } public <U extends Number> void inspect(U u){ System.out.println("T: " + t.getClass().getName()); System.out.println("U: " + u.getClass().getName()); } public static void main(String[] args) { Box<Integer> integerBox = new Box<Integer>(); integerBox.add(new Integer(10)); integerBox.inspect("some text"); // error: this is // still String! } }
By modifying our generic method to include this bounded type parameter, compilation will now fail, since our invocation of inspect
still includes a String
:
Box.java:21: <U>inspect(U) in Box<java.lang.Integer> cannot be applied to (java.lang.String) integerBox.inspect("10"); ^ 1 error
To specify additional interfaces that must be implemented, use the &
character, as in:
<U extends Number & MyInterface>
As you already know, it’s possible to assign an object of one type to an object of another type provided that the types are compatible. For example, you can assign an Integer
to an Object
, since Object
is one of Integer
’s supertypes:
Object someObject = new Object(); Integer someInteger = new Integer(10); someObject = someInteger; // OK
In object-oriented terminology, this is called an “is a” relationship. Since an Integer
is a kind of Object
, the assignment is allowed. But Integer
is also a kind of Number
, so the following code is valid as well:
public void someMethod(Number n){ // method body omitted } someMethod(new Integer(10)); // OK someMethod(new Double(10.1)); // OK
The same is also true with generics. You can perform a generic type invocation, passing Number
as its type argument, and any subsequent invocation of add
will be allowed if the argument is compatible with Number
:
Box<Number> box = new Box<Number>(); box.add(new Integer(10)); // OK box.add(new Double(10.1)); // OK
Now consider the following method:
public void boxTest(Box<Number> n){ // method body omitted }
What type of argument does it accept? By looking at its signature, we can see that it accepts a single argument whose type is Box<Number>
. But what exactly does that mean? Are you allowed to pass in Box<Integer>
or Box<Double>
, as you might expect? Surprisingly, the answer is “no,” because Box<Integer>
and Box<Double>
are not subtypes of Box<Number>
.
Understanding why becomes much easier if you think of tangible objects—things you can actually picture—such as a cage:
// A cage is a collection of things, with bars to keep them in. interface Cage<E> extends Collection<E>;
The Collection
interface is the root interface of the collection hierarchy; it represents a group of objects. Since a cage would be used for holding a collection of objects (the animals), it makes sense to include it in this example.
A lion is a kind of animal, so Lion
would be a subtype of Animal
:
interface Lion extends Animal {} Lion king = ...;
Where we need some animal, we’re free to provide a lion:
Animal a = king;
A lion can of course be put into a lion cage:
Cage<Lion> lionCage = ...; lionCage.add(king);
and a butterfly into a butterfly cage:
interface Butterfly extends Animal {} Butterfly monarch = ...; Cage<Butterfly> butterflyCage = ...; butterflyCage.add(monarch);
But what about an “animal cage”? English is ambiguous, so to be precise let’s assume we’re talking about an “all-animal cage”:
Cage<Animal> animalCage = ...;
This is a cage designed to hold all kinds of animals, mixed together. It must have bars strong enough to hold in the lions and spaced closely enough to hold in the butterflies. Such a cage might not even be feasible to build, but if it is, then:
animalCage.add(king); animalCage.add(monarch);
Since a lion is a kind of animal (Lion
is a subtype of Animal
), the question then becomes, “Is a lion cage a kind of animal cage? Is Cage<Lion>
a subtype of Cage<Animal>
?” By the above definition of animal cage, the answer must be “no.” This is surprising! But it makes perfect sense when you think about it: A lion cage cannot be assumed to keep in butterflies, and a butterfly cage cannot be assumed to hold in lions. Therefore, neither cage can be considered an “all-animal” cage:
animalCage = lionCage; // compile-time error animalCage = butterflyCage; // compile-time error
Without generics, the animals could be placed into the wrong kinds of cages, where it would be possible for them to escape.
Earlier we mentioned that English is ambiguous. The phrase “animal cage” can reasonably mean “all-animal cage,” but it also suggests an entirely different concept: a cage designed not for any kind of animal, but rather for some kind of animal whose type is unknown. In generics, an unknown type is represented by the wildcard character “?
”.
To specify a cage capable of holding some kind of animal:
Cage<? extends Animal> someCage = ...;
Read “? extends Animal
” as “an unknown type that is a subtype of Animal
, possibly Animal
itself,” which boils down to “some kind of animal.” This is an example of a bounded wildcard, where Animal
forms the upper bound of the expected type. If you’re asked for a cage that simply holds some kind of animal, you’re free to provide a lion cage or a butterfly cage.
It’s also possible to specify a lower bound by using the super
keyword instead of extends
. The code <? super Animal>
, therefore, would be read as “an unknown type that is a supertype of Animal
, possibly Animal
itself.” You can also specify an unknown type with an unbounded wilcard, which simply looks like <?>
. An unbounded wildcard is essentially the same as saying <? extends Object>
.
While Cage<Lion>
and Cage<Butterfly>
are not subtypes of Cage<Animal>
, they are in fact subtypes of Cage<? extends Animal>
:
someCage = lionCage; // OK someCage = butterflyCage; // OK
So now the question becomes, “Can you add butterflies and lions directly to someCage
?” As you can probably guess, the answer to this question is “no”:
someCage.add(king); // compiler-time error someCage.add(monarch); // compiler-time error
If someCage
is a butterfly cage, it would hold butterflies just fine, but the lions would be able to break free. If it’s a lion cage, then all would be well with the lions, but the butterflies would fly away. So if you can’t put anything at all into someCage
, is it useless? No, because you can still read its contents:
void feedAnimals(Cage<? extends Animal> someCage) { for (Animal a : someCage) a.feedMe(); }
Therefore, you could house your animals in their individual cages, as shown earlier, and invoke this method first for the lions and then for the butterflies:
feedAnimals(lionCage); feedAnimals(butterflyCage);
Or, you could choose to combine your animals in the all-animal cage instead:
feedAnimals(animalCage);
When a generic type is instantiated, the compiler translates those types by a technique called type erasure—a process where the compiler removes all information related to type parameters and type arguments within a class or method. Type erasure enables Java applications that use generics to maintain binary compatibility with Java libraries and applications that were created before generics.
For instance, Box<String>
is translated to type Box
, which is called the raw type—a raw type is a generic class or interface name without any type arguments. This means that you can’t find out what type of Object
a generic class is using at runtime. The following operations are not possible:
public class MyClass<E> { public static void myMethod(Object item) { if (item instanceof E) { // Compiler error ... } E item2 = new E(); // Compiler error E[] iArray = new E[10]; // Compiler error E obj = (E)new Object(); // Unchecked cast warning } }
The operations shown in bold are meaningless at runtime because the compiler removes all information about the actual type argument (represented by the type parameter E
) at compile time.
Type erasure exists so that new code may continue to interface with legacy code. Using a raw type for any other reason is considered bad programming practice and should be avoided whenever possible.
When mixing legacy code with generic code, you may encounter warning messages similar to the following:
Note: WarningDemo.java uses unchecked or unsafe operations. Note: Recompile with -Xlint:unchecked for details.
This can happen when using an older API that operates on raw types, as shown in the following WarningDemo
[4] program:
public class WarningDemo { public static void main(String[] args){ Box<Integer> bi; bi = createBox(); } /** * Pretend that this method is part of an old library, * written before generics. It returns * Box instead of Box<T>. */ static Box createBox(){ return new Box(); } }
Recompiling with -Xlint:unchecked
reveals the following additional information:
WarningDemo.java:4: warning: [unchecked] unchecked conversion found : Box required: Box<java.lang.Integer> bi = createBox(); ^ 1 warning
This chapter described the following problem: We have a Box
class, written to be generally useful so that it deals with Object
s. We need an instance that takes only Integer
s. The comments say that only Integer
s go in, so the programmer knows this (or should know it), but the compiler doesn’t know it. This means that the compiler can’t catch someone erroneously adding a String
. When we read the value and cast it to an Integer
we’ll get an exception, but that’s not ideal since the exception may be far removed from the bug in both space and time:
Debugging may be difficult, as the point in the code where the exception is thrown may be far removed from the point in the code where the error is located.
It’s always better to catch bugs when compiling than when running.
Specifically, you learned that generic type declarations can include one or more type parameters; you supply one type argument for each type parameter when you use the generic type. You also learned that type parameters can be used to define generic methods and constructors. Bounded type parameters limit the kinds of types that can be passed into a type parameter; they can specify an upper bound only. Wildcards represent unknown types, and they can specify an upper or lower bound. During compilation, type erasure removes all generic information from a generic class or interface, leaving behind only its raw type. It is possible for generic code and legacy code to interact, but in many cases the compiler will emit a warning telling you to recompile with special flags for more details.
For additional information, see “Generics” by Gilad Bracha.[5]
Consider the following classes:
public class AnimalHouse<E> { private E animal; public void setAnimal(E x) { animal = x; } public E getAnimal() { return animal; } } public class Animal{ } public class Cat extends Animal { } public class Dog extends Animal { }
For the following code snippets, identify whether the code:
fails to compile,
compiles with a warning,
generates an error at runtime, or
none of the above (compiles and runs without problem).
AnimalHouse<Animal> house = new AnimalHouse<Cat>();
AnimalHouse<Dog> house = new AnimalHouse<Animal>();
AnimalHouse<?> house = new AnimalHouse<Cat>(); house.setAnimal(new Cat());
AnimalHouse house = new AnimalHouse(); house.setAnimal(new Dog());
18.225.72.133