Table Of Contents
Acknowledgements
Change Log
Copyright Notice

• Fundamentals of Java Generics
• Language Features of Java Generics
• Practicalities - Programming With Java Generics
• Technicalities - Under the Hood of the Compiler

"Language Features of Java Generics" is a huge section that explains all language features of Java Generics: 

• Generic Types
• Generic Methods
• Type Parameters
• Type Arguments

"Practicalities - Programming With Java Generics" aims to address issues that arise when you use Java Generics in practice.  It discusses topics such as "How do I design a generics API?" , "Should my class be generic or not?", "What happens when I mix generic and non-generic Java?", "Why is class Class generic and what is this good for?".  The focus is on programming techniques on the one hand and pitfalls and surprises on the other hand.  It is likely that this section will grow over time as programming idioms and techniques using Java Generics will be discovered. 

"Technicalities - Under the Hood of the Compiler" addresses more advanced and more esoteric aspects of Java Generics, which will become the more interesting the more you learn about Java Generics.  Some of these topics are typically of little interest when you begin using generics. For instance, the section explains what the notorious "unchecked" warnings are, what translation by type erasure is, what wildcard capture and type inference are, what the type system looks like now that it includes generic types, and how overload resolution works in presence of generic methods. 

In addition to these four main sections the FAQ has a Table Of Contents , a reference to More Information on Java Generics such as tutorials, books, articles, and websites, a Glossary , and an alphabetic Index .

I've found that many readers underestimate the reference section - to their own detriment.  The cross references refer to related items and point in particular to entries that explain terms or facts mentioned in the text, but not explained there.  In other words, if there is something in the explanation that has not been explained yet, go to the reference section and see whether you can find a reference to a corresponding entry that explains it.  If not, let me know.

The FAQ is supposed to grow and mature over time.  In particular the section on programming techniques using generics will hopefully gain weight as the body of experience with Java generics grows.  If you have a technique or observation made in practice that you want to share with other programmers, feel free to send email and suggest it for inclusion in the FAQ. 

For instance, when the language features are explained the term type erasure will be mentioned.  Type erasure is part of what the compiler does during compilation and it is discussed in detail in the Technicalities section.  So you will probably jump forward to the explanation of type erasure to see what it is in principle, spare yourself the details, and return to the language feature from which you started your excursion to the Technicalities section. 

Beyond that, the FAQ is mainly intended as a reference and can be consulted any order you feel like.  Related topics are grouped together so that it might be convenient to read certain sections that are of immediate interest and ignore the rest for the time being. 

You might find that the same fact is explained repeatedly in different entries.  This is intended. A certain amount of redundency is inevitable in order to make it possible to use the FAQ as a reference.  If you feel you already know this, skip it and move on. 

Also, if you use the FAQ as a reference, the table of contents and the index should help finding what you are looking for.  If not, let me know.

Fundamentals of Java Generics

Language Features of Java Generics

Generic Types

Fundamentals
Concrete Instantiations
Raw Types
Wildcard Instantiations

Generic Methods

Fundamentals

Type Parameters

Fundamentals
Type Parameter Bounds
Usage
Scope
Static Context

Type Arguments

Fundamentals
Wildcards
Wildcard Bounds

Practicalities - Programming With Java Generics

Using Generic Types
Using Generic Methods
Coping With Legacy
Defining Generic Types and Methods
Designing Generic Methods
Working With Generic Interfaces
Implementing Infrastructure Methods
Using Runtime Type Information
Reflection

Technicalities - Under the Hood of the Compiler

Compiler Messages
Heap Pollution
Type Erasure
Type System
Exception Handling
Static Context
Type Argument Inference
Wildcard Capture
Wildcard Instantiations
Cast and instanceof

More Information on Java Generics

Glossary

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

How is this FAQ organized at large?
How are the individual answered questions organized?
Whom is the FAQ for?
How do I best read the FAQ - top-to-bottom or zig-zag?
Whom do I contact when I have questions, comments or suggestions related to this FAQ?

What are Java generics?
What is the primary purpose of Java generics?
What is the benefit of using Java generics?
What does type-safety mean?

Which language features are related to Java generics?



Generic Types

Fundamentals

• What is a generic or parameterized type?
• How do I define a generic type?
• Are there any types that cannot have type parameters?
• How is a generic type instantiated (to form a parameterized type)?
• Why do instantiations of a generic type share the same runtime type?
• Can I cast to a parameterized type?
• Can I use parameterized types in exception handling?
• Can generic types have static members?

Concrete Instantiations

• What is a concrete instantiation of a generic type?
• Are different concrete instantiations of the same generic type compatible?
• Can I use a concrete parmeterized type like any other type?
• Can I create an array whose component type is a concrete parameterized type?
• Can I declare a reference variable of an array type whose component type is a concrete parameterized type?
• How can I work around the restriction that there are no arrays whose component type is a concrete parameterized type?
• Why is there no class literal for the concrete parameterized type?

Raw Types

• What is the raw type?
• Can I use a raw type like any other type?

Wildcard Instantiations

• What is a wildcard instantiation of a generic type?
• What is an unbounded wildcard instantiation of a generic type?
• Which methods and fields are accessible/inaccessible through a reference variable of a wildcard parameterized type?
• What is the difference between the unbounded wildcard parameterized type and the raw type?
• Can I use a wildcard parameterized type like any other type?
• Can I create an object whose type is a wildcard parameterized type?
• Can I create an array whose component type is a wildcard parameterized type?
• Can I declare a reference variable of an array type whose component type is a bounded wildcard parameterized type?
• Why is it allowed to create an array whose component type is an unbounded wildcard parameterized type ?
• Can I declare a reference variable of an array type whose component type is an unbounded wildcard parameterized type?
• Can I derive from a wildcard instantiation of a parameterized type?
• Why is there no class literal for wildcard parameterized types ?




Generic Methods

Fundamentals
• What is a generic method?
• How do I invoke a generic method?

 


Type Parameters

Fundamentals
• What is a type parameter?
• Where is a type parameter visible (or invisible)?
Type Parameter Bounds
• What is a bounded type parameter?
• Which types are permitted as type parameter  bounds?
• Can I use a type parameter as a type parameter bound?
• Can I use different instantiations of a same generic type as bounds of a type parameter?
• How can I work around the restriction that a type parameter cannot have different instantiations of a same generic type as its bounds?
• Does a bound that is a class type give access to all its public members?
• How do I decrypt " Enum<E extends Enum<E>> "?
• Why is there no lower bound for type parameters?
Usage
• Can I use a type parameter like a type?
• Can I create an object whose type is a type parameter?
• Can I create an array whose component type is a type parameter?
• Can I cast to the type that the type parameter stands for?
• Can I use a type parameter in exception handling?
• Can I derive from a type parameter?
• Why is there no class literal for a type parameter?
Scope
• Where is a type parameter visible (or invisible)?
• Can I use a type parameter as part of its own bounds or in the declaration of other type parameters?
Static Context
• Is there one instances of a static field per instantiation of a generic type?
• Why can't I use a type parameter in any static context of the generic class?




Type Arguments

Fundamentals
• What is a type argument?
• Which types are permitted as type arguments?
• Are primitive types permitted as type arguments?
• Are wildcards permitted as type arguments?
• Are type parameters permitted as type arguments?
• Do I have to specify a type argument when I want to use a generic type?
• Do I have to specify a type argument when I want to invoke a generic method?
Wildcards
• What is a wildcard?
• What is an unbounded wildcard?
• What is a bounded wildcard?
• What do multi-level wildcards mean?
• If a wildcard appears repeatedly in a type argument section, does it stand for the same type?
Wildcard Bounds
• What is a wildcard bound?
• Which types are permitted as wildcard bounds?
• What is the difference between a wildcard bound and a type parameter bound?

Using Generic Types
• Should I prefer parameterized types over raw types?
• Why shouldn't I mix parameterized and raw types, if I feel like it?
• Should I use the generic collections or better stick to the old non-generic collections?
• What is a checked collection?
• What is the difference between a Collection<?> and a Collection<Object>?
• How do I express that a collection is a mix of objects of different types?
• What is the difference between a Collection<Pair<String,Object>>, a Collection<Pair<String,?>> and a Collection<? extends Pair<String,?>>?
• How can I make sure that the same wildcard stand for the same type?

Using Generic Methods
• Why doesn't method overloading work as I expect it?
• Why doesn't method overriding work as I expect it?

Coping With Legacy
• What happens when I mix generic and non-generic code?
• Should I re-engineer all my existing classes and generify them?
• How do I generify an existing non-generic type or method?
• Can I safely generify a supertype, or does it affect all subtypes?
• How do I avoid breaking binary compatibility when I generify an existing type or method?

Defining Generic Types and Methods
• Which types should I design as generic types instead of defining them as regular non-generic types?
• Do generics help designing parallel class hierarchies?
• When would I use an unbounded wildcard instantiation instead of a bounded or concrete instantiation?
• When would I use a wildcard instantiation instead of a concrete instantiation?
• When would I use a wildcard instantiation with an lower bound?
• How do I recover the actual type of the this object in a class hierarchy?
• What is the "getThis" trick?
• How do I recover the element type of a container?
• What is the "getTypeArgument" trick?

Designing Generic Methods
• Why does the compiler sometimes issue an unchecked warning when I invoke a "varargs" method?
• What is a "varargs" warning?
• How can I suppress a "varargs" warning?
• When should I refrain from suppressing a "varargs" warning?
• Which role do wildcards play in method signatures?
• Which one is better: a generic method with type parameters or a non-generic method with wildcards?
• Under which circumstances are the generic version and the wildcard version of a method equivalent?
• Under which circumstances do the generic version and the wildcard version of a method mean different things?
• Under which circumstances is there no transformation to the wildcard version of a method possible?
• Should I use wildcards in the return type of a method?
• How do I implement a method that takes a wildcard argument?
• How do I implement a method that takes a multi-level wildcard argument?
• I want to pass a U and a X<U> to a method.  How do I correctly declare that method?

Working With Generic Interfaces
• Can a class implement different instantiations of the same generic interface?
• Can a subclass implement another parameterized interface than any of its superclasses does?
• What happens if a class implements two generic interfaces that define the same method?
• Can an interface type nested into a generic type use the enclosing type's type parameters?

Implementing Infrastructure Methods
• How do I best implement the equals method of a generic type?
• How do I best implement the clone method of a generic type?

Using Runtime Type Information
• What does the type parameter of class java.lang.Class mean?
• How do I pass type information to a method so that it can be used at runtime?
• How do I generically create objects and arrays?
• How do I perform a runtime type check whose target type is a type parameter?

Reflection
• Which information related to generics can I access reflectively?
• How do I retrieve an object's actual (dynamic) type?
• How do I retrieve an object's declared (static) type?
• What is the difference between a generic type and a parameterized type in reflection?
• How do I figure out whether a type is a generic type?
• Which information is available about a generic type?
• How do I figure out whether a type is a parameterized type?
• Which information is available about a parameterized type?
• How do I retrieve the representation of a generic method?
• How do I figure out whether a method is a generic method?
• Which information is available about a generic method?
• Which information is available about a type parameter?
• What is a generic declaration?
• What is a wildcard type?
• Which information is available about a wildcard?

Compiler Messages
• What is an "unchecked" warning?
• How can I disable or enable unchecked warnings?
• What is the -Xlint:unchecked compiler option?
• What is the SuppressWarnings annotation?
• How can I avoid "unchecked cast" warnings?
• Is it possible to eliminate all "unchecked" warnings?
• Why do I get an "unchecked" warning although there is no type information missing?
Heap Pollution
• What is heap pollution?
• When does heap pollution occur?
Type Erasure
• How does the compiler translate Java generics?
• What is type erasure?
• What is reification?
• What is a bridge method?
• Under which circumstances is a bridge method generated?
• Why does the compiler add casts when it translates generics?
• How does type erasure work when a type parameter has several bounds?
• What is a reifiable type?
• What is the type erasure of a parameterized type?
• What is the type erasure of a type parameter?
• What is the type erasure of a generic method?
• Is generic code faster or slower than non-generic code?
• How do I compile generics for use with JDK <= 1.4?
Type System
• How do parameterized types fit into the Java type system?
• How does the raw type relate to instantiations of the corresponding generic type?
• How do instantiations of a generic type relate to instantiations of other generic types that have the same type argument?
• How do unbounded wildcard instantiations of a generic type relate to other instantiations of the same type?
• How do wildcard instantiations with an upper bound relate to other instantiations of the same type?
• How do wildcard instantiations with a lower bound relate to other instantiations of the same type?
• Which super-subtype relationships exist among instantiations of generic types?
• Which super-subset relationships exist among wildcards?
• Does "extends" always mean "inheritance"?
Exception Handling
• Can I use parameterized types in exception handling?
• Why are generic exception and error types illegal?
• Can I use a type parameter in exception handling?
• Can I use a type parameter in a catch clause?
• Can I use a type parameter in in a throws clause?
• Can I throw an object whose type is a type parameter?
Static Context
• How do I refer to static members of a parameterized type?
• How do I refer to a (non-static) inner class of a parameterized type?
• How do I refer to an interface type nested into a parameterized type?
• How do I refer to an enum type nested into a parameterized type?
• Can I import a particular instantiation of generic type?
• Why are generic enum types illegal?
Type Argument Inference
• What is type argument inference?
• Is there a correspondence between type inference for method invocation and type inference for instance creation?
• What is the "diamond" operator?
• What is type argument inference for instance creation expressions?
• Why does the type inference for an instance creation expression fail?
• What is type argument inference for generic methods?
• What explicit type argument specification?
• Can I use a wildcard as the explicit type argument of a generic method?
• What happens if a type parameter does not appear in the method parameter list?
• Why doesn't type argument inference fail when I provide inconsistent method arguments?
• Why do temporary variables matter in case of invocation of generic methods?
Wildcard Capture
• What is the capture of a wildcard?
• What is the capture of an unbounded wildcard compatible to?
• Is the capture of a bounded wildcard compatible to the bound?
Wildcard Instantiations
• Which methods and fields are accessible/inaccessible through a reference variable of a wildcard type?
• Which methods that use the type parameter in the argument or return type are accessible in an unbounded wildcard instantiation?
• Which methods that use the type parameter in the argument or return type are accessible in an upper bound wildcard instantiation?
• Which methods that use the type parameter in the argument or return type are accessible in a lower bound wildcard instantiation?
• Which methods that use the type parameter as type argument of a parameterized argument or return type are accessible in a wildcard instantiation?
• Which methods that use the type parameter as upper wildcard bound in a parameterized argument or return type are accessible in a wildcard instantiation?
• Which methods that use the type parameter as lower wildcard bound in a parameterized argument or return type are accessible in a wildcard instantiation?
• In a wildcard instantiation, can I read and write fields whose type is the type parameter?
• Is it really impossible to create an object whose type is a wildcard parameterized type?
Cast and instanceof
• Which types can or must not appear as target type in an instanceof expression?
Overloading and Overriding
• What is method overriding?
• What is method overloading?
• What is the  @Override annotation?
• What is a method signature?
• What is a subsignature?
• What are override-equivalent signatures?
• When does a method override its supertype's method?
• What are covariant-return types?
• What are substitutable return types?
• Can a method of a non-generic subtype override a method of a generic supertype?
• Can a method of a generic subtype override a method of a generic supertype?
• Can a generic method override a generic one?
• Can a non-generic method override a generic one?
• Can a generic method override a non-generic one?
• What is overload resolution?

Where can I find a generics tutorial?
Where can I find a specification of the Java generics language features?
Which books cover Java generics?
What webpages are devoted to Java generics?

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Klaus Kreft, Bruce Eckel and Cay Horstmann reviewed this FAQ and provided invaluable feedback. 

A number of individuals at (or formerly at) Sun Microsystems (now Oracle) patiently answered countless questions I posed regarding Java generics.  My thanks to Gilad Bracha, Neal Gafter, and Peter von der Ahé. 

Suggestions and corrections, that inspired changes in this FAQ, have been provided by the following people (in alphabetic order): Eric Armstrong, Richard Grin, Markus Keller, Richard Kennard, Sascha Kratky, Keith Lea, Mike Lehmann, Maurice Naftalin, Joe Soroka, Frank Tip, Phil Wadler.

Except as specifically granted below, you may not modify, copy, publish, sell, display, transmit (in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise), adapt, distribute, store in a retrieval system, create derivative works, or in any other way use or exploit the contents of the Java Generics FAQ, without the prior consent of the author. 

All rights, titles and interest, including copyrights and other applicable intellectual property rights, in any of the material belongs to the provider of the material. You do not acquire proprietary interest in such materials by accessing them on my web site. You must abide by all copyright notices and restrictions on use of the material accessed. 

In particular, I do NOT grant permission to copy the Java Generics FAQ or any part of it to a public Web server. Link to the original pages instead. (The problem with you putting a page on your server is that the search engines will find it and send my readers to your server instead. Thus they will be deprived of the most up-to-date version of the document.) 

Non-commercial Use
As a reader of the Java Generics FAQ, you are granted a nonexclusive, nontransferable, limited license to access and use for non-commercial (research and information) purposes the materials that are made available to you as the Java Generics FAQ. This license includes the right to download and print out one copy of the Java Generics FAQ so long as you neither change nor delete any author attribution, legend or copyright notice.  I request that you do not break up the document and attribute the source in such a way that someone can find the most up-to-date version on the Web, e.g. by including a link to http://www.AngelikaLanger.com/GenericsFAQ/JavaGenericsFAQ.html. If you redistribute the hardcopy of the Java Generics FAQ, please send me email informing me of the usage. 

Other forms of non-commercial use may be allowed with prior written permission.  If permission is granted for non-commercial use, credit to the copyright owner must be displayed as prescribed by copyright owner in every exposure of text. To request non-commercial use of copyrighted materials, please email your request and provide the following information:  your name, organization, and title, your request (the text or texts you wish to quote) and the non-commercial purpose of the use. 

Commercial Use

Commercial use on paper, electronic storage devices of all types, online via the Internet or any part of the World Wide Web or via any other electronic distribution is strictly prohibited without prior payment to the copyright owner, as well as attribution of ownership of copyright and URL in every exposure of text. To negotiate legal use of text owned and copyrighted by Angelika Langer, please send me email . 

Disclaimers

The author has taken care in the preparation of this material, but makes no expressed or implied warranty of any kind and assumes no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the information or programs contained herein.