https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Return to Effective Java, Java Best Practices, Java Style Guides, Java

In Java, generics offer a powerful way to create flexible and type-safe APIs. Bounded wildcards (`? extends T` and `? super T`) further enhance this flexibility by allowing you to specify upper or lower bounds on the types that can be used with a generic class, method, or interface. Using bounded wildcards effectively is a best practice that can make your APIs more adaptable while maintaining type safety and ensuring that your code can handle a wide range of types.

A bounded wildcard in Java generics is a special type of wildcard that imposes a restriction (or bound) on the types it can represent. There are two types of bounded wildcards: 1. **Upper-bounded wildcard (`? extends T`)**: This wildcard allows you to specify that a type can be any subtype of a given class or interface `T`. It’s useful when you want to read items from a collection and know that they will be at least of type `T`. 2. **Lower-bounded wildcard (`? super T`)**: This wildcard allows you to specify that a type can be any supertype of a given class or interface `T`. It’s useful when you want to write items into a collection and ensure that the collection can accept any object that is a superclass of `T`.

Using bounded wildcards increases the flexibility of your API by allowing it to work with a wider range of types. This flexibility is particularly useful when dealing with collections or generic methods that need to operate on a variety of related types. Additionally, bounded wildcards help you maintain type safety by ensuring that only types that meet certain criteria can be used, reducing the risk of runtime errors.

Here’s an example of using an upper-bounded wildcard to create a method that processes a list of any subtype of `Number`:

```java import java.util.List;

public class UpperBoundExample {

   public static double sum(List numbers) {
       double sum = 0.0;
       for (Number number : numbers) {
           sum += number.doubleValue();
       }
       return sum;
   }

   public static void main(String[] args) {
       List integers = List.of(1, 2, 3);
       List doubles = List.of(1.1, 2.2, 3.3);

       System.out.println("Sum of integers: " + sum(integers)); // Works with Integer
       System.out.println("Sum of doubles: " + sum(doubles)); // Works with Double
   }

In this example, the `sum` method uses an upper-bounded wildcard `List<? extends Number>`, which allows it to accept a list of any subtype of `Number`, such as `Integer`, `Double`, or `Float`. This flexibility allows the method to be used with different numeric types while maintaining type safety.

Here’s an example of using a lower-bounded wildcard to create a method that adds elements to a collection:

```java import java.util.List; import java.util.ArrayList;

public class LowerBoundExample {

   public static void addNumbers(List list) {
       list.add(1);
       list.add(2);
       list.add(3);
   }

   public static void main(String[] args) {
       List numbers = new ArrayList<>();
       addNumbers(numbers);

       for (Number number : numbers) {
           System.out.println(number);
       }
   }

In this example, the `addNumbers` method uses a lower-bounded wildcard `List<? super Integer>`, which allows it to accept a list of any type that is a superclass of `Integer`, such as `Number` or `Object`. This ensures that the method can add `Integer` elements to the list without risking a type mismatch.

Sometimes, you may need to combine upper and lower bounds to create more complex and flexible APIs. While this can increase the power of your code, it’s important to keep the logic clear and straightforward to avoid confusing the users of your API.

Here’s an example that combines upper and lower bounds in a single method:

```java import java.util.List;

public class BoundedWildcardExample {

   public static  void copy(List dest, List src) {
       for (T item : src) {
           dest.add(item);
       }
   }

   public static void main(String[] args) {
       List numbers = new ArrayList<>();
       List integers = List.of(1, 2, 3);

       copy(numbers, integers);

       for (Number number : numbers) {
           System.out.println(number);
       }
   }

In this example, the `copy` method uses both an upper-bounded wildcard `List<? extends T>` for the source list and a lower-bounded wildcard `List<? super T>` for the destination list. This setup allows the method to copy elements from a list of any subtype of `T` into a list of any supertype of `T`, providing maximum flexibility while maintaining type safety.

While bounded wildcards are powerful, they can also introduce complexity if not used carefully. Common pitfalls include over-complicating the method signatures or misapplying bounds, which can lead to confusing API designs. It’s essential to use bounded wildcards judiciously and only when they add clear value to your API.

To make the most of bounded wildcards in your APIs, follow these tips: 1. **Use upper bounds (`? extends T`) when you need to read from a collection** and ensure type safety for the objects you are processing. 2. **Use lower bounds (`? super T`) when you need to write to a collection** and ensure that the collection can accept a range of types. 3. **Combine bounds only when necessary** and ensure that the method’s purpose is clear and the API remains intuitive to use. 4. **Document the behavior and expectations of methods using bounded wildcards** to make it easier for other developers to understand how to use them correctly.

In conclusion, using bounded wildcards in Java is a best practice that can greatly increase the flexibility and versatility of your APIs. By carefully applying upper-bounded and lower-bounded wildcards, you can create methods and classes that work with a wide range of types while maintaining type safety. This approach leads to more reusable and adaptable code, helping you build more robust and maintainable applications.

For more information on bounded wildcards and generics in Java, consider exploring the following resources:

• https://docs.oracle.com/javase/tutorial/java/generics/wildcards.html
• https://en.wikipedia.org/wiki/Generics_in_Java
• https://github.com/iluwatar/java-design-patterns/tree/master/generics

These resources provide additional insights and best practices for using bounded wildcards effectively in Java.

Fair Use Sources:

• Use bounded wildcards to increase API flexibility
• Java Best Practices and Core Guidelines
• Effective Java on DuckDuckGo - B078H61SCH (EffJav 2017)
• The Borg

• Effective Java for Archive Access for Fair Use Preservation, quoting, paraphrasing, excerpting and/or commenting upon