How to Use ParameterizedTypeReference in Java

1. Introduction

When working with generic types in Java, we’ll often face type erasure. This becomes particularly challenging when we’re making HTTP requests that return generic collections or complex parameterized types. Spring’s ParameterizedTypeReference gives us an elegant solution to this problem.

In this tutorial, we’ll explore how to use ParameterizedTypeReference with both RestTemplate and WebClient. We’ll also cover the underlying concepts and best practices for handling complex generic types in modern Java applications.

2. Understanding Type Erasure and the Problem It Creates

Java’s type erasure removes generic type information at runtime. For example, List<String> and List<Integer> both become List at runtime. This creates challenges when we need to preserve generic type information.

Let’s create a User class that will help us in our code demonstrations:

public class User {
    private Long id;
    private String name;
    private String email;
    private String department;

    //constructors, getters and setters
}

Now, let’s consider a common scenario where we’re retrieving a list of users from a REST API:

RestTemplate restTemplate = new RestTemplate();
List<User> users = restTemplate.getForObject("/users", List.class);

However, it results in a List<Object> rather than the List<User> we want. Furthermore, each element in the list needs to be manually cast. This approach can lead to errors and defeats the purpose of using generics.

Undoubtedly, this is where we see the value of ParameterizedTypeReference. It captures and preserves the complete generic type information at compile time so that it’s available at runtime.

3. Basic Usage with RestTemplate

RestTemplate remains widely used in Spring applications. Understanding how to handle generic types with it is important. Next, we’ll look at several practical scenarios to understand ParameterizedTypeReference better.

3.1. Working with Generic Collections

Let’s look at an example using RestTemplate to fetch a list of users:

@Service
public class ApiService {

    //properties and constructor

    public List<User> fetchUserList() {
        ParameterizedTypeReference<List<User>> typeRef =
          new ParameterizedTypeReference<List<User>>() {};

        ResponseEntity<List<User>> response = restTemplate.exchange(
          baseUrl + "/api/users",
          HttpMethod.GET,
          null,
          typeRef
        );

        return response.getBody();
   }
}

In the example above, the key elements are the creation of a ParameterizedTypeReference with the exact generic type we expect. The empty braces create an anonymous class, which we use as an argument in the exchange() method. The ParameterizedTypeReference allows exchange() to directly return a List<User> without requiring any casting.

Let’s verify this logic:

@Test
void whenFetchingUserList_thenReturnsCorrectType() {
    // given
    wireMockServer.stubFor(get(urlEqualTo("/api/users"))
        .willReturn(aResponse()
            .withStatus(200)
            .withHeader("Content-Type", "application/json")
            .withBody("""
                [
                    {
                        "id": 1,
                        "name": "John Doe",
                        "email": "[email protected]",
                        "department": "Engineering"
                    },
                    {
                        "id": 2,
                        "name": "Jane Smith",
                        "email": "[email protected]",
                        "department": "Marketing"
                    }
                ]
                """)));

    // when
    List<User> result = apiService.fetchUserList();

    // then
    assertEquals(2, result.size());
    assertEquals("John Doe", result.get(0).getName());
    assertEquals("[email protected]", result.get(1).getEmail());
    assertEquals("Engineering", result.get(0).getDepartment());
    assertEquals("Marketing", result.get(1).getDepartment());
}

The test confirms that our ParameterizedTypeReference correctly keeps the generic type information, allowing us to work with a properly typed List<User> instead of a raw List. 

We’re using WireMock for our tests to simulate a live API endpoint. This allows our RestTemplate to make actual HTTP calls and receive valid JSON responses, which are then deserialized according to our ParameterizedTypeReference.

WireMock provides a solid option to test HTTP client behavior without depending on external services, ensuring our tests are both reliable and fast.

3.2. Comparing getForEntity() with exchange()

In general, understanding the difference between getForEntity() and exchange() is crucial when working with generic types. Additionally, many developers initially try to use the simpler getForEntity() method, only to encounter type safety issues.

The key issue is getForEntity() doesn’t accept a ParameterizedTypeReference — it only accepts a class type for the response object.

Let’s look at an example of inappropriate usage of getForEntity():

public List<User> fetchUsersWrongApproach() {
    ResponseEntity response = restTemplate.getForEntity(
      baseUrl + "/api/users",
      List.class
    );

    return (List) response.getBody();
}

The problem we’ll encounter using the above solution is that we’ll have an unchecked cast. Even if the code compiles, it loses the type information.

Now, let’s look at the recommended solution, using exchange():

public List<User> fetchUsersCorrectApproach() {
    ParameterizedTypeReference<List<User>> typeRef =
      new ParameterizedTypeReference<List<User>>() {};

    ResponseEntity<List<User>> response = restTemplate.exchange(
      baseUrl + "/api/users",
      HttpMethod.GET,
      null,
      typeRef
    );

    return response.getBody();
}

Some key differences are that getForEntity() accepts a Class<T> parameter, which can’t represent generic types. On the other hand, exchange() accepts ParameterizedTypeReference<T>, preserving full type information.

Consequently, the compiler can verify type safety with exchange(), preventing a ClassCastException at runtime.

4. Working with WebClient

WebClient provides a modern, reactive approach to HTTP communication. Unlike RestTemplate, it returns reactive types like Mono and Flux. These require special handling when working with generic types.

4.1. Reactive Operations with Complex Types

Let’s look at how ParameterizedTypeReference handles nested generic types in reactive programming:

@Service
public class ReactiveApiService {

    private final WebClient webClient;

    public ReactiveApiService(String baseUrl) {
        this.webClient = WebClient.builder().baseUrl(baseUrl).build();
    }

    public Mono<Map<String, List<User>>> fetchUsersByDepartment() {
        ParameterizedTypeReference<Map<String, List<User>>> typeRef = 
          new ParameterizedTypeReference<Map<String, List<User>>>() {};

        return webClient.get()
            .uri("/users/by-department")
            .retrieve()
            .bodyToMono(typeRef);
    }
}

The method returns a Mono containing a map where each key is a department name and each value is a list of users in that department. This showcases WebClient’s ability to deserialize complex generic structures while maintaining type safety.

Now, let’s test our implementation:

@Test
void whenFetchingUsersByDepartment_thenReturnsCorrectMap() {
    // given
    wireMockServer.stubFor(get(urlEqualTo("/users/by-department"))
        .willReturn(aResponse()
            .withStatus(200)
            .withHeader("Content-Type", "application/json")
            .withBody("""
                {
                    "Engineering": [
                        {
                            "id": 1,
                            "name": "John Doe",
                            "email": "[email protected]",
                            "department": "Engineering"
                        }
                    ],
                    "Marketing": [
                        {
                            "id": 2,
                            "name": "Jane Smith",
                            "email": "[email protected]",
                            "department": "Marketing"
                        }
                    ]
                }
                """)));

    // when
    Mono<Map<String, List<User>>> result = reactiveApiService.fetchUsersByDepartment();

    // then
    StepVerifier.create(result)
        .assertNext(map -> {
            assertTrue(map.containsKey("Engineering"));
            assertTrue(map.containsKey("Marketing"));
            assertEquals("John Doe", map.get("Engineering").get(0).getName());
            assertEquals("Jane Smith", map.get("Marketing").get(0).getName());

            // Verify proper typing - this would fail if ParameterizedTypeReference didn't work
            List engineeringUsers = map.get("Engineering");
            User firstUser = engineeringUsers.get(0);
            assertEquals(Long.valueOf(1L), firstUser.getId());
        })
        .verifyComplete();
}

Notice that we’re able to correctly deserialize the JSON response into the expected Map<String, List<User>>.

4.2. Custom Generic Wrappers

Real-world APIs often use generic wrapper classes. Here’s how we can handle them. First, let’s create our wrapper object:

public record ApiResponse<T>(boolean success, String message, T data) {}

Now, let’s use this wrapper with ParameterizedTypeReference:

public Mono<ApiResponse<List<User>>> fetchUsersWithWrapper() {
    ParameterizedTypeReference<ApiResponse<List<User>>> typeRef = 
      new ParameterizedTypeReference<ApiResponse<List<User>>>() {};

    return webClient.get()
        .uri("/users/wrapped")
        .retrieve()
        .bodyToMono(typeRef);
}

Finally, let’s test our implementation to make sure it correctly handles the generic wrapper:

@Test
void whenFetchingUsersWithWrapper_thenReturnsApiResponse() {
    // given
    wireMockServer.stubFor(get(urlEqualTo("/users/wrapped"))
        .willReturn(aResponse()
            .withStatus(200)
            .withHeader("Content-Type", "application/json")
            .withBody("""
                {
                    "success": true,
                    "message": "Success",
                    "data": [
                        {
                            "id": 1,
                            "name": "John Doe",
                            "email": "[email protected]",
                            "department": "Engineering"
                        },
                        {
                            "id": 2,
                            "name": "Jane Smith",
                            "email": "[email protected]",
                            "department": "Marketing"
                        }
                    ]
                }
                """)));

    // when
    Mono<ApiResponse<List<User>>> result = reactiveApiService.fetchUsersWithWrapper();

    // then
    StepVerifier.create(result)
        .assertNext(response -> {
            assertTrue(response.success());
            assertEquals("Success", response.message());
            assertEquals(2, response.data().size());
            assertEquals("John Doe", response.data().get(0).getName());
            assertEquals("Jane Smith", response.data().get(1).getName());

            // Verify proper generic typing - this ensures ParameterizedTypeReference worked
            List users = response.data();
            User firstUser = users.get(0);
            assertEquals(Long.valueOf(1L), firstUser.getId());
            assertEquals("Engineering", firstUser.getDepartment());
        })
        .verifyComplete();
}

5. Best Practices

When working with ParameterizedTypeReference in production applications, following certain best practices improves performance and maintainability.

Let’s explore some of these best practices. The strategies we’re covering focus on optimizing our code and handling errors gracefully.

5.1. When to Use ParameterizedTypeReference

Understanding when to use ParameterizedTypeReference is important for writing clean code. It is not required in every HTTP call. Furthermore, using it unnecessarily adds complexity.

We should use ParameterizedTypeReference when:

• working with generic collections (List<T>, Set<T>, Map<K, V>)
• handling custom generic wrapper classes (ApiResponse<T>)
• dealing with nested generic types (Map<String, List<User>>)

We should avoid ParameterizedTypeReference when:

• working with simple, non-generic types
• the response is a single object without generics
• using primitive types or their wrappers

Let’s look at some examples where we should avoid it:

public User fetchUser(Long id) {
    return restTemplate.getForObject(baseUrl + "/api/users/" + id, User.class);
}

public User[] fetchUsersArray() {
    return restTemplate.getForObject(baseUrl + "/api/users", User[].class);
}

Straightaway, we can see why ParameterizedTypeReference is not needed in the fetchUser() method. Analogous to the explanations above, the method returns a simple object, User. In addition, this also applies to array types. As such, we don’t need to use ParameterizedTypeReference for the fetchUsersArray() method, either.

On the other hand, let’s look at an example where it is needed:

public List<User> fetchUsersList() {
    ParameterizedTypeReference<List<User>> typeRef = 
      new ParameterizedTypeReference<List<User>>() {};
    
    ResponseEntity<List<User>> response = restTemplate.exchange(
      baseUrl + "/api/users",
      HttpMethod.GET,
      null,
      typeRef
    );
    
    return response.getBody();
}

In the example above, we need ParameterizedTypeReference because we’re handling a generic collection, specifically a List<User>.

Our main takeaway here sums it up nicely: The key distinction is whether type erasure affects our use case. If Java‘s runtime can determine the type without generic information, ParameterizedTypeReference is unnecessary.

5.2. Reusing Type References

Creating ParameterizedTypeReference instances has a performance cost. Therefore, for frequently used types, we should create static instances:

public class TypeReferences {
    public static final ParameterizedTypeReference<List<User>> USER_LIST = 
      new ParameterizedTypeReference<List<User>>() {};

    public static final ParameterizedTypeReference<Map<String, List<User>>> USER_MAP = 
      new ParameterizedTypeReference<Map<String, List<User>>>() {};
}

Here’s an example of how we would use one of the static instances:

public List<User> fetchUsersListWithExistingReference() {
    ResponseEntity<List<User>> response =
      restTemplate.exchange(baseUrl + "/api/users", HttpMethod.GET, null, USER_LIST);

    return response.getBody();
}

6. Conclusion

In this article, we’ve explored how to use ParameterizedTypeReference to handle complex generic types in Java applications. Furthermore, we’ve seen how this solves the type erasure problem and enables us to work with generic collections seamlessly.

ParameterizedTypeReference is essential when working with generic types in Spring HTTP clients. It works with both RestTemplate and WebClient, and reusing type references improves performance.

Consequently, by following these patterns, we can write more robust and maintainable code when working with generic types in our Java applications.