java generic method: Practical Usage and Code Examples

When you write a java generic method, you declare a type parameter before the return type. This lets the method operate on values of different types while preserving compile-time type checking. The syntax is simple, but the behavior under the hood is more subtle.

Declaring a Generic Method

A generic method introduces its own type parameter in angle brackets before the return type. The type parameter can appear in the parameter list, the return type, or both.

public static <T> T identity(T value) {
    return value;
}

The <T> declares a type variable that is scoped to the method. The compiler infers the actual type from the arguments when the method is called. This is distinct from a generic class, where the type parameter is part of the class declaration and fixed for each instance.

public class Box<T> {
    private T content;
    public void set(T content) { this.content = content; }
    public T get() { return content; }
}

A generic method can be static, which is not possible with a generic class's type parameter. Static methods cannot reference a class-level type parameter because the type parameter is tied to an instance. A generic method solves this by declaring its own type parameter.

Type Inference and Explicit Type Arguments

When calling a generic method, the compiler usually infers the type argument from the method arguments and the expected return type. In most cases you do not need to specify the type explicitly.

String s = identity("hello");
Integer i = identity(42);

The compiler infers String for the first call and Integer for the second. Inference also works when the return type is assigned to a variable, but it can fail when the method is used in a context where no target type is available, such as a standalone expression.

If inference is ambiguous or you want to force a specific type, use the explicit type argument syntax:

Object obj = MyClass.<Object>identity("hello");

The type argument appears between the method name and the argument list. This is rarely needed but can be necessary when the compiler cannot infer the type from the context, such as when passing the method reference to a generic functional interface.

Bounded Type Parameters

A type parameter can be restricted to a specific type or a subtype using the extends keyword. This allows the method to call methods on the type without casting.

public static <T extends Number> double sum(T a, T b) {
    return a.doubleValue() + b.doubleValue();
}

Here T must be a subtype of Number. The compiler guarantees that any type argument passed to sum has a doubleValue() method. Without the bound, the method would not compile because T is treated as Object.

Multiple bounds are separated by &:

public static <T extends Comparable<T> & Serializable> void sort(T[] array) {
    // ...
}

The first bound must be a class or interface; subsequent bounds must be interfaces. The class bound, if any, must come first.

Bounds are useful when the method needs to rely on a specific contract. For example, a generic max method can require Comparable:

public static <T extends Comparable<T>> T max(T a, T b) {
    return a.compareTo(b) >= 0 ? a : b;
}

Generic Methods and Wildcards

Wildcards (?) are used in generic types to represent an unknown type. A generic method and a wildcard can sometimes achieve similar goals, but they differ in flexibility and intent.

Consider a method that copies elements from one list to another:

public static <T> void copy(List<? extends T> src, List<? super T> dest) {
    for (T item : src) {
        dest.add(item);
    }
}

The wildcard ? extends T allows reading from a list of any subtype of T, while ? super T allows writing to a list of any supertype of T. This is the standard producer-extends, consumer-super (PECS) pattern.

A generic method can also be written without wildcards by using a single type parameter, but that would be less flexible:

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

This only works when both lists have exactly the same type argument. The wildcard version accepts List<Integer> as source and List<Number> as destination, which is often more useful.

Use a generic method when the type parameter appears in multiple places and you need to relate them. Use a wildcard when you only need to accept a range of types without needing to name the type.

Common Pitfalls: Erasure and Static Context

Java generics are implemented via type erasure. The compiler removes all type parameters and replaces them with their leftmost bound, or Object if no bound is declared. This has several consequences.

First, you cannot check the type parameter at runtime. The following code does not compile:

public static <T> void check(Object obj) {
    if (obj instanceof T) { // error: illegal generic type for instanceof
    }
}

Second, you cannot create an array of a type parameter:

public static <T> T[] createArray(int size) {
    return new T[size]; // error: generic array creation
}

Instead, you can create an array of the erasure type and cast it, but this produces an unchecked warning. In practice, prefer List<T> over T[] when the element type is generic.

Third, a static method cannot use a class-level type parameter, but it can declare its own. This is a common confusion. The following is valid:

public class Util {
    public static <T> T get(T value) { return value; }
}

But this is not:

public class Box<T> {
    public static T get() { return null; } // error: non-static type variable T cannot be referenced from a static context
}

Because T belongs to the instance, not the class.

Another pitfall is method overloading. Two generic methods with the same erasure cannot coexist. For example, void print(List<String>) and void print(List<Integer>) both erase to void print(List), causing a compile-time conflict.

Runtime Behavior and Performance

Type erasure means generic methods do not incur runtime overhead for type checking. The compiler inserts casts where necessary, but the method itself runs on the erased type. This keeps performance close to non-generic code.

However, erasure can introduce hidden casts. When you call a generic method that returns T, the compiler inserts a cast to the inferred type at the call site. If the method returns a type that does not match the expected type, a ClassCastException can occur at runtime, even though the method itself is type-safe.

For example:

public static <T> T unsafeCast(Object obj) {
    return (T) obj;
}

This method is legal but dangerous. The cast to T is unchecked and will not be verified at runtime. Calling unsafeCast("hello") and assigning the result to an Integer will throw a ClassCastException at the assignment point, not inside the method. Avoid such patterns unless you are certain about the type.

Generic methods also cannot be overloaded solely on type parameter bounds. The erasure of <T extends Number> void foo(T) and <T extends String> void foo(T) is the same, so they cannot coexist.

Choosing Between Generic Method and Generic Class

A generic method is appropriate when the type parameter is local to a single operation. If multiple methods in a class share the same type parameter, a generic class is usually cleaner.

Use a generic method when:

The type parameter appears only in the method signature.
The method is static and needs its own type parameter.
The method is a utility that operates on different types without maintaining state.

Use a generic class when:

The type parameter is part of the object's state, such as a collection or container.
Multiple methods need to to use the same type consistently.
The type is known when the object is created and does not change.

For example, a Repository<T> class that stores and retrieves entities of type T is better as a generic class. A static Collections.sort(List<T>) method is better as a generic method.

Edge Cases: Varargs and Checked Exceptions

Generic methods can accept varargs, but there is a subtle issue. Because the varargs array is created at the call site with the erasure type, you may get a heap pollution warning.

public static <T> void addAll(List<? super T> list, T... items) {
    for (T item : items) {
        list.add(item);
    }
}

The T... is treated as Object[] at runtime. If you pass a String[], it is safe, but if you pass a generic type like List<String>[], the array will be an Object[] and can cause a ClassCastException later. The @SafeVarargs annotation can suppress the warning, but only when the method does not modify the varargs array in a way that could corrupt the heap.

n Another edge case involves checked exceptions. A generic method can declare a type parameter that extends Exception, allowing callers to catch a specific exception type without wrapping.

public static <E extends Exception> void throwIt(Exception cause) throws E {
    throw (E) cause;
}

This is a known pattern for sneaky throws, but it is controversial because it bypasses checked exception guarantees. Use it sparingly and only when you have full control over the exception propagation.

Compatibility with Legacy Code

Generic methods interact with raw types and legacy code. If you call a generic method with a raw type, the compiler emits unchecked warnings. For example:

List list = new ArrayList();
Collections.sort(list); // raw use of generic method

This compiles but may produce a warning. The The compiler cannot verify that the list contains comparable elements. In a mixed codebase, you may need to suppress warnings or add explicit casts.

When migrating legacy code to generics, generic methods can gradually replace raw casts. The compiler will help identify missing type arguments. However, you cannot change a method's erasure without breaking binary compatibility. If a method was compiled as Object before, changing it to <T> may change the signature and require recompilation of callers.

Practical Example: A Generic Method for Sorting

Let's combine the concepts with a realistic example. The following method sorts a list of any type that implements Comparable:

public static <T extends Comparable<? super T>> void sort(List<T> list) {
    for (int i = 0; i < list.size(); i++) {
        for (int j = i + 1; j < list.size(); j++) {
            if ( (list.get(i).compareTo(list.get(j))) > 0) {
                T temp = list.get(i);\n                list.set(i, list.get(j));
                list.set(j, temp);
            }
        }
    }
}

The bound T extends Comparable<? super T> is the standard way to require that T is comparable to itself. The wildcard ? super T allows types like String, which implements Comparable<String>, and also types that implement a supertype's Comparable, such as a subclass of a comparable base class.

This method is not efficient for large lists, but it demonstrates the syntax and bounds. In production, use Collections.sort or List.sort, which use optimized algorithms.

Type Inference with Method References

Generic methods can be used as method references, but type inference can be tricky. For example, given a generic method identity, you cannot directly assign it to a Function<String,, String> without specifying the type argument:

Function<String, String> f = MyClass::identity; // error: cannot infer type

You need to use an explicit type argument:

Function<String, String> f = MyClass::<String>identity;

This is a common source of confusion. The compiler cannot infer the type argument from the target type in all cases. When it fails, provide the type argument explicitly.

Another approach is to use a lambda instead of a method reference:

Function<String, String> f = s -> MyClass.identity(s);
```\nThis works because the lambda provides the argument type, and the compiler can infer `T` from the argument.


## Final Code Example: A Generic Method for Merging Maps

A practical use case is merging two maps with a generic method that preserves the value type. The method takes two maps and a merge function, and returns a new map with the merged values.

```java
public static <K, V> Map<K,, V> merge(Map<? extends K, ? extends V> m1,
                                    Map<? extends K, ? extends V>> m2,
                                    BiFunction<? super V,, ? super V, ? extends V> mergeFunction) {
    Map<K, V>> result = new HashMap<>(m1);\n    m2.forEach((key, value)) -> result.merge(key, value, mergeFunction));
    return result;
}

This method uses multiple type parameters (K and V) and wildcards to accept maps with subtypes. The BiFunction parameter allows the caller to control how duplicate keys are handled. The method is reusable across different key and value types, and it preserves type safety without casting.

This example shows how generic methods can be composed with other generic APIs to build flexible utilities. The key is to keep the type parameters explicit and use wildcards only at the boundaries where you need flexibility.