What is the purpose of additional diamond parameters in a method signature (that look like an additional return type(s))?

Question

I have the following class which builds:

public class Test<T> {
    public T DoSomething(T value) {
        return value;
    }
}

I can also define it like this class like this (notice the extra in the DoSomething signature (which also builds):

public class Test<T> {
    public <T> T DoSomething(T value) {
        return value;
    }
}

What is its purpose and when do I need to include it? I am asking about the additional <T> in the return type, not what generics are.

Answer 1

Maybe this will clear it up. The notation <T> declares a type variable.

So we have one variable T at the class level, and a redeclaration of that same symbol for a particular method.

class Test<T> {
    <T> T doSomething(T value) {
        // <T> declares a new type variable for this one method
        System.out.println("Type of value: " + value.getClass().getSimpleName());
        return value;
    }
    T doSomethingElse(T value) {
        // T is not redeclared here, thus is the type from the class declaration
        System.out.println("Type of value: " + value.getClass().getSimpleName());
        return value;
    }
    public static void main(String... a) {
        Test<String> t = new Test<>();
        t.doSomething(42);
        t.doSomething("foo"); // also works
        t.doSomething(t); // contrived, but still works
        t.doSomethingElse("hi");
        t.doSomethingElse(42); // errors because the type `T` is bound to `String` by the declaration `Test<String> t`
    }
}

In main, I create a Test<String> so the class-level T is String. This applies to my method doSomethingElse.

But for doSomething, T is redeclared. If I call the method with an Integer arg, then T for that case is Integer.

Really, it would have been better to call the second type variable anything else at all, on the declaration of doSomething. U, for example.

(In most cases, I actually favour giving useful names to type variables, not just single letters).

Answer 2

The concept is known as a generic method (docs.oracle.com).

In the code presented, we have an especially tricky case of generics since we have two generic parameters with the same name:

• the <T> on the class-level: public class Test<T>, and
• the <T> on the method-level: public <T> T DoSomething(T value)

The latter hides the former within the scope of the method DoSomething(...), just like a local variable would hide an instance field with the same name. In general, I would advice against this type of "hiding" since it makes the code harder to read and understand. Thus, for the rest of the discussion we will work with this (slightly modified) version of the code:

public class Test<T> {
    public T doSomethingWithT(T t) {
        return t;
    }

    public <U> U doSomethingWithU(U u) {
        return u;
    }
}

The scope of the class-level generic parameter T is for the whole class, while the scope of the method-level generic parameter U is only for the one method it is delared on. This will lead to the following observation:

// T is bound to type String for the instance testString:
final Test<String> testString = new Test<>();

final String tString = testString.doSomethingWithT("Hello");
System.out.println(tString); // prints "Hello"
// will not compile since 1 is not a String:
// int tInt = testString.doSomethingWithT(1);

// For this one invocation of doSomethingWithU(...), U is bound to 
// type String:
final String uString = testString.doSomethingWithU("World!");
System.out.println(uString); // prints "World!"

// for this one invocation of doSomethingWithU(...), U is bound to
// type Integer:
final int uInt = testString.doSomethingWithU(1);
System.out.println(uInt); // prints "1"

Ideone demo

Notice that, although doSomethingWithU(...) is a generic method, we did not have to specify the generic parameter, the compiler inferred the type for us. While seldom used, we can also explicitly specify the generic parameter for thie method:

final Test<String> testString = new Test<>();
final Number number = testString.<Number>doSomethingWithU(1);
System.out.println(number);

Ideone demo

(In this example, the explicit generic parameter is not necessary, the code works without it aswell, but there are rare cases where this may be useful or even necessary.)

---

The following is not strictly necessary to understand generic methods, but more of a curiosity one might find in code and is meant to prime the reader that it is bad practice, should not be used and removed when seen.

It should also be mentioned that the JLS allows us to add generic method parameters on method invocations that do not have any generic parameter. Those parameter do not have any effect:

Object o = new Object();

// Method "hashCode()" on "Object" has not generic parameters, one 
// can "add" one to the method invocation, it has no effect on the 
// semantics, however
int hash = o.<String>hashCode();

Ideone demo

---

A remark on the code: In Java, methods should be written in camelCase instead of CamelCase (DoSomething(...) -> doSomething(...))