Mapping to String in Mapstruct

1. Overview

When working with Java applications, we may need to convert complex data objects into simpler representations. For example, it’s common to convert data types such as enums, numbers, or nested objects to their String equivalents for display, logging, or API responses. In such a scenario, we can use MapStruct.

In this tutorial, we’ll map different data types to a String.

2. Project Setup

To demonstrate mapping to a String in MapStruct, we can create a simple Maven project mapstructstringmapping.

In the pom.xml file, let’s navigate to the mapstructstringmapping directory and update:

<dependencies>
    <!-- MapStruct -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.6.3</version>
    </dependency>

    <!-- JUnit 5 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.14.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Above, we add mapstruct for compile-time mapping, and JUnit 5 for testing.

3. Simple Mapping to String

While working on presentation or even API responses, we may need to convert numeric or boolean values into strings. One good example is when a database entity stores a user’s age as an int, but the API layer needing to expose it as a String.

Let’s examine a straightforward example to show how to use MapStruct to map an int field to a String. First, we define the class Person:

public class Person {
    private String name;
    private int age;
}

Next, let’s create the second class PersonDTO:

public class PersonDTO {
    private String name;
    private String age;
}

In the above examples, the classes have standard getters and setters, which MapStruct will use for mapping.

Now, let’s define the mapper interface PersonMapper.java:

@Mapper
public interface PersonMapper {

    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);
    PersonDTO toDTO(Person person);
}

At compile time, MapStruct creates the PersonMapper implementation. In this case, MapStruct automatically changes the int value of age from the source object to a String in the target object when the toDTO() method is called.

Let’s create the PersonMapperUnitTest.java unit test and ensure the mapping functions as intended:

public class PersonMapperUnitTest {

    @Test
    void givenPerson_whenMapsToPersonDTO_thenFieldsAreCorrect() {

        Person person = new Person();
        person.setName("Alice");
        person.setAge(30);

        PersonDTO dto = PersonMapper.INSTANCE.toDTO(person);

        assertEquals("Alice", dto.getName());
        assertEquals("30", dto.getAge());
    }
}

The test confirms that the int value of age is translated to its String representation and that the name field is successfully mapped.

4. Enums to String Conversion

In Java, enums are widely used to define fixed sets of variables, including user roles, order statuses, and system states. However, when data is shown in user interfaces or made accessible through APIs, these enum values are usually rendered as strings.

4.1. Defining the Enum and Domain Classes

Let’s start by defining an enum that represents a user’s status:

public enum Status {
    ACTIVE,
    INACTIVE,
    PENDING
}

To follow this up, let’s create a domain object that uses this enum:

public class User {
    private String username;
    private Status status;
}

Finally, we create a DTO where the enum value is represented as a String:

public class UserDTO {
    private String username;
    private String status;
}

Now, the User class uses an enum for the status field, whereas UserDTO expects the same value as a String.

4.2. Defining the Mapper

Let’s define a mapper interface that converts a User into a UserDTO:

@Mapper
public interface UserMapper {

    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO toDto(User user);
}

Here, MapStruct automatically detects that the source field is an enum and the target field is a String. We don’t need to define any custom mapping logic. It invokes the enum’s name() method during the mapping process.

In most real-world APIs, this default behavior is sufficient, but it’s important to be aware of it if enum names don’t match the values expected by clients.

4.3. Verifying the Mapping

Let’s write a unit test that confirms the enum-to-string conversion works as expected:

public class UserMapperUnitTest {

    @Test
    void shouldMapEnumToString() {

        User user = new User();
        user.setUsername("Kevin");
        user.setStatus(Status.ACTIVE);

        UserDTO dto = UserMapper.INSTANCE.toDto(user);

        assertEquals("Kevin", dto.getUsername());
        assertEquals("ACTIVE", dto.getStatus());
    }
}

This is what the test verifies:

• The username field is mapped correctly
• The enum value Status.ACTIVE is converted to its String representation, “ACTIVE”

Notably, this behavior works out of the box with MapStruct and requires no additional configuration.

5. Mapping Dates to String

When working with date fields, we often need to convert them into formatted string representations before exposing them through APIs or displaying them in user interfaces. MapStruct supports this use case through the dateFormat attribute in the @Mapping annotation.

Using this attribute, we can define the exact date pattern we want MapStruct to apply during the mapping process.

5.1. Defining the Domain and DTO Classes

Let’s start by defining a simple domain entity that contains a LocalDate field:

public class Event {
    private String name;
    private LocalDate eventDate;
}

Next, let’s define a corresponding DTO where the eventDate field is represented as a String:

public class EventDTO {
    private String name;
    private String eventDate;
}

Here, the Event class represents the domain model, while EventDTO is the data transfer object used for output. The key difference is that the eventDate field is a LocalDate in the source object and a formatted String in the target object.

5.2. Creating the Mapper

Now, let’s define a mapper interface to convert an Event into an EventDTO:

@Mapper
public interface EventMapper {

    EventMapper INSTANCE = Mappers.getMapper(EventMapper.class);

    @Mapping(source = "eventDate", target = "eventDate", dateFormat = "yyyy-MM-dd")
    EventDTO toEventDTO(Event event);
}

public class EventMapperUnitTest {

    @Test
    public void shouldMapLocalDateToFormattedString() {

        LocalDate date = LocalDate.of(2025, 11, 10);
        Event event = new Event("Tech Meetup", date);

        EventDTO dto = EventMapper.INSTANCE.toEventDTO(event);

        assertNotNull(dto);
        assertEquals("Tech Meetup", dto.getName());
        assertEquals("2025-11-10", dto.getEventDate());
    }
}

@Mapper(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
public interface PersonMapper {

    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);

    @Mapping(target = "age", defaultValue = "")
    PersonDTO toDTO(Person person);
}

@Mapper(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
public interface PersonMapper {

    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);

    @Mapping(target = "name", qualifiedByName = "mapName")
    @Mapping(target = "age", defaultValue = "")
    PersonDTO toDTO(Person person);

    @Named("mapName")
    default String mapName(String name) {
        return name == null ? "Unknown" : name;
    }
}