Casting Maps to Complex Objects

1. Overview

Manipulating and reconstructing data is often a crucial part of programming in Java. One powerful technique involves casting Map objects into complex objects or POJOs. This can allow us to use our existing data with the benefits of type safety.

In this tutorial, we’ll explore three key approaches to converting Map objects into more complex types: Jackson, Gson, and Apache Commons BeanUtils APIs.

2. Domain Classes

To demonstrate the functionalities of different libraries for the conversion, we’ll work with the domain of a User who has multiple Address, each associated with a Country:

class User {
    private Long id;
    private String name;
    private List<Address> addresses;

    // standard getters and setters
}

The Address class represents a User‘s address, along with a city and country:

class Address {
    private String city;
    private Country country;

    // standard getters and setters
}

The Country class represents the nation associated with an Address:

class Country {
    private String name;

    // standard getters and setters
}

We’ll use this Map object to see how different libraries convert the data into a User object:

private static final Map<String, Object> map = Map.of(
  "id", 1L,
  "name", "Baeldung",
  "addresses", List.of(
    new Address("La Havana", new Country("Cuba")),
    new Address("Paris", new Country("France"))
  )
);

To avoid repetition and ensure consistency in verifying the cast User object against the original Map, we’ll use a helper method:

private static void assertEqualsMapAndUser(Map<String, Object> map, User user) {
    assertEquals(map.get("id"), user.getId());
    assertEquals(map.get("name"), user.getName());
    assertEquals(map.get("addresses"), user.getAddresses());
}

With the domain classes and helper method declared, we’re now ready to explore the capabilities of the libraries.

3. Why Direct Casting Doesn’t Work?

Directly casting a Map to an object isn’t possible due to type incompatibility issues. This operation results in a ClassCastException:

@Test
void givenMap_whenCasting_thenThrow() {
    assertThrows(ClassCastException.class, () -> { User user = (User) map; });
}

The previous code fails to cast due to the type mismatch between the Map and the User objects.

4. Using Jackson

Jackson is a flexible library that’s excellent at transforming objects to and from various serialization formats, including Map objects.

To use Jackson, we add the jackson-databind dependency in our pom.xml file:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.0</version>
</dependency>

Jackson’s core functionality is provided by the ObjectMapper class. This is the main tool for converting data between different formats in Jackson.

The convertValue() method transforms the Map into a User object, where each key in the Map becomes a field name in the resulting object, and the corresponding value from the map populates that field:

@Test
void givenMap_whenUsingJackson_thenConvertToObject() {
    ObjectMapper objectMapper = new ObjectMapper();
    User user = objectMapper.convertValue(map, User.class);

    assertEqualsMapAndUser(map, user);
}

If the Map contains keys that don’t correspond to attributes of the target class, Jackson throws an exception by default:

@Test
void givenMap_whenUsingJacksonWithWrongAttrs_thenThrow() {
    Map<String, Object> modifiedMap = new HashMap<>(map);
    modifiedMap.put("enabled", true);

    ObjectMapper objectMapper = new ObjectMapper();

    assertThrows(IllegalArgumentException.class, () -> objectMapper.convertValue(modifiedMap, User.class));
}

Let’s configure Jackson to ignore unknown properties:

@Test
void givenMap_whenUsingJacksonIgnoreUnknownProps_thenConvertToObject() {
    Map<String, Object> modifiedMap = new HashMap<>(map);
    modifiedMap.put("enabled", true);

    ObjectMapper objectMapper = new ObjectMapper();
    objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    User user = objectMapper.convertValue(modifiedMap, User.class);

    assertEqualsMapAndUser(modifiedMap, user);
}

This time, the unknown property was ignored and the rest of the Map transformed to the expected User object.

5. Using Gson

Gson is a user-friendly library that transforms objects to and from the JSON format. Its focus on simplicity makes it a great choice for projects where we primarily deal with JSON data exchange.

To use Gson, we add the gson dependency in our pom.xml file:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.11.0</version>
</dependency>

Let’s explore Gson’s approach. Unlike Jackson’s direct conversion, we need to perform a two-step process here.

First, we serialize the Map into a JSON string using toJson(). Then, we use fromJson() to deserialize the resulting JSON into a User object:

@Test
void givenMap_whenUsingGson_thenConvertToObject() {
    Gson gson = new Gson();
    String jsonMap = gson.toJson(map);
    User user = gson.fromJson(jsonMap, User.class);

    assertEqualsMapAndUser(map, user);
}

Unlike Jackson, which requires configuration to handle unknown properties, Gson seamlessly ignores Map keys that don’t correspond to class attributes during conversion.

6. Using Apache Commons BeanUtils

Apache Commons BeanUtils steps up for a more traditional approach. It’s particularly well-suited for scenarios where we work with codebases that rely heavily on Java Beans.

To use BeanUtils, we add the beanutils dependency in our pom.xml file:

<dependency>
    <groupId>commons-beanutils</groupId>
    <artifactId>commons-beanutils</artifactId>
    <version>1.9.4</version>
</dependency>

This library offers the populate() method, allowing us to populate an object’s fields using a Map directly:

@Test
void givenMap_whenUsingBeanUtils_thenConvertToObject() throws InvocationTargetException, IllegalAccessException {
    User user = new User();
    BeanUtils.populate(user, map);

    assertEqualsMapAndUser(map, user);
}

Unlike Jackson, which requires configuration to handle unknown properties, BeanUtils ignores Map keys that don’t correspond to class attributes during conversion.

7. Comparison

The next table provides a side-by-side comparison of the three approaches. This comparison helps us to choose the most suitable option for converting maps into objects within our application:

8. Conclusion

This article explored three methods for casting maps to objects in Java: Jackson, Gson, and Apache Commons BeanUtils.

Jackson, with its large community, offers a powerful and flexible approach with direct conversion. Gson also has a large community and excels in user-friendly JSON transformations with a two-step process. BeanUtils, suitable for legacy code with Java Beans, uses a direct population method, but has a smaller community.