If you want to provide feedback or have any questions regarding Java generics, to which you cannot find an answer in this document, feel free to send me EMAIL or use the GENERICS FAQ form.
A printable version of the FAQ documents is available in PDF format (4.5MB).

Practicalities - Programming With Java Generics

Programming With Generics

Using Generic Types and Methods

Should I prefer parameterized types over raw types?

Why shouldn't I mix parameterized and raw types, if I feel like it?
 

Because it is poor style and highly confusing to readers of your source code.
Despite of the benefits of parameterized types you might still prefer use of raw types over using pre-defined generic types in their parameterized form, perhaps because the raw types look more familiar. To some extent it is a matter of style and taste and both styles are permitted.  No matter what your preferences are: be consistent and stick to it.  Either ignore Java generics and use raw type in all places, or take advantage of the improved type-safety and provide type arguments in all places. Mixing both styles is confusing and results in "unchecked" warnings that can and should be avoided.  Naturally, you have to mix both styles when you interface with source code that was written before the advent of Java generics. In these cases you cannot avoid the mix and the inevitable "unchecked" warnings. However, one should never have any "unchecked" warnings in code that is written in generic style and does not interface with non-generic APIs.  Here is a typical beginner's mistake for illustration.  Example (of poor programming style):  List <String> list = new ArrayList <String> (); Iterator iter = list.iterator();  String s = (String) iter.next(); ... Beginners often start out correctly providing type arguments and suddenly forget, in the heat of the fighting, that methods of parameterized types often return other parameterized types.  This way they end up with a mix of generic and non-generic programming style, where there is no need for it.  Avoid mistakes like this and provide type arguments in all places.  Example (corrected):  List <String> list = new ArrayList <String> (); Iterator <String> iter = list.iterator();  String s = iter.next(); ... Here is an example of a code snippet that produces avoidable "unchecked" warnings.  Example (of avoidable "unchecked" warning):  void f(Object obj) {   Class type = obj.getClass();   Annotation a = type.getAnnotation(Documented.class); // unchecked warning   ... } warning: [unchecked] unchecked call to <A>getAnnotation(java.lang.Class<A>) as a member of the raw type java.lang.Class         Annotation a = type.getAnnotation(Documented.class);                                          ^ The getClass method returns an instantiation of class Class , namely Class<? extends X> , where X is the erasure of the static type of the expression on which getClass is called. In the example, the parameterization of the return type is ignored and the raw type Class is used instead.  As a result, certain method calls, such as the invocation of getAnnotation , are flagged with an "unchecked" warning.  In general, it is recommended that type arguments are provided unless there is a compelling reason not to do so.  In case of doubt, often the unbounded wildcard parameterized type is the best alternative to the raw type.  It is sematically equivalent, eliminates "unchecked" warnings and yields to error messages if their use is unsafe.  Example (corrected):  void f(Object obj) {   Class <?> type = obj.getClass();   Annotation a = type.getAnnotation(Documented.class);    ... }
LINK TO THIS	Practicalities.FAQ002
REFERENCES	What is the benefit of using Java generics? What does type-safety mean? What is an "unchecked" warning? What is the raw type? What is a parameterized or generic)type? How is a generic type instantiated? What is an unbounded wildcard parameterized type?

Should I use the generic collections or stick to the old non-generic collections?
 

Provide type arguments when you use collections; it improves clarity and expressiveness of your source code.
The JDK collection framework has been re-engineered. All collections are generic types since Java 5.0.  In principle, you can choose whether you want to use the pre-defined generic collections in their parameterized or raw form.  Both is permitted, but use of the parameterized form is recommended because it improves the readability of your source code.  Let us compare the generic and non-generic programming style and see how they differ.  Example (of non-generic style):      final class HtmlProcessor {         public static Collection process( Collection files) {             Collection imageFileNames = new TreeSet();             for (Iterator i = files.iterator(); i.hasNext(); ) {                 URI uri = (URI) i.next();                 Collection tokens = HtmlTokenizer.tokenize(new File(uri));                 imageFileNames.addAll(ImageCollector.collect(tokens));  // unchecked warning             }             return imageFileNames;         }     }     final class ImageCollector {         public static Collection collect( Collection tokens) {             Set images = new TreeSet();             for (Iterator i = tokens.iterator(); i.hasNext(); ) {                 HtmlToken tok = (HtmlToken) i.next();                 if (tok.getTag().3("img") && tok.hasAttribute("src"))  {                     Attribute attr = tok.getAttribute("src");                     images.add(attr.getValue());       // unchecked warning                 }              }             return images;         }     } From the code snippet above it is relatively difficult to tell what the various collections contain.  This is typical for non-generic code.  The raw type collections do not carry information regarding their elements.  This lack of type information also requires that we cast to the alledged element type each time an element is retrieved from any of the collections.  Each of these casts can potentially fail at runtime with a ClassCastException . ClassCastException s are a phenomenon typical to non-generic code.  If we translate this non-generic source code with a Java 5.0 compiler, we  receive "unchecked" warnings when we invoke certain operations on the raw type collections.  We would certainly ignore all these warnings, or suppress them with the SuppressWarnings annotation.  Example (of generic counterpart):      final class HtmlProcessor {         public static Collection<String> process( Collection<URI> files) {             Collection<String> imageFileNames = new TreeSet<String>();             for (URI uri : files) {                 Collection<HtmlToken> tokens = HtmlTokenizer.tokenize(new File(uri));                 imageFileNames.addAll(ImageCollector.collect(tokens));             }             return imageFileNames;         }     }     final class ImageCollector {          public static Collection<String> collect( Collection<HtmlToken> tokens) {             Set<String> images = new TreeSet<String>();             for (HtmlToken tok : tokens) {                 if (tok.getTag().equals("img") && tok.hasAttribute("src"))  {                     Attribute attr = tok.getAttribute("src");                     images.add(attr.getValue());                 }              }             return images;         }     } From the generic source code we can easily tell what type of elements are stored in the various collections. This is one of the benefits of generic Java: the source code is substantially more expressive and captures more of the programmer's intent. In addition it enables the compiler to perform lots of type checks at compile time that would otherwise be performed at runtime.  Note that we got rid of all casts. As a consequence there will be no runtime failure due to a ClassCastException .  This is a general rule in Java 5.0:  if your source code compiled without any warnings then there will be no unexpected ClassCastException s at runtime. Of course, if your code contains explicit cast expressions any exceptions resulting from these casts are not considered unexpected.  But the number of casts in your source code will drop substantially with the use of generics.
LINK TO THIS	Practicalities.FAQ003
REFERENCES	package java.util Should I prefer parameterized types over raw types? What is the benefit of using Java generics? What is an "unchecked" warning? How can I disable or enable unchecked warnings? What is the SuppressWarnings annotation? What is the raw type? What is a parameterized or generic type? How is a generic type instantiated?

What is a checked collection?
 

A view to a regular collection that performs a runtime type check each time an element is inserted.
Despite of all the type checks that the compiler performs based on type arguments in order to ensure type safety it is still possible to smuggle elements of the wrong type into a generic collection.  This can happen easily when generic and non-generic code is mixed.  Example (of smuggling an alien into a collection):  class Legacy {   public static List create() {     List rawList = new ArrayList();     rawList.add("abc");    // unchecked warning     ...     return rawList;   }   public static void insert(List rawList) {     ...      rawList.add(new Date ()); // unchecked warning     ...   } } class Modern {   private void someMethod() {     List< String > stringList = Legacy.create();  // unchecked warning     Legacy.insert(stringList);      Unrelated.useStringList(stringList);   } } class Unrelated {   public static void useStringList(List<String> stringList) {     ...     String s = stringList.get(1);   // ClassCastException     ...   } } An "alien" Date object is successfully inserted into a list of strings.  This can happen inadvertantly when a parameterized type is passed to a piece of legacy code that accepts the corresponding raw type and then adds alien elements.  The compiler can neither detect nor prevent this kind of violation of the type safety, beyond issuing an "unchecked" warning when certain methods of the raw type are invoked. The inevitable type mismatch will later show up in a potentially unrelated part of the program and will mainfest itself as an unexpected ClassCastException .  For purposes of diagnostics and debugging JDK 5.0 adds a set of &ldquo;checked&rdquo; views to the collection framework (see java.util.Collections ), which can detect the kind of problem explained above.  If a checked view is used instead of the original collection then the error is reported at the correct location, namely when the "alien" element is inserted.  Example (of using a checked collection):  class Legacy {   public static List create() {     List rawList = new ArrayList();     rawList.add("abc");    // unchecked warning     ...     return rawList;   }   public static void insert(List rawList) {     ...      rawList.add(new Date());    // ClassCastException     ...   } } class Modern {   private void someMethod() {     List<String> stringList        = Collections.checkedList (L egacy.create() ,String.class) ; // unchecked warning     Legacy.insert(stringList);     Unrelated.useStringList(stringList);   } } class Unrelated   public static void useStringList(List<String> stringList) {     ...     String s = stringList.get(1);      ...   } } The checked collection is a view to an underlying collection, similar to the unmodifiable and synchronized views provided by class Collections . The purpose of the checked view is to detect insertion of "aliens" and prevent it by throwing a ClassCastException in case the element to be inserted is of an unexptected type.  The expected type of the elements is provided by means of a Class object when the checked view is created. Each time an element is added to the checked collection a runtime type check is performed to make sure that element is of an acceptable type.  Here is a snippet of the implementation of  the checked view for illustration.  Example (excerpt from a checked view implementation):  public class Collections {    public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type ) {     return new CheckedCollection<E>(c, type);   }   private static class CheckedCollection<E> implements Collection<E> {     final Collection<E> c;     final Class<E> type;     CheckedCollection(Collection<E> c, Class<E> type) {       this.c = c;       this.type = type;     }     public boolean add(E o){       if (! type.isInstance (o))         throw new ClassCastException();       return c.add(o);     }   } } The advantage of using a checked view is that the error is reported at the correct location. The downside of using a checked collection is the performance overhead of an additional dynamic type check each time an element is inserted into the collection.  The error detection capabilities of the checked view are somewhat limited.  The type check that is performed when an element is inserted into a checked collection is performed at runtime - using the runtime type representation of the expected element type.  If the element type is a parameterized type the check cannot be exact, because only the raw type is available at runtime.  As a result, aliens can be inserted into a checked collection, although the checked collection was invented to prevent exactly that.  Example (of limitations of checked collections):  class Legacy {   public static List legacyCreate() {     List rawList = new ArrayList();     rawList.add(new Pair("abc","xyz"));  // unchecked warning     ...     return rawList;   }   public static void legacyInsert(List rawList) {     ...      rawList.add(new Pair(new Date(),"Xmas") );        // unchecked warning     ...   } } class Modern {   private void someModernMethod() {     List< Pair<String,String> > stringPairs        = Collections.checkedList( legacyCreate() ,Pair.class) ; // unchecked warning     Legacy.insert(stringPairs);      Unrelated.useStringPairs(stringPairs);   } } class Unrelated {   public static void useStringPairs(List<Pair<String,String>> stringPairList) {     ...     String s = stringPairList.get(1).getFirst(); // ClassCastException     ...   } } The checked view can only check against the raw type Pair and cannot prevent that an alien pair of type Pair<Date,String> is inserted into the checked view to a collection of Pair<String,String> .  Remember, parameterized types do not have an exact runtime type representation and there is not class literal for a parameterized type that we could provide for creation of the checked view.  Note, that a checked view to a collection of type Pair<String,String> cannot be created without a warning.  Example:  Lis t<Pair<String,String>> stringPairs        = Collections.checkedList         (new ArrayList< Pair<String,String> > () , Pair .class); // error Lis t<Pair<String,String>> stringPairs        = Collections.checkedList         ( (List<Pair>) (new ArrayList< Pair<String,String> > ()) , Pair .class); // error Lis t<Pair<String,String>> stringPairs        = Collections.checkedList         ( (List) (new ArrayList< Pair<String,String> > ()) , Pair .class); // unchecked warning We cannot create a checked view to a parameterized type such as List<Pair<String,String>> , because it is required that we supply the runtime type representation of the collection's element type as the second argument to the factory method Collections.checkedList .  The element type Pair<String,String> does not have a runtime type representation of its own; there is no such thing as Pair<String,String>.class .  At best, we can specify the raw type Pair as the runtime type representation of the collection's element type.  But this is the element type of a collection of type List<Pair> , not of a List<Pair<String,String>> .  This explains why we have to add a cast.  The natural cast would be to type List<Pair> , but the conversion from ArrayList<Pair<String,String>> to List<Pair> is not permitted. These two types a inconvertible because they are instantiations of the same generic type for different type arguments.  As a workaround we resort to the raw type List , because the conversion ArrayList<Pair<String,String>> to List is permitted for reasons of compatibility.  Use of the raw type results in the usual "unchecked" warnings.  In this case the compiler complains that we pass a raw type List as the first arguments to the Collections.checkedList method, where actually a List<Pair> is exptected.  In general, we cannot create a checked view  to an instantiation of a collection whose type argument is a parameterized type (such as List<Pair<String,String>> ). This is only possible using debatable casts, as demonstrated above.  However, it is likely that checked collections are used in cases where generic and non-generic legacy code is mixed, because that is the situation in which alien elements can be inserted into a collection inadvertantly.  In a mixed style context, you might not even notice that you work around some of the compiler's type checks, when you create a checked view, because you have to cope with countless "unchecked" warnings anyway.  The point to take home is that checked views provide a certain safety net for collections whose element type is a raw type, but fails to provide the same kind of safety for collections whose element type is a parameterized type.
LINK TO THIS	Practicalities.FAQ004
REFERENCES	class java.util.Collections What is an "unchecked" warning? What is the raw type? What happens when I mix generic and non-generic code? How do I pass type information to a method so that it can be used at runtime? How do I perform a runtime type check whose target type is a type parameter? Why is there no class literal for concrete parameterized types? How does the compiler translate Java generics? What is type erasure? What is the type erasure of a parameterized type?

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 a wildcard that occurs repeatedly in the same scope stands for the same type?

Using Generic Methods

Why doesn't method overloading work as I expect it?
 

Because there is only one byte code representation of each generic type or method.
When you invoke an overloaded method and pass an argument to the method whose type is a type variable or involves a type variable, you might observe surprising results.  Let us study an example.  Example (of invocation of an overloaded method):  static void overloadedMethod( Object o) {         System.out.println("overloadedMethod(Object) called"); } static void overloadedMethod( String s) {         System.out.println("overloadedMethod(String) called"); } static void overloadedMethod( Integer i) {         System.out.println("overloadedMethod(Integer) called"); } static <T> void genericMethod(T t) {         overloadedMethod (t) ; // which method is called?  } public static void main(String[] args) {         genericMethod( "abc" ); } We have several overloaded versions of a method.  The overloaded method is invoked by a generic method which passes an argument of type T to the overloaded method.  Eventually the generic method is called and a string is passed as an argument to the generic method. One might expect that inside the generic method the string version of the overloaded method is invoked, because the method argument is a string.  This, however, is wrong. The program prints:   overloadedMethod( Object ) called How can this happen?  We pass an argument of type String to the overloaded method and yet the version for type Object is called. The reason is that the compiler creates only one byte code representation per generic type or method and maps all instantiations of the generic type or method to that one representation.  In our example the generic method is translated to the following representation:   void genericMethod( Object t) {         overloadedMethod(t);  } Considering this translation, it should be obvious why the Object version of the overloaded method is invoked.  It is entirely irrelevant what type of object is passed to the generic method and then passed along to the overloaded method.  We will always observe a call of the Object version of the overloaded method.  More generally speaking:  overload resolution happens at compile time, that is, the compiler decides which overloaded version must be called. The compiler does so when the generic method is translated to its unique byte code representation.  During that translation type erasure is performed, which means that type parameters are replaced by their leftmost bound or Object if no bound was specified.  Consequently, the leftmost bound or Object determines which  version of  an overloaded method is invoked.  What type of object is passed to the method at runtime is entirely irrelevant for overload resolution. Here is another even more puzzling example. Example (of invocation of an overloaded method): public final class GenericClass<T> {     private void overloadedMethod( Collection<?> o) {         System.out.println("overloadedMethod(Collection<?>)");     }     private void overloadedMethod( List<Number> s) {         System.out.println("overloadedMethod(List<Number>)");     }     private void overloadedMethod( ArrayList<Integer> i) {         System.out.println("overloadedMethod(ArrayList<Integer>)");     }     private void method(List<T> t) {         overloadedMethod(t) ; // which method is called?     }     public static void main(String[] args) {         GenericClass<Integer> test = new GenericClass<Integer>();         test.method(new ArrayList<Integer> ());     } } The program prints: overloadedMethod(Collection<?>) One might have expected that version for ArrayList<Integer> would be invoked, but that again is the wrong expectation.  Let us see what the compiler translates the generic class to.  Example (after type erasure): public final class GenericClass {     private void overloadedMethod( Collection o) {         System.out.println("overloadedMethod(Collection<?>)");     }     private void overloadedMethod( List s) {         System.out.println("overloadedMethod(List<Number>)");     }     private void overloadedMethod( ArrayList i) {         System.out.println("overloadedMethod(ArrayList<Integer>)");     }     private void method(List t) {         overloadedMethod(t) ;     }     public static void main(String[] args) {         GenericClass test = new GenericClass();         test.method(new ArrayList ());     } } One might mistakenly believe that the compiler would decide that the List version of the overloaded method is the best match.  But that would be wrong, of course.  The List version of the overloaded method was originally a version that takes a List<Number> as an argument, but on invocation a List<T> is passed, where T can be any type and need not be a Number . Since T can be any type the only viable version of the overloaded method is the version for Collection<?> . Conclusion: Avoid passing type variables to overloaded methods. Or, more precisely, be careful when you pass an argument to an overloaded method whose type is a type variable or involves a type variable.
LINK TO THIS	Practicalities.FAQ050
REFERENCES	How does the compiler translate Java generics? What is type erasure? What is method overriding? What is method overloading? What is a method signature? What is the @Override annotation? What are override-equivalent signatures? When does a method override its supertype's method? What is overload resolution?

Why doesn't method overriding work as I expect it?
 

Because the decision regarding overriding vs. overloading is based on the generic type, not on any instantiation thereof.
Sometimes, when you believe you override a method inherited from a supertype you inadvertantly overload instead of override the inherited method.  This can lead to surprising effects.  Let us study an example. Example (of overloading): class Box <T> {   private T theThing;   public Box( T t)        { theThing = t; }   public void reset( T t) { theThing = t; }   ... } class WordBox< S extends CharSequence > extends Box< String > {   public WordBox( S t)    { super(t.toString().toLowerCase()); }   public void reset( S t) { super.reset(t.toString().toLowerCase()); }    ... } class Test {     public static void main(String[] args) {         WordBox<String> city = new WordBox<String>("Skogland");         city.reset("Stavanger"); // error: ambiguous     } } error: reference to reset is ambiguous,  both method reset(T) in Box<String> and method reset(T) in WordBox<String> match         city.reset("Stavanger");             ^ In this example, one might be tempted to believe that the method WordBox<String>.reset(String) overrides the superclass method Box<String>.reset(String) .  After all, both methods have the same name and the same parameter types.  Methods with the same name and the same parameter types in a super- and a subtype are usually override-equivalent.  For this reason, we might expect that the invocation of the reset method in the Test class leads to the execution of the WordBox<String>.reset(String) method.  Instead, the compiler complains about an ambiguous method call.  Why? The problem is that the subclass's reset method does not override the superclass's reset method, but overloads it instead.  You can easily verify this by using the @Override annotation. Example (of overloading): class Box <T> {   private T theThing;   public Box( T t)        { theThing = t; }   public void reset( T t) { theThing = t; }   ... } class WordBox <S extends CharSequence> extends Box <String> {   public WordBox( S t)    { super(t.toString().toLowerCase()); } @Override    public void reset( S t) { super.reset(t.toString().toLowerCase()); }    ... } error: method does not override a method from its superclass         @Override           ^ When a method is annotated by an @Override annotation, the compiler issues an error message if the annotated method does not override any of its supertype's methods.  If it does not override, then it overloads or hides methods with the same name inherited from its supertype.  In our example the reset method in the generic WordBox<S extends CharSequence> class overloads the reset method in the parameterized Box<String> class. The overloading happens because the two methods have different signatures. This might come as a surprise, especially in the case of the instantation WordBox<String> , where the two reset methods have the same name and the same parameter type.  The point is that the compiler decides whether a subtype method overrides or overloads a supertype method when it compiles the generic subtype, independently of any instantiations of the generic subtype.  When the compiler compiles the declaration of the generic WordBox<S extends CharSequence> class, then there is no knowledge regarding the concrete type by which the type parameter S might later be replaced.  Based on the declaration of the generic subtype the two reset methods have different signatures, namely reset(String) in the supertype and reset(S_extends_CharSequence) in the generic subtype. These are two completely different signatures that are not override-equivalent.  Hence the compiler considers them overloading versions of each other. In a certain instantiation of the subtype, namely in WordBox<String> , the type parameter S might be replaced by the concrete type String .  As a result both reset methods visible in WordBox<String> suddenly have the same argument type.  But that does not change the fact that the two methods still have different signatures and therefore overload rather than override each other. The identical signatures of the two overloading version of the reset method that are visible in WordBox<String> lead to the anbiguitiy that we observe in our example. When the reset method is invoked through a reference of type WordBox<String> , then the compiler finds both overloading versions.  Both versions are perfect matches, but neither is better than the other, and the compiler rightly reports an ambiguous method call. Conclusion: Be careful when you override methods, especially when generic types or generic methods are involved.  Sometimes the intended overriding turns out to be considered overloading by the compiler, which leads to surprising and often confusing results.  In case of doubt, use the @Override annotation.
LINK TO THIS	Practicalities.FAQ051
REFERENCES	How does the compiler translate Java generics? What is type erasure? What is method overriding? What is method overloading? What is a method signature? What is the @Override annotation? When does a method override its supertype's method? Can a method of a generic subtype override a method of a generic supertype?

Coping With Legacy

What happens when I mix generic and non-generic legacy code?
 

The compiler issues lots of "unchecked" warnings.
It is permitted that a generic class or method is used in both its parameterized and its raw form.  Both forms can be mixed freely.  However, all uses that potentially violate the type-safety are reported by means of an "unchecked warning".  In practice, you will see a lot of unchecked warnings when you use generic types and methods in their raw form.  Example (of mixing paramterized and raw use of a generic type):  interface Comparable<T> {   int compareTo(T other); } class SomeClass implements Comparable {   public int compareTo(Object other) {     ...   } } class Test {   public static void main(String[] args) {     Comparable x = new SomeClass();     x.compareTo(x);     // "unchecked" warning   } } warning: [unchecked] unchecked call to compareTo(T) as a member of the raw type java.lang.Comparable         x.compareTo(x);                    ^ The Comparable interface is a generic type.  Its raw use in the example above leads to "unchecked" warnings each time the compareTo method is invoked.  The warning is issued because the method invocation is considered a potential violation of the type-safety guarantee.  This particular invocation of compareTo is not unsafe, but other methods invoked on raw types might be.  Example (of type-safety problem when mixing parameterized and raw use):  class Test {   public static void someMethod( List list) {     list.add("xyz");     // "unchecked" warning   }   public static void test() {     List<Long> list = new ArrayList<Long> ();     someMethod(list);   } } warning: [unchecked] unchecked call to add(E) as a member of the raw type java.util.List      list.add("xyz");              ^ Similar to the previous example, the invocation of the add method on the raw type List is flagged with an "unchecked" warning.  The invocation is indeed unsafe, because it inserts a string into a list of long values.  The compiler cannot distinguish between invocations that are safe and those that are not.  It reports "unchecked" warnings just in case that a call might be unsafe.  It applies a simple rule: every invocation of a method of a raw type that takes an argument of the unknown type that the class's type parameter stands for, is potentially unsafe.  That does not mean, it must be unsafe (see Comparable.compareTo ), but it can be unsafe (see List.add ).  If you find that you must intermix legacy and generic code, pay close attention to the unchecked warnings. Think carefully how you can justify the safety of the code that gives rise to the warning. Once you've made sure the warning is harmless suppress it using the SuppressWarnings annotation.  If you can re-engineer existing code or if you write new code from scratch you should use generic types and methods in their parmeterized form and avoid any raw use.  For instance, the examples above can be "repaired" as follows:  Example #1 (corrected):  interface Comparable<T> {   int compareTo(T other); } class SomeClass implements Comparable <Object> {   public int compareTo(Object other) {     ...   } } class Test {   public static void main(String[] args) {     Comparable <Object> x = new SomeClass();     x.compareTo(x);     // fine   } } No "unchecked" warning occurs if the Comparable interface is used in its parameterized form in all places.  Example #2 (corrected):  class Test {   public static void someMethod( List <String> list) {     list.add("xyz");     // fine   }   public static void test() {     List<Long> list = new ArrayList<Long> ();     someMethod(list);   // error   } } error: someMethod(java.util.List<java.lang.String>) cannot be applied to java.util.List<java.lang.Long>)         someMethod(list);         ^ The "unchecked" warning in someMethod is no longer necessary if the generic type List is used in its parameterized form as List<String> .  With this additional type information the compiler is now capable of flagging the formerly undetected type-safety problem in method test as an error.
LINK TO THIS	Practicalities.FAQ101
REFERENCES	What does type-safety mean? What is the raw type? Can I use a raw type like any other type? What is an "unchecked" warning? How can I disable or enable unchecked warnings? What is the SuppressWarnings annotation?

Should I re-engineer all my existing types and generify them?

How do I generify an existing non-generic type or method?
 

There are no carved-in-stone rules.  It all depends on the intended semantics of the generified type or method.
Modifying an existing type that was non-generic in the past so that it becomes usable as a parameterized type in the future is a non-trivial task. The generification must not break any existing code that uses the type in its old non-generic form and it must preserve the original non-generic type's semantic meaning.  For illustration, we study a couple of examples from the collection framework (see package java.util in J2SE 1.4.2 and J2SE 5.0 ).  We will generify the traditional non-generic interface Collection .  From the semantics of a collection it is obvious that for a homogenous collection of elements of the same type the element type would be the type parameter of a generic Collection interface.  Example (from JDK 1.4; before generification):  interface Collection {   boolean add     ( Object o);    boolean contains( Object o);   boolean remove  ( Object o);   ... } These methods take an element as an argument and insert, find or extract the element from the collection.  In a generic collection the method parameters would be of type E , the interface's type parameter. Example (from JDK 5.0; after generification):  interface Collection <E> {   boolean add     ( E o);    boolean contains( E o);    boolean remove  ( E o);   ... } However, this modification does not exactly preserve the semantics of the old class.  Before the generification it was possible to pass an arbitrary type of object to these methods.  After the generification only objects of the "right" type are accepted as method arguments.  Example (of modified semantics):  class ClientRepository {   private Collection <Client> clients = new LinkedList<Client>();   ...   boolean isClient( Object c) {     return clients.contains(c);   // error   }  } Passing an Object reference to method contains used to be permitted before the generification, but no longer compiles after generification.    Seemingly, our generified type is not semantically  compatible with the original non-generic type.  A more relaxed generification would look like this. Example (from JDK 5.0; after an alternative generification):  interface Collection <E> {   boolean add     ( E o);    boolean contains( Object o);    boolean remove  ( Object o);   ... } Only for the add method now would accept the more restrictive method parameter type E .  Since a Collection<E> is supposed to contain only elements of type E , it is expected and desired that insertion of an alien element is rejected at compile time.  This seemingly trivial example illustrates that decisions regarding a "correct" generification are largely a matter of taste and style. Often, there are several viable approaches for a generification.  Which one is "correct" depends on the specific requirements to and expectations of the semantics of the resulting generified type.
LINK TO THIS	Practicalities.FAQ103
REFERENCES	How do I avoid breaking binary compatibility when I generify an existing type or method?

Can I safely generify a supertype, or does it affect all subtypes?
 

Yes, we can generify non-generic legacy supertypes without affecting the non-generic legacy subtypes - provided the subtype method's signature is identical to the erasure of the supertype method's signature.
Assume we have a class hierarchy of legacy types and we want to generify the supertype.  Must we also generify all the subtypes?  Fortunately not. Let us consider an example. Example (of a hierarchy of legacy types): c lass Box {   private Object theThing;   public Box(Object t)        { theThing = t; }   public void reset( Object t) { theThing = t; }   public Object get()         { return theThing; }   ... } class NamedBox extends Box {   private String theName;   public NamedBox(Object t,String n) { super(t); theName = n; }   public void reset( Object t)        { super.reset(t); }   public Object get()                { return super.get(); }   ... } Now we decide to generify the supertype. Example (same as before, but with generified superclass):   class Box <T> {   private T theThing;   public Box(T t)        { theThing = t; }   public void reset( T t) { theThing = t; }   public T get()         { return theThing; }   ... } class NamedBox extends Box {   private String theName;   public NamedBox(Object t,String n) { super(t); theName = n; }   public void reset( Object t)        { super.reset(t); }   public Object get()                { return super.get(); }   ... } warning: [unchecked] unchecked call to Box(T) as a member of the raw type Box   public NamedBox(Object t,String n) { super(t); theName = n; }                                             ^ warning: [unchecked] unchecked call to reset(T) as a member of the raw type Box   public void reset(Object t)        { super.reset(t); }                                                   ^ The subclass is still considered a subtype of the now generic supertype where the reset and get method override the corresponding supertype methods. Inevitably, we now receive unchecked warnings whenever we invoke certain methods of the supertype because we are now using methods of a raw type. But other than that, the subtype is not affected by the re-engineering of the supertype.  This is possible because the signatures of the subtype methods are identical to the erasures of the signatures of the supertype methods. Let us consider a slightly different generification.  Say, we re-engineer the superclass as follows. Example (same as before, but with a different generification): class Box <T> {   private T theThing;   public <S extends T> Box(S t)        { theThing = t; }   public <S extends T> void reset( S t) { theThing = t; }   public T get() { return theThing; }   ...  } class NamedBox extends Box {   private String theName;   public NamedBox(Object t,String n) { super(t); theName = n; }   public void reset( Object t)        { super.reset(t); }   public Object get()                { return super.get(); }   ... } This time the reset method is a generic method.  Does the subtype method reset still override the generic supertype method?  The answer is: yes. The subtype method's signature is still identical to the erasure of the supertype method's signature and for this reason the subtype method is considered an overriding method.  Naturally, we still receive the same unchecked warnings as before, but beyond that there is no need to modify the subtype although we re-engineered the supertype. The point to take home is that methods in a legacy subtype can override (generic and non-generic) methods of a generic supertype as long as the subtype method's signature is identical to the erasure of the supertype method's signature.
LINK TO THIS	Practicalities.FAQ103A
REFERENCES	Can a method of a non-generic subtype override a method of a generic supertype? How does the compiler translate Java generics? What is type erasure? What is method overriding? What is a method signature? What is a subsignature? What are override-equivalent signatures? When does a method override its supertype's method?

How do I avoid breaking binary compatibility when I generify an existing type or method?
 

Sometimes a dummy bound does the trick.
Occasionally, one must pay attention to the fact that a generification might change the signature of some methods in the byte code.  Changing the signature will break existing code that cannot be recompiled and relies on the binary compatibility of the old and new version of the .class file.  Example (before generification, taken from package java.util ):  class Collections {   public static Object max( Collection coll) {...}    ... } The max method finds the largest element in a collection and obviously the declared return type of the method should match the element type of the collection passed to the method.  A conceivable generification could look like this. Example (after a naive generification):  class Collections {   public static <T extends Comparable<? super T>>   T max(Collection <? extends T> coll)  {...}    ... } While this generification preserves the semantics of the method, it changes the signature of the max method.  It is now a method with return type Comparable , instead of Object .  Example (after type erasure):  class Collections {   public static Comparable max( Collection coll)  {...}    ... } This will break existing code that relies on the binary compatibility of the .class files.  In order to preserve the signature and thus the binary compatibility, an otherwise superfluous bound can be used.  Example (after binary compatible generification, as available in package java.util ):  class Collections {   public stati c <T extends Object & Comparable<? super T>>   T max(Collection <? extends T> coll)  {...}   ... } The leftmost bound of the type parameter is now type Object instead of type Comparable , so that the type parameter T is replaced by Object during type erasure.  Example (after type erasure):  class Collections {   public static Object max( Collection coll)  {...}    ... } Afterthought:  Perhaps you wonder why the hack decribed in this FAQ entry is needed.  Indeed, had the Collections.max method been defined as returning a Comparable in the first place, no further measures, such as adding Object as a type parameter bound, had been required to preserve binary compatibility. Basically, the declared return type Object is a mistake in the design of this method.  If you carefully study the specification of the Collections.max  method's functionality then you realize that all elements of the collection are required to implement the Comparable interface.  Consequently, the returned object is Comparable , too.  There is no reason why the method should return an Object reference.  The only explanation one can think of is that in pre-generic Java there was no way of ensuring by compile-time type checks that the Collection contains only Comparable objects.  However, this was ensured via runtime type checks, namely an explicit downcast in the implementation of the method.  Hence this is not really an excuse for the bug.  Note, that the runtime time type check in the pre-generic version of the Collections.max method still exists in the generic version.  The former explicit cast is now an implicit one generated by the compiler.  In the generic version, this cast can never fail (unless there are unchecked warnings), because the type parameter bound Comparable ensures at compile-time that the elements in the Collection are Comparable .
LINK TO THIS	Practicalities.FAQ104
REFERENCES

 
 

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?

Yes.
Some hierarchies of types run in parallel in the sense that a supertype refers to another type and the subtype refers to a subtype of that other type. Here is an example, where the supertype Habitat refers to Animal s and the subtype Aquarium refers to Fish .   Overriding methods in the subtype often have to perform a type checks in this situation, like in the example below. Example (of parallel type hierarchies leading to dynamic type check): abstract class Habitat {   protected Collection theAnimals;   ...   public void addInhabitant( Animal animal) {     theAnimals.add(animal);   } } class Aquarium extends Habitat {   ... public void addInhabitant( Animal fish) {     if (fish instanceof Fish )       theAnimals.add(fish);     else       throw new IllegalArgumentException(fish.toString());   } } Aquarium a = new Aquarium(); a.addInhabitant(new Cat());   // ClassCastException In order to ensure that the aquarium only contains fish, the addInhabitant method performs an instanceof test.  The test may fail at runtime with a ClassCastException .  It would be nice if the addInhabitant method could be declared as taking a Fish argument; the instanceof test would be obsolete then.  The problem is that a addInhabitant(Fish) method in the Aquarium class would be an overloading version of the Habitat 's addInhabitant(Animal) method rather than an overriding version thereof and this is neither intended nor corrct.  Hence, we cannot get rid of the instanceof test - unless we consider generics. This kind of type relationship among parallel type hierarchies can be more elegantly expressed by means of generics.  If the supertype Habitat were a generic type, then the subtype Aquarium would no longer need the type check.  Here is a re-engineered version of the example above. Example (same as above, re-engineered using generics): abstract class Habitat <A extends Animal> {   protected Collection <A> theAnimals;   ...   public void addInhabitant( A animal) {     theAnimals.add(animal);  } class Aquarium extends Habitat <Fish> {   ... public void addInhabitant( Fish fish) {     // no test necessary     theAnimals.add(fish);   } } Aquarium a = new Aquarium(); a.addInhabitant(new Cat());   // error: illegal argument type When the supertype is generic, then the subtype can derive from a certain instantiation of the supertype.  The advantage is that overriding methods in the subtype can now be declared to take the intended type of argument rather than a supertype argument.  In the example, the Aquarium is a Habitat<Fish> , which means that the addInhabitant method now takes a Fish argument instead of an Animal argument.  This way, the instanceof test is no longer necessary and any attempt to add a non- Fish to the Aquarium will be detected at compile-time already. Note, that the generic version of the type hierarchy has further advantages. Example (of parallel type hierarchies): abstract class Habitat {   protected Collection theAnimals;   ...   public Habitat( Collection animals) {      theAnimals = animals;   } } class Aquarium extends Habitat {   ...   public Aquarium( Collection fish) {      // no type check possible      super(fish);    } } ArrayList animals = new ArrayList(); animals.add(new Cat()); Aquarium a = new Aquarium(animals); // no error or exception here In the Aquarium constructor there is no way to check whether the collection contains Fish or not.  Compare this to the generic solution. Example (of parallel type hierarchies using generics): abstract class Habitat<A extends Animal> {   protected Collection<A> theAnimals;   ...   public Habitat(Collection <A> animals) {      theAnimals = animals;   } } class Aquarium extends Habitat<Fish> {    ...    public Aquarium(Collection <Fish> fish) {      // no type check necessary      super(fish);    } } ArrayList<Animal> animals = new ArrayList<Animal>(); animals.add(new Cat()); Aquarium a = new Aquarium(animals); // error: illegal argument type In this generic version of the type hierarchy, the Aquarium constructor requires a Collection<Fish> as a constructor argument and this collection of fish can be passed along to the supertype's constructor because Aquarium extends the supertype's instantiation Habitat<Fish> whose constructor requires exactly that type of collection. Conclusion:  Type hierarchies that run in parallel are more easily and more reliably implemented by means of generics.
LINK TO THIS	Practicalities.FAQ201A
REFERENCES	What is method overriding? What is method overloading?

When would I use an unbounded wildcard parameterized type instead of a bounded wildcard or concrete parameterized type?

When would I use a wildcard parameterized type instead of a concrete parameterized type?
 

Whenever you need the supertype of all or some instantiations of a generic type.
There are two typical situations in which wildcard parameterized types are used because they act as supertype of all instantiations of a given generic type:  relaxing a method signature to allow a broader range of argument or return types denoting a mix of instantiations of the same generic type Details are discussed in the FAQ entries Practicalities.FAQ301 and Practicalities.FAQ006 listed in the reference section below.
LINK TO THIS	Practicalities.FAQ203
REFERENCES	Which role do wildcards play in method signatures? How do I express a mixed sequence of instantiations of a given generic type?

When would I use a wildcard parameterized type with a lower bound?
 

When a concrete parmeterized type would be too restrictive.
Consider a class hierarchy where a the topmost superclass implements an instantiation of the generic Comparable interface.  Example:  class Person implements Comparable<Person> {   ... } class Student extends Person {   ... } Note, the Student class does not and cannot implement Comparable<Student> , because it would be a subtype of two different instantiations of the same generic type then, and that is illegal (details here ).  Consider also a method that tries to sort a sequence of subtype objects, such as a List<Student> .  Example:  class Utilities {   public static <T extends Comparable<T>> void sort(List<T> list) {     ...   }   ... } This sort method cannot be applied to a list of students.  Example:  List<Student> list = new ArrayList<Student>(); ... Utilities.sort(list);       // error The reason for the error message is that the compiler infers the type parameter of the sort method as T:=Student and that class Student is not Comparable<Student> .  It is Comparable<Person> , but that does not meet the requirements imposed by the bound of the type parameter of method sort.  It is required that T (i.e. Student ) is Comparable<T> (i.e. Comparable<Student> ), which in fact it is not. In order to make the sort method applicable to a list of subtypes we would have to use a wildcard with a lower bound, like in the re-engineered version of the sort method below.  Example:  class Utilities {   public static <T extends Comparable <? super T > > void sort(List<T> list) {     ...   }   ... } Now, we can sort a list of students, because students are comparable to a supertype of Student , namely Person .
LINK TO THIS	Practicalities.FAQ204
REFERENCES	Can a subclass implement another instantiation of a generic interface than any of its superclasses does?

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?
 

Because you pass in a variable argument list of reifiable types.
When you invoke a method with a variable argument list (also called varargs ) you will occasionally find that the compiler issues an unchecked warning.  Here is an example: Example (of a varargs method and its invocation): public  static <E> void addAll(List<E> list, E... array) {    for (E element : array) list.add(element); } public static void main(String[] args) {    addAll(new ArrayList<String>(),     // fine           "Leonardo da Vinci",           "Vasco de Gama"    );    addAll(new ArrayList<Pair<String,String>>(), // unchecked warning           new Pair<String,String>("Leonardo","da Vinci"),           new Pair<String,String>("Vasco","de Gama")    ); } warning: [unchecked] unchecked generic array creation of type Pair<String,String>[] for varargs parameter         addAll(new ArrayList<Pair<String,String>>(),               ^ The first invocation is fine, but the second invocation is flagged with an unchecked warning.  This warning is confusing because there is no array creation expression anywhere in the source code. In order to understand, what the compiler complains about you need to keep in mind two things: Variable argument lists are translated by the compiler into an array. Creation of arrays with a non-reifiable component type is not permitted. In the example above the compiler translates the varargs parameter in the method definition into an array parameter.  Basically the method declaration is translated to the following: Example (of varargs method after translation): public static <E> void addAll(List<E> list, E[] array) {   for (E element : array) list.add(element); } When the method is invoked, the compiler automatically takes the variable number of arguments, creates an array into which it stuffs the arguments, and passes the array to the method. The method invocations in the example above are translated to the following: Example (of invocation of varargs method after translation): public static void main(String[] args) {    addAll(new ArrayList<String>(),   // fine         new String[] {            "Leonardo da Vinci",            "Vasco de Gama"         }    );    addAll(new ArrayList<Pair<String,String>>(), // unchecked warning           new Pair<String,String>[] {               new Pair<String,String>("Leonardo","da Vinci"),               new Pair<String,String>("Vasco","de Gama")           }    ); } As you can see, the compiler creates a String[] for the first invocation and a Pair<String,String>[] for the second invocation. Creating a is String[] is fine, but creating a Pair<String,String>[] is not permitted. Pair<String,String> is not a reifiable type, that is, it loses information as a result of type erasure and is at runtime represented as the raw type Pair instead of the exact type Pair<String,String> .  The loss of information leads to problems with arrays of such non-reifiable component types. The reasons are illustrated in FAQ entry ParameterizedTypes.FAQ104 ; as usual it has to do with type safety issues. If you were trying to create such an array of type Pair<String,String>[] yourself, the compiler would reject the new -expression with an error message.  But since it is the compiler itself that creates such a forbidden array, it chooses to do so despite of the type safety issues and gives you an unchecked warning to alert you to potential safety hazards. You might wonder why the unchecked warning is needed and what peril it tries to warn about.  The example above is perfectly type-safe, because in the method implementation the array is only read and nothing is stored in the array.  However, if a method would store something in the array it could attempt to store an alien object in the array, like putting a Pair<Long,Long> into a Pair<String,String>[] .  Neither the compiler nor the runtime system could prevent it. Example (of corrupting the implicitly created varargs array; not recommended): Pair<String,String>[] method(Pair<String,String>... lists) {    Object[] objs = lists;    objs[0] = new Pair<String,String>("x","y");     objs[1] = new Pair<Long,Long>(0L,0L);  // corruption !!!    return lists; } public static void main(String[] args) {    Pair<String,String>[] result       = method(new Pair<String,String>("Vasco","da Gama"), // unchecked warning               new Pair<String,String>("Leonard","da Vinci"));    for (Pair<String,String> p : result) {      String s = p.getFirst();           // ClassCastException    } } The implicitly created array of String pairs is accessed through a reference variable of type Object[] .  This way anything can be stored in the array; neither the compiler nor the runtime system can prevent that a Pair<Long,Long> is stored in the array of Pair<String,String> . What the compiler can do is warning you when the implicit varargs array is created.  If you ignore the warning you will get an unexpected ClassCastException later at runtime. Here is another example that illustrates the potential danger of ignoring the warning issued regarding array construction in conjunction with variable argument lists. Example (of a varargs method and its invocation): public final class Test {          static <T> T[] method_1(T t1, T t2) {             return method_2(t1, t2);                       // unchecked warning         }         static <T> T[] method_2( T... args) {             return args;         }         public static void main(String... args) {             String[] strings = method_1("bad", "karma");     // ClassCastException         } } warning: [unchecked] unchecked generic array creation of type T[] for varargs parameter             return method_2(t1, t2);                            ^ In this example the first method calls a second method and the second method takes a variable argument list.  In order to invoke the varargs method the compiler creates an array and passes it to the method. In this example the array to be created is an array of type T[] , that is, an array whose component type is a type parameter.  Creation of such arrays is prohibited in Java and you would receive an error message if you tried to create such an array yourself; see TypeParameters.FAQ202 for details. As in the previous example, the array's component type is non-reifiable and due to type erasure the compiler does not create a T[] , but an Object[] instead.  Here is what the compiler generates: Example (same a above, after translation by type erasure): public final class Test {          static Object[] method_1( Object t1, Object t2) {             return method_2( new Object[] {t1, t2} );                   // unchecked warning         }         static Object[] method_2( Object[] args) {             return args;         }         public static void main(String[] args) {             String[] strings = (String[]) method_1("bad", "karma");       // ClassCastException         } } The unchecked warning is issued to alert you to the potential risk of type safety violations and unexpected ClassCastException s.  In the example, you would observe a ClassCastException in the main() method where two strings are passed to the first method.  At runtime, the two strings are stuffed into an Object[] ; note, not a String[] .  The second method accepts the Object[] as an argument,  because after type erasure Object[] is its declared parameter type. Consequently, the second method returns an Object[] , not a String[] , which is passed along as the first method's return value. Eventually, the compiler-generated cast in the main() method fails, because the return value of the first method is an Object[] and no String[] . Again, the problem is that calling the varargs method requires creation of a array with a non-reifiable component type.  In the first example, the array in question was a Pair<String,String>[] ; in the second example, it was a T[] .  Both are prohibited in Java because they can lead to type safety problems.  Conclusion:  It is probably best to avoid providing objects of non-reifiable types where a variable argument list is expected.  You will always receive an unchecked warning and unless you know exactly what the invoked method does you can never be sure that the invocation is type-safe.
LINK TO THIS	Practicalities.FAQ300
REFERENCES	What does type-safety mean? What is a reifiable type? Can I create an array whose component type is a concrete parameterized type? Can I create an array whose component type is a wildcard parameterized type? Why is it allowed to create an array whose component type is an unbounded wildcard parmeterized type? Can I create an array whose component type is a type parameter?

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?
 

It depends.  There is not one-size-fits-all rule.
Often, we have two alternatives for the declaration of a method: We can declare the method as a non-generic method using wildcard parameterized types as argument and return types. Example: void reverse( List <?> list) { ... } or We can declare the method as a generic method with type parameters, that is, without using wildcards. Example: <T> void reverse( List <T> list) { ...} Whether one alternative is better than the other depends on the semantics of the method. In some situations there is no semantic difference between the two alternatives and it is mostly a matter of taste and style which technique is preferred.  But there are also semantics that cannot expressed with wildcards as well as cases that cannot be solved without wildcards.  The subsequent  entries explore the details and provide examples.
uiLINK TO THIS	Practicalities.FAQ302
REFERENCES	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?

Under which circumstances are the generic version and the wildcard version of a method equivalent?
 

If there is a transformation between the generic and the wildcard version that maintains the semantics.
In many situations we can replace wildcards by type parameters and vice versa.  For example, the following two signatures are semantically equivalent:     void reverse( List <?> list) { ... } <T> void reverse( List <?> list) { ... } In this and the subsequent entries we aim to explore not only which of two versions is better than the other, but also how we can transform between a generic and a wildcard version of a method signature.  The Transformation Wildcard => Generic: The key idea for turning a method signature with a wildcard into a generic method signature is simple:  replace each wildcard by a type variable. These type variables are basically the captures of the respective wildcards, that is, the generic method signature makes the captures visible as type parameters. For example,  we can transform the following method signature <T> void fill( List <? super T> list, T obj) { ... } into this signature  <S, T extends S> void fill( List <S> list, T obj) by replacing the wildcard " ? super T " by an additional type parameter S .  The type relationship, namely that the former wildcard is a supertype of T , is expressed by saying that " T extends S ". Generic => Wildcard: Conversely, if we prefer method signatures with fewer type parameters, then we can reduce the number of type parameters by means of wildcards: replace each type parameter that appears in a parameterized argument or return type by a wildcard.  In the previous example, we would transform the method signature <S, T extends S> void fill( List <S> list, T obj) into the signature <T> void fill( List <? super T> list, T obj) { ... } by replacing the type variable S by a wildcard.  The type relationship, namely that T is a subtype of S , is expressed by giving the wildcard a lower bound, that is, by saying " ? super T ". The transformations sketched out above do not always work.  Especially the transformation from a generic version to a wildcard version is not always possible. Problems pop up, for instance, when the generic method signature has more than one type parameter and the type parameters have certain type relationships, such as super-subtype or same-type relationships.  In such a situation it might be impossible to translate the type relationship among the type parameters into a corresponding relationship among the wildcards.  In the example above, a semantically equivalent wildcard version could be found, because the type relationship could be expressed correctly by means of the wildcard bound.  But this is not always possible, as is demonstrated in subsequent entries. In this entry, we discuss only situations in which a transformation exists that allows for two semantically equivalent signature and the questions is: which one is better?  For illustration let us study a couple of examples. Case Study #1 Let us consider the following reverse method.  It can be declared as a generic method. Example (of a method with type parameters): public static <T> void reverse( List <T> list) {   ListIterator <T> fwd = list.listIterator();   ListIterator <T> rev = list.listIterator(list.size());   for (int i = 0, mid = list.size() >> 1; i < mid; i++) {     T tmp = fwd.next();     fwd.set(rev.previous());     rev.set(tmp);   } } Alternatively, it can be declared as a non-generic method using a wildcard argument type instead.  The transformation simply replaces the unbounded type parameter T by the unbounded wildcard " ? ". Example (of the same method with wildcards; does not compile): public static void reverse( List <?> list) {   ListIterator <?> fwd = list.listIterator();   ListIterator <?> rev = list.listIterator(list.size());   for (int i = 0, mid = list.size() >> 1; i < mid; i++) {     Object tmp = fwd.next();     fwd.set(rev.previous()); // error     rev.set(tmp);          // error   } } The wildcard version has the problem that it does not compile. The iterators of a List<?> are of type ListIterator<?> , a side effect of which is that their next and previous methods return an Object , while their set method requires a more specific type, namely the " capture of ? ". We can find a workaround for this problem by using raw types, as shown below. Example (of the same method with wildcards; not recommended):   public  static void reverse( List <?> list) {   ListIterator fwd = list.listIterator();   ListIterator rev = list.listIterator(list.size());   for (int i = 0, mid = list.size() >> 1; i < mid; i++) {     Object tmp = fwd.next();     fwd.set(rev.previous());  // unchecked warning     rev.set(tmp);  //  unchecked warning   } } But even that workaround is not satisfying because the compiler gives us unchecked warnings, and rightly so.  After all we are calling the  set method on the raw type  ListIterator , without knowing which type of object the iterator refers to.  The best implementation of the wildcard version of  reverse would use a generic helper method, as shown below. Example (of the same method with wildcards; uses helper method):   private static  <T> void reverseHelper( List <T> list) {   ListIterator<T> fwd = list.listIterator();   ListIterator<T> rev = list.listIterator(list.size());   for (int i = 0, mid = list.size() >> 1; i < mid; i++) {     T tmp = fwd.next();     fwd.set(rev.previous());     rev.set(tmp);   } } public static void reverse( List <?> list) {   reverseHelper(list); } This solution compiles without warnings and works perfectly well, thanks to wildcard capture.  However, it raises the question: why not use the generic version in the first place.  The helper method is exactly the generic version of our  reverse method. The wildcard version only adds overhead and does not buy the user anything. Case Study #2 Let us start with the wildcard version this time.  We discuss the example of a  copy method. Example (of the a method with wildcards):   public static <T> void copy( List <? super T> dest,  List <? extends T> src) {   int srcSize = src.size();   if (srcSize > dest.size())     throw new IndexOutOfBoundsException("Source does not fit in dest");   ListIterator <? super T> di=dest.listIterator();   ListIterator <? extends T> si=src.listIterator();   for (int i = 0; i < srcSize; i++) {     di.next();     di.set(si.next());   } } It is a method that has one type parameter  T and uses two different wildcard types as argument types.  We can transform it into a generic method without wildcards by replacing the two wildcards by two type parameters.  Here is the corresponding generic version without wildcards. Example (of the same method without wildcards):   public static  <U,T extends U,L extends T> void copy( List <U> dest,  List <L> src) {   int srcSize = src.size();   if (srcSize > dest.size())      throw new IndexOutOfBoundsException("Source does not fit in dest");   ListIterator <U> di = dest.listIterator();   ListIterator <L>  si = src.listIterator();   for (int i = 0; i < srcSize; i++) {     di.next();     di.set(si.next());   } } The version without wildcards uses two additional type parameters  U and  L .  U stands for a supertype of  T and  L stands for a subtype of  T .  Basically,  U and  L are the captures of the wildcards " ? extends T " and " ? super T " from the wildcard version of the copy method. Semantically the two version are equivalent. The main difference is the number of type parameters.  The version without wildcards expresses clearly that 3 unknown types are involved:  T , a supertype of  T , and a subtype of  T . In the wildcard version this is less obvious.  Which version is preferable is to the eye of the beholder. Case Study #3 Let's study the example of a  fill method, which has been mentioned earlier, greater detail. Let's start with the generic version without wildcards and let's try to figure out whether we can get rid of the type parameters by means of wildcards. Example (of the a method with type parameters):   public static  <S, T extends S> void fill( List <S> list,  T obj) {   int size = list.size();   ListIterator <S> itr = list.listIterator();   for (int i = 0; i < size; i++) {     itr.next();     itr.set(obj);   } } The method takes two type parameters  S and  T and two method parameters: an unknown instantiation of the generic type  List , namely  List<S> , and an object of unknown type  T . There is a relationship between  S and  T :  S is a supertype of  T .  When we try to eliminate the type parameters we find that we can easily replace the type parameter  S by a wildcard, but we cannot get rid of the type parameter  T . This is because there is no way to express by means of wildcards that the  fill method takes an argument of unknown type.  We could try something like this: Example (of the same method with wildcards; does not work):   public static  void fill( List <?> list,  Object obj) {   int size = list.size();   ListIterator <?> itr = list.listIterator();   for (int i = 0; i < size; i++) {     itr.next();     itr.set(obj);  // error   } } The first problem is that this version does not compile; the problem can be reduced to an unchecked warning by using a raw type  ListIterator instead of the unbounded wildcard  ListIterator<?> .  But the the real issues is that this signature gives up the relationship between the element type of the list and the type of the object used for filling the list.  A semantically equivalent version of the  fill method would look like this: Example (of the same method with wildcards):   public static  <T>  void fill( List <? super T> list,  T obj) {   int size = list.size();     ListIterator <? super T> itr = list.listIterator();     for (int i = 0; i < size; i++) {       itr.next();       itr.set(obj);   } } Now, we have successfully eliminated the need for the type parameter  S , which stands for the list's element type, by using the " ? super T " wildcard, but we still need the type parameter  T .  To this regard the example is similar to the copy method discussed earlier, because we can reduce the number of type parameters by means of wildcards, but we cannot entirely eliminate the type parameters.  Which version is better is a matter of style and taste. Conclusion:  In all these examples it is mostly a matter of taste and style whether you prefer the generic or the wildcard version.  There is usually trade-off between ease of implementation (the generic version is often easier to implement) and complexity of  signature (the wildcard version has fewer type parameters or none at all).
LINK TO THIS	Practicalities.FAQ302A
REFERENCES	Should I use wildcards in the return type of a method? Which methods and fields are accessible/inaccessible through a reference variable of a wildcard type? What is the capture of a wildcard? 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?

Under which circumstances do the generic version and the wildcard version of a method mean different things?
 

When a type parameter appears repeatedly in a generic method signature and in case of multi-level wildcards.
In many situations we can replace wildcards by type parameters and vice versa.  For example, the following two signatures are semantically equivalent:       void reverse( List <?> list) { ...  } <T> void reverse( List <T> list) { ... } In the previous entry we saw several examples of equivalent method signature, but there are also situations in which the generic version and the wildcard version of a method signature mean different things. These situations include generic method signature in which a type parameter appears repeated  and method signatures in which multi-level wildcards, such as  List<Pair<?,?>> , appear.  In the following we study a couple of examples. Case Study #1 Let us consider the implementation of a  reverse method.  It is slightly different from the  reverse method we discussed in the previous entry. The key difference is that the  List type, and with it the type parameter  T , appears twice in the method's signature: in the argument type and the return type.  Let's start again with the generic version of  the  reverse method. Example (of a method with type parameters):   public static  <T> List <T> reverse( List <T> list) {   List<T> tmp = new ArrayList<T>(list);   for (int i = 0; i < list.size(); i++) {     tmp.set(i, list.get(list.size() - i - 1));   }   return tmp; } If we tried to declare this method as a non-generic method using wildcards, a conceivable signature could look like this. Example (of the same method with wildcards; does not compile):   public static  List <?> reverse( List <?> list) {   List<?> tmp = new ArrayList<?>(list);  // error   for (int i = 0; i < list.size(); i++) {     tmp.set(i, list.get(list.size() - i - 1));  // error   }   return tmp; } The first problem is that this version does not compile; the problem can be reduced to an unchecked warning by using the raw types  List and  ArrayList instead of the unbounded wildcards  List<?>  and ArrayList<?> .  Even the warnings can be eliminated by relying on wildcard capture and using a generic helper method.  But one fundamental issue remains: the wildcard version has an entirely different semantic meaning compared to the generic version.  The generic version is saying:  the  reverse method accepts a list with a certain, unknown element type and returns a list of that same type.  The wildcard version is saying:  the  reverse method accepts a list with a certain, unknown element type and returns a list of  a potentially different type.  Remember, each occurrence of a wildcard stands for a potentially different type.  In principle, the  reverse method could take a  List<Apple> and return a  List<Orange> . There is nothing in the signature or the implementation of the  reverse method that indicates that "what goes in does come out".  In other words, the wildcard signature does not reflect our intent correctly. Conclusion:  In this example it the generic version and the wildcard version have different meaning.  Case Study #2 Another example where more than one wildcard occurs in the signature of the method. Example (of a method with type parameters):   class Pair<S,T> {   private S first;   private T second;   ...   public Pair(S s,T t) { first = s; second = t; }   public static  <U> void flip( Pair <U,U> pair) {       U tmp = pair.first;      pair.first = pair.second;       pair.second = tmp;    } }  When we try to declare a wildcard version of the generic  flip method we find that there is no way of doing so.  We could try the following: Example (of the same method with wildcards; does not compile):   class Pair<S,T> {   private S first;   private T second;   ...   public Pair(S s,T t) { first = s; second = t; }   public static void flip( Pair <?,?> pair) {     Object tmp = pair.first;     pair.first = pair.second;  // error: imcompatible types     pair.second = tmp;  // error: imcompatible types   } }  But this wildcard version does not compile, and rightly so.  It does not make sense to flip the two parts of a  Pair<?,?> .  Remember, each occurrance of a wildcard stands for a potentially different type.  We do not want to flip the two parts of a pair, if the part are of different types.  This additional requirement, that the parts of the pair must be of the same type, cannot be expressed by means of wildcards.  The wildcard version above would be equivalent to the following generic version: Example (of the generic equivalent of the wildcard version; does not compile):   class Pair<S,T> {   private S first;   private T second;   ...   public Pair(S s,T t) { first = s; second = t; }   public static  <U,V> void flip( Pair <U,V> pair) {      U tmp = pair.first;      pair.first = pair.second;  // error: imcompatible types      pair.second = tmp;  // error: imcompatible types   } }  Now it should be obvious that the wildcard version simply does not express our intent.  Conclusion:  In this example only the generic version allows to express the intent correctly. Case Study #3 If a method signature uses multi-level wildcard types then there is always a difference between the generic method signature and the wildcard version of it. Here is an example.  Assume there is a generic type  Box and we need to declare a method that takes a list of boxes. Example (of a method with a type parameter): public static  <T> void print1( List <Box<T>> list) {   for (Box<T> box : list) {     System.out.println(box);   } } Example (of method with wildcards):   public static void print2( List <Box<?>> list) {   for (Box<?> box : list) {     System.out.println(box);   } } Both methods are perfectly well behaved methods, but they are not equivalent.  The generic version requires a homogenous list of boxes of the same type.  The wildcard version accepts a heterogenous list of boxes of different type.  This becomes visible when the two  print methods are invoked.  Example (calling the 2 versions):   List <Box<?>> list1 = new ArrayList<Box<?>>(); list1.add(new Box<String>("abc")); list1.add(new Box<Integer>(100)); print1(list1);  // error print2(list1);  // fine List <Box<Object>> list2 = new ArrayList<Box<Object>>(); list2.add(new Box<Object>("abc")); list2.add(new Box<Object>(100)); print1(list2);  // fine print2(list2); // error error: <T>print1( Box<T>>) cannot be applied to ( Box<?>>)         print1(list1);          ^ error: print2( Box<?>>) cannot be applied to ( Box<Object>>)         print2(list2);          ^ First, we create a list of boxes of different types and stuff a  Box<String> and a  Box<Integer> into the list. This heterogenous list of type  List<Box<?>> cannot be passed to the generic method, because the generic method expects a list of boxes of the same type. Then, we create a list of boxes of the same type, namely of type  Box<Object> , and we stuff two  Box<Object> objects into the list.  This homogenous list of type  List<Box<Object>>   cannot be passed to the wildcard method, because the wildcard method expects a list of boxes, where there is no restriction regarding the type of the boxes. Let us consider a third version of the  print method, again with wildcards, but more relaxed so that it accepts either type of list, the homogenous and the heterogenous list of boxes. Example (of another wildcard version):   public static void print3( List <? extends Box<?>> list) {   for (Box<?> box : list) {     System.out.println(box);   } } Example (calling all 3 versions):   List <Box<?>> list1 = new ArrayList<Box<?>>(); list1.add(new Box<String>("abc")); list1.add(new Box<Integer>(100)); print1(list1);  // error print2(list1);  // fine print3(list1);  // fine List <Box<Object>> list2 = new ArrayList<Box<Object>>(); list2.add(new Box<Object>("abc")); list2.add(new Box<Object>(100)); print1(list2);  // fine print2(list2);  // error print3(list2);  // fine No matter how we put it, the generic version and the wildcard versions are not equivalent. Conclusion: In this example it the generic version and the wildcard version have different meaning.
uiLINK TO THIS	Practicalities.FAQ302B
REFERENCES	What do multi-level wildcards mean? If a wildcard appears repeatedly in a type argument section, does it stand for the same type? Which methods and fields are accessible/inaccessible through a reference variable of a wildcard type? What is the capture of a wildcard? Under which circumstances are the generic version and the wildcard version of a method equivalent? Under which circumstances is there no transformation to the wildcard version of a method possible?

Under which circumstances is there no transformation to the wildcard version of a method possible?
 

I f a type parameter has more than one bound.
Wildcards can have at most one upper bound, while type parameters can have several upper bounds.  For this reason, there is not wildcard equivalent for generic method signatures with type parameter with several bounds.  Here is an example. Example (of a method with a type parameter with more than one bound):   public interface State {   boolean isIdle(); } public static  <T extends Enum<T> & State> boolean hasIdleState( EnumSet <T> set) {   for (T state : set)      if (state.isIdle()) return true;   return false; } This  hasIdleState method has a type parameter that must be a enum type that implements the  State interface.  The requirement of both being an enum type and implementing an interface cannot be expressed by means of wildcards.  If we tried it it would look like this: Example (of the same method without type parameters; does not compile):   public static boolean hasIdleState( EnumSet <? extends Enum<?> & State> set) {  // error   ... } This attempt fails because a wildcard cannot have two bounds and for this reason the expression " ? extends Enum<?> & State " is illegal syntax.  Conclusion: In this example there is no way to find an equivalent version with wildcards and the generic version is the only viable solution.
uiLINK TO THIS	Practicalities.FAQ302C
REFERENCES	What is the difference between a wildcard bound and a type parameter bound? 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?

Should I use wildcards in the return type of a method?

public abstract class 
Reference<T>
 {


 public T get() { ... }
 public void clear() { ... }
 ...



}

public class 

WeakReference<T>
 extends Reference<T> {

 public WeakReference(T referent) { ... }
 public WeakReference(T referent, 
ReferenceQueue<? super T>
 q) { .. }
}

public class 

ReferenceQueue<T>
 {

 public

 




Reference<? extends T> 
remove

() { ... }


 public

 




Reference<? extends T> 
remove

(long timeout) { ... }


 public

 





Reference<? extends T>
 
poll() { ... }
}

public abstract class 
Reference<T>
 {

 ReferenceQueue<? super T> queue;
 Reference(T referent) { 

... }


 
Reference(T referent, 

ReferenceQueue<? super T>

 queue) { 



... }




 public T get() { ... }
 public void clear() { ... }
 ...



}

public class 

ReferenceQueue<T>
 {

 
boolean enqueue(

Reference<? extends T>

 ref) { ... }



 public

 




Reference<? extends T> 
remove

() { ... }


 public

 




Reference<? extends T> 
remove

(long timeout) { ... }


 public

 




Reference<? extends T> 
poll() { ... }
}

public abstract class 
Reference<T>
 {

 ReferenceQueue<T> queue;
 Reference(T referent) { 

... }


 Reference(T referent, 


ReferenceQueue<T>
 queue) { 

... }





 public T get() { ... }
 public void clear() { ... }
 ...



}

public class 

ReferenceQueue<T>
 {

 boolean enqueue(


Reference<T>

 
ref) { ... }


 public

 






Reference<T> 
remove

() { ... }


 public

 




Reference<T> 
remove

(long timeout) { ... }


 public

 





Reference<T>




 
poll() { ... }
}

How do I implement a method that takes a wildcard argument?
 

Using a generic helper method and wildcard capture.
Consider the situation where you decided that a certain method should take arguments whose type is a wildcard parameterized type.  When you start implementing such a method you will find that you do not have full access to the argument.  This is because wildcards do not permit certain operations on the wildcard parameterized type.  Example (implementation of a reverse method with wildcards; does not work):  public static void reverse(List <?> list) {   List<?> tmp = new ArrayList<?> (list); // error   for (int i=0;i<list.size();i++){     tmp. set (i,list.get(list.size()-i-1)); // error   }   list = tmp; } Using the wildcard type List<?> we can neither create a temporary copy of the argument nor can we invoke the set method.  A workaround, that works in this particular case, is use of wildcard capture and a generic helper method.  Example (corrected implementation of a reverse method with wildcards):  public static void reverse(List <?> list) {   rev(list); } private static <T> void rev(List <T> list) {   List<T> tmp = new ArrayList<T>(list);   for (int i=0;i<list.size();i++){     tmp.set(i,list.get(list.size()-i-1));   }   list = tmp; } Wildcard capture makes it possible to invoke a generic helper method.  The helper method does not use any wildcards; it is generic and has a type parameter instead.  It has unrestricted access to its arguments' methods and can provide the necessary implementation.  Since the helper method has the exact same functionality as the original method and permits the same set of argument types, one might consider using it instead of the method with the wildcard argument in the first place.  Example (generic version of the reverse method):  public static <T> void reverse(List <T> list) {   List<T> tmp = new ArrayList<T>(list);   for (int i=0;i<list.size();i++){     tmp.set(i,list.get(list.size()-i-1));   }   list = tmp; }
LINK TO THIS	Practicalities.FAQ304
REFERENCES	What is the capture of a wildcard? What is a parameterized (or generic) method? Can I use a wildcard parameterized type like any other type? Can I create an object whose type is a wildcard parameterized type?

How do I implement a method that takes a multi-level wildcard argument?
 

Using several  generic helper methods and wildcard capture.
Here is a an example of a method whose argument and return type is a multi-level wildcard. It is a method that takes a list whose element type is an arbitrary  pair type and return such a list.  The swapAndReverse method reverses the order all the list elements and swaps the members of each pair.  It is a contrived example for the purpose of illustrating the implementation technique.  Example:  class Pair<E> {   private E fst, snd;   public E getFirst() { return fst; }   public void setFirst(S s) { fst = s; }   ... } class Test {   public static ArrayList<? extends Pair<?>> swapAndReverse(ArrayList <? extends Pair<?>> l) {     ...    }   public static void main(String[] args) {         ArrayList<Pair<Integer>> list = new ArrayList<Pair<Integer>>();         list.add(new Pair<Integer>(-1,1,0));         list.add(new Pair<Integer>(1,0,0));         ...         List<?> result = swapAndReverse(list);         ArrayList<Pair<?>> list = new ArrayList<Pair<?>>();         list.add(new Pair<String>("a","b","c"));         list.add(new Pair<Integer>(1,0,-1));         list.add(new Pair<Object>(new Date(),Thread.State.NEW,5));         ...         List<?> result = swapAndReverse(list);   } } The swapAndReverse method can be invoked on homogenous lists of pairs of the same type, such as a ArrayList<Pair<Integer>> , but also on a heterogenous list of pairs of different types, such as ArrayList<Pair<?>> .  When we try to implement the method we find that the wildcard argument type does not permit invocation of the operations that we need.  Example (implementation of a swapAndReverse method with wildcards; does not work):  public static ArrayList<? extends Pair<?>> swapAndReverse(ArrayList <? extends Pair<?>> l) {   ArrayList<? extends Pair<?>> list      = new ArrayList<? extends Pair<?>> (l); // error   for (int i=0;i<l.size();i++){     list. set (i,l.get(l.size()-i-1)); // error   }   for (Pair<?> pair : list) {     Object e = pair.getFirst();     pair. setFirst (pair.getSecond()); // error     pair. setSecond (e);   // error   }   return list; } We cannot create a temporary copy of the list and cannot access the individual pairs in the list.  Hence we apply the capture-helper technique from above.  Example (implementation of a swapAndReverse method with helper method; does not work):  public static ArrayList<? extends Pair<?>> swapAndReverse(ArrayList <? extends Pair<?>> l) {   return capturePairType(l); } private static <T extends Pair<?>> ArrayList<T> capturePairType(ArrayList <T> l) {   ArrayList<T> list = new ArrayList<T>(l);   for (int i=0;i<l.size();i++){     list.set(i,l.get(l.size()-i-1));   }   for (T pair : list) {     Object e = pair.getFirst();     pair. setFirst (pair.getSecond()); // error     pair. setSecond (e);   // error   }   return list; } The compiler will capture the type of the pairs contained in the list, but we still do not know what type of members the pairs have. We can use the capture-helper technique again to capture the pairs' type argument.  Example (corrected implementation of a swapAndReverse method with wildcards): public static ArrayList<? extends Pair<?>> swapAndReverse(ArrayList <? extends Pair<?>> l) {   return capturePairType(l); } private static <T extends Pair<?>> ArrayList<T> capturePairType(ArrayList <T> l) {   ArrayList<T> list = new ArrayList<T>(l);   for (int i=0;i<l.size();i++){     list.set(i,l.get(l.size()-i-1));   }   for (T pair : list) {     captureMemberType(pair);   }   return list; } private static <E> void captureMemberType(Pair <E> pair) {   E e = pair.getFirst();   pair.setFirst(pair.getSecond());   pair.setSecond(e); } In this case there is no alternative to the stepwise application of the capture-helper technique.  A generic version of the swapAndReverse method would have slightly different semantics. Example (parameterized version of the swapAndReverse method):  public static  < E ,T extends Pair <E> > ArrayList<T> swapAndReverse(ArrayList <T> l) {   ArrayList<T> list = new ArrayList<T>(l);   for (int i=0;i<l.size();i++){     list.set(i,l.get(l.size()-i-1));   }   for (T pair : list) {     E e = pair.getFirst();     pair.setFirst(pair.getSecond());     pair.setSecond(e);   }   return list; } This version of the swapAndReverse method has one disadvantage:  it does not accept a mixed list of pairs of arbitrary types, such as ArrayList<Pair<?>> .  Example:  class Test {   public static void main(String[] args) {         ArrayList<Pair<Integer>> list = new ArrayList<Pair<Integer>>();         list.add(new Pair<Integer>(-1,1,0));         list.add(new Pair<Integer>(1,0,0));         ...         List<?> result = swapAndReverse(list);         ArrayList<Pair<?>> list = new ArrayList<Pair<?>>();         list.add(new Pair<String>("a","b","c"));         list.add(new Pair<Integer>(1,0,0));         list.add(new Pair<Object>(new Date(),Thread.State.NEW,5));         ...         List<?> result = swapAndReverse(list);  // error   } } error: <E,T>swapAndReverse(java.util.ArrayList<T>) in Test cannot be applied to (java.util.ArrayList<Pair<?>>)       List<?> result = swapAndReverse(list);                        ^ On the other hand, the generic swapAndReverse method has the advantage that it returns a concrete instantiation of ArrayList , that does not suffer from the limitations that come with the wildcard instantiation that is returned from the wildcard version of the swapAndReverse method.
LINK TO THIS	Practicalities.FAQ305
REFERENCES	How do I implement a method that takes a wildcard argument? What do multi-level wildcards mean? What is the capture of a wildcard? What is a parameterized or generic method? What is a bounded type parameter? Which types are permitted as type parameter  bounds? Can I use a type parameter as part of its own bounds or in the declaration of other type parameters? Can I use a wildcard parameterized type like any other type? Can I create an object whose type is a wildcard parameterized type?

I want to pass a U and a X<U> to a method.  How do I correctly declare that method?
 

Using an upper bound wildcard parameterized type instead of a concrete parameterized type as the argument type.
Example (has a bug):  interface Acceptor<V> {   void accept( Task<V> task, V v); } interface Task<U> {   void go(Acceptor<? super U> acceptor); } class AcceptingTask<U> implements Task<U> {   public void go(Acceptor<? super U> acceptor) {     U result = null;      ... produce result ...      acceptor.accept(this, result);  // error   } } error: accept(Task<capture of ? super U>,capture of ? super U)  in Acceptor<capture of ? super U> cannot be applied to (AcceptingTask<U>,U)           acceptor.accept(this, result);                   ^ This is the example of a callback interface Acceptor and its accept method which takes  result-producing task and the result. Note that the accept method takes a result of type V and a corresponding task of type Task<V> .  The task is described by an interface Task .  It has a method go that is supposed to produce a result and takes an Acceptor , to which it passes the result.  The class AcceptingTask is an implementation of the Task interface and in its implementation of the go method we see an invocation of the accept method.  This invocation fails.  The problem with this invocation is that the accept method is invoked on a wildcard instantiation of the Acceptor , namely Acceptor<? super U> .  Access to methods through wildcard parameterized types is restricted.  The error message clearly indicates the problem.  Method accept in  Acceptor<? super U> expects a Task<capture of ? super U> and a capture of ? super U . What we pass as arguments are a AcceptingTask<U> and a U .  The argument of type U is fine because the declared argument type is an unknown supertype of U .  But the argument of type AcceptingTask<U> is a problem. The declared argument type is an instantiation of Task for an unknown supertype of U . The compiler does not know which supertype and therefor rejects all argument types.  The crux is that the signature of the accept method is too restrictive. If we would permit instantiations of Task for subtypes of U , then it would work.  Example (corrected):  interface Acceptor<V> {   void accept( Task< ? extends V> task, V v); } interface Task<U> {   void go(Acceptor<? super U> acceptor); } class AcceptingTask<U> implements Task<U> {   public void go(Acceptor<? super U> acceptor) {     U result = null;      ... produce result ...      acceptor.accept(this, result);  // fine   } } With this relaxed signature the accept method  in  Acceptor<? super U> expects a Task<? extends capture of ? super U> , that is, an instantiation of Task for a subtype of a supertype of U and Task<U> meets this requirement.  The common misunderstanding here is that the signature accept(Task<V> task, V v) looks that I can pass a Task<U> whenever I can pass a U .  This is true for concrete instantiations of the enclosing type, but not when wildcard instantiations are used.  The accessibility rules for methods that take the type parameter such as V as an argument and methods that take a parameterized type instantiated on the type parameter such as Task<V> are very different.  The solution to the problem is relaxing the signature by using a wildcard parameterized type as an argument type instead of a concrete parameterized type.
LINK TO THIS	Practicalities.FAQ306
REFERENCES	Which methods and fields are accessible/inaccessible through a reference variable of a wildcard parameterized type? Which methods that use the type parameter in the argument or return type are accessible in an unbounded wildcard parameterized type? Which methods that use the type parameter in the argument or return type are accessible in an upper bound wildcard parmeterized type? Which methods that use the type parameter in the argument or return type are accessible in a lower bound wildcard parameterized type? Which methods that use the type parameter as type argument of a parameterized argument or return type are accessible in a wildcard parameteriezed type? 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?