google-site-verification: google61fe8ba583a51912.html
MACRO NEPAL
MapStruct for Object Mapping in Java: A Complete Guide
awiskar acharya
November 6, 2025
3:01 pm

MapStruct is a code generator that simplifies object mapping in Java by automatically generating mapping code at compile time. It eliminates boilerplate code and provides type-safe, fast, and maintainable object transformation.

Why MapStruct?

Advantages over Manual Mapping:

  • Compile-time Safety: Errors caught during compilation
  • Performance: No reflection, generated code is as fast as hand-written
  • Type Safety: Compile-time verification of mapping correctness
  • Maintainability: Easy to refactor and update
  • Less Boilerplate: No manual getter/setter code
  • IDE Support: Full IDE integration with code completion

Setup and Dependencies

Maven Dependencies

<properties> <org.mapstruct.version>1.5.5.Final</org.mapstruct.version> </properties> <dependencies> <!-- MapStruct Core --> <dependency> <groupId>org.mapstruct</groupId> <artifactId>mapstruct</artifactId> <version>${org.mapstruct.version}</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <annotationProcessorPaths> <path> <groupId>org.mapstruct</groupId> <artifactId>mapstruct-processor</artifactId> <version>${org.mapstruct.version}</version> </path> </annotationProcessorPaths> </configuration> </plugin> </plugins> </build>

Gradle Setup

plugins { id 'java' } dependencies { implementation 'org.mapstruct:mapstruct:1.5.5.Final' annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final' }

Basic Mapping Examples

Example 1: Simple Object Mapping

Source and Target Classes:

// Source class public class User { private Long id; private String username; private String email; private String firstName; private String lastName; private LocalDateTime createdAt; // Constructors public User() {} public User(Long id, String username, String email, String firstName, String lastName, LocalDateTime createdAt) { this.id = id; this.username = username; this.email = email; this.firstName = firstName; this.lastName = lastName; this.createdAt = createdAt; } // Getters and Setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } public LocalDateTime getCreatedAt() { return createdAt; } public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; } } // Target class public class UserDTO { private Long id; private String username; private String email; private String fullName; private String createdAt; // Constructors, getters, and setters public UserDTO() {} public UserDTO(Long id, String username, String email, String fullName, String createdAt) { this.id = id; this.username = username; this.email = email; this.fullName = fullName; this.createdAt = createdAt; } // Getters and Setters public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } public String getFullName() { return fullName; } public void setFullName(String fullName) { this.fullName = fullName; } public String getCreatedAt() { return createdAt; } public void setCreatedAt(String createdAt) { this.createdAt = createdAt; } }

Mapper Interface:

import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.mapstruct.factory.Mappers; @Mapper public interface UserMapper { UserMapper INSTANCE = Mappers.getMapper(UserMapper.class); @Mapping(target = "fullName", expression = "java(user.getFirstName() + ' ' + user.getLastName())") @Mapping(target = "createdAt", source = "createdAt", dateFormat = "yyyy-MM-dd HH:mm:ss") UserDTO userToUserDTO(User user); @Mapping(target = "firstName", expression = "java(extractFirstName(userDTO.getFullName()))") @Mapping(target = "lastName", expression = "java(extractLastName(userDTO.getFullName()))") @Mapping(target = "createdAt", ignore = true) // We'll handle this separately User userDTOToUser(UserDTO userDTO); // Default methods for custom logic default String extractFirstName(String fullName) { if (fullName == null || fullName.trim().isEmpty()) { return null; } String[] names = fullName.split(" "); return names.length > 0 ? names[0] : null; } default String extractLastName(String fullName) { if (fullName == null || fullName.trim().isEmpty()) { return null; } String[] names = fullName.split(" "); return names.length > 1 ? names[1] : null; } }

Usage Example:

public class BasicMappingDemo { public static void main(String[] args) { // Create source object User user = new User( 1L, "johndoe", "[email protected]", "John", "Doe", LocalDateTime.now() ); // Map to DTO UserDTO userDTO = UserMapper.INSTANCE.userToUserDTO(user); System.out.println("Original User: " + user.getFirstName() + " " + user.getLastName()); System.out.println("Mapped UserDTO: " + userDTO.getFullName()); System.out.println("Email: " + userDTO.getEmail()); System.out.println("Created At: " + userDTO.getCreatedAt()); // Map back to User User mappedUser = UserMapper.INSTANCE.userDTOToUser(userDTO); System.out.println("Mapped back - First Name: " + mappedUser.getFirstName()); System.out.println("Mapped back - Last Name: " + mappedUser.getLastName()); } }

Advanced Mapping Features

Example 2: Complex Object Mapping with Nested Objects

Nested Object Classes:

// Address classes public class Address { private String street; private String city; private String state; private String zipCode; private String country; // Constructors, getters, and setters public Address() {} public Address(String street, String city, String state, String zipCode, String country) { this.street = street; this.city = city; this.state = state; this.zipCode = zipCode; this.country = country; } // Getters and setters... } public class AddressDTO { private String fullAddress; private String location; // Constructors, getters, and setters public AddressDTO() {} public AddressDTO(String fullAddress, String location) { this.fullAddress = fullAddress; this.location = location; } // Getters and setters... } // User with Address public class UserWithAddress { private Long id; private String username; private String email; private Address address; // Constructors, getters, and setters public UserWithAddress() {} public UserWithAddress(Long id, String username, String email, Address address) { this.id = id; this.username = username; this.email = email; this.address = address; } // Getters and setters... } public class UserWithAddressDTO { private Long id; private String username; private String email; private AddressDTO address; // Constructors, getters, and setters... }

Complex Mapper:

import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.mapstruct.Named; @Mapper public interface ComplexUserMapper { ComplexUserMapper INSTANCE = Mappers.getMapper(ComplexUserMapper.class); @Mapping(target = "address", source = "address", qualifiedByName = "addressToAddressDTO") UserWithAddressDTO userWithAddressToDTO(UserWithAddress user); @Mapping(target = "address", source = "address", qualifiedByName = "addressDTOToAddress") UserWithAddress dtoToUserWithAddress(UserWithAddressDTO dto); @Named("addressToAddressDTO") default AddressDTO addressToAddressDTO(Address address) { if (address == null) { return null; } String fullAddress = String.format("%s, %s, %s %s", address.getStreet(), address.getCity(), address.getState(), address.getZipCode()); String location = String.format("%s, %s", address.getCity(), address.getCountry()); return new AddressDTO(fullAddress, location); } @Named("addressDTOToAddress") default Address addressDTOToAddress(AddressDTO addressDTO) { if (addressDTO == null || addressDTO.getFullAddress() == null) { return null; } // Simple parsing logic - in real scenario, use proper parsing String[] parts = addressDTO.getFullAddress().split(", "); return new Address( parts.length > 0 ? parts[0] : null, // street parts.length > 1 ? parts[1] : null, // city parts.length > 2 ? parts[2] : null, // state parts.length > 3 ? parts[3] : null, // zipCode addressDTO.getLocation() != null ? addressDTO.getLocation().split(", ")[1] : null // country ); } }

Example 3: Collection Mapping

Collection Mapper:

import org.mapstruct.Mapper; import org.mapstruct.factory.Mappers; import java.util.List; import java.util.Set; @Mapper public interface CollectionMapper { CollectionMapper INSTANCE = Mappers.getMapper(CollectionMapper.class); // List to List List<UserDTO> usersToUserDTOs(List<User> users); // Set to Set Set<UserDTO> usersToUserDTOs(Set<User> users); // List to Set Set<UserDTO> usersToUserDTOsSet(List<User> users); }

Usage:

public class CollectionMappingDemo { public static void main(String[] args) { List<User> users = List.of( new User(1L, "user1", "[email protected]", "John", "Doe", LocalDateTime.now()), new User(2L, "user2", "[email protected]", "Jane", "Smith", LocalDateTime.now()), new User(3L, "user3", "[email protected]", "Bob", "Johnson", LocalDateTime.now()) ); List<UserDTO> userDTOs = CollectionMapper.INSTANCE.usersToUserDTOs(users); System.out.println("Mapped " + userDTOs.size() + " users to DTOs"); userDTOs.forEach(dto -> System.out.println(" - " + dto.getFullName() + " (" + dto.getEmail() + ")") ); } }

Spring Integration

Example 4: MapStruct with Spring Boot

Spring-based Mapper:

import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.springframework.stereotype.Component; @Mapper(componentModel = "spring") public interface SpringUserMapper { @Mapping(target = "fullName", expression = "java(user.getFirstName() + ' ' + user.getLastName())") @Mapping(target = "createdAt", source = "createdAt", dateFormat = "yyyy-MM-dd HH:mm:ss") UserDTO userToUserDTO(User user); User userDTOToUser(UserDTO userDTO); List<UserDTO> usersToUserDTOs(List<User> users); }

Service Class:

import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.List; @Service public class UserService { private final SpringUserMapper userMapper; @Autowired public UserService(SpringUserMapper userMapper) { this.userMapper = userMapper; } public UserDTO getUserDTO(Long userId) { User user = userRepository.findById(userId) .orElseThrow(() -> new UserNotFoundException(userId)); return userMapper.userToUserDTO(user); } public List<UserDTO> getAllActiveUsers() { List<User> activeUsers = userRepository.findByActiveTrue(); return userMapper.usersToUserDTOs(activeUsers); } public User createUser(UserDTO userDTO) { User user = userMapper.userDTOToUser(userDTO); user.setCreatedAt(LocalDateTime.now()); user.setActive(true); return userRepository.save(user); } }

Advanced Configuration

Example 5: Custom Mapper with Configuration

Mapper Configuration:

import org.mapstruct.MapperConfig; import org.mapstruct.Mapping; import org.mapstruct.ReportingPolicy; @MapperConfig( componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE, unmappedSourcePolicy = ReportingPolicy.WARN ) public interface CentralConfig { @Mapping(target = "id", ignore = true) @Mapping(target = "createdAt", ignore = true) User toEntity(UserDTO dto); }

Inheriting Mapper:

@Mapper(config = CentralConfig.class) public interface ConfiguredUserMapper extends CentralConfig { // Inherits configuration from CentralConfig @Mapping(target = "fullName", expression = "java(user.getFirstName() + ' ' + user.getLastName())") UserDTO toDTO(User user); // Uses configuration from CentralConfig for toEntity User toEntity(UserDTO dto); }

Example 6: Conditional Mapping

Conditional Mapper:

import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.mapstruct.Condition; @Mapper public interface ConditionalMapper { @Mapping(target = "email", source = "email", condition = "isValidEmail") UserDTO userToUserDTO(User user); @Condition default boolean isValidEmail(String email) { return email != null && email.contains("@") && email.contains("."); } @Mapping(target = "username", source = "username", defaultExpression = "java(generateUsername())") User userDTOToUser(UserDTO dto); default String generateUsername() { return "user_" + System.currentTimeMillis(); } }

Real-World Use Case

Example 7: E-commerce Domain Mapping

Domain Classes:

// Domain classes public class Order { private Long id; private String orderNumber; private Customer customer; private List<OrderItem> items; private BigDecimal totalAmount; private OrderStatus status; private LocalDateTime orderDate; // Constructors, getters, setters } public class OrderItem { private Long id; private Product product; private Integer quantity; private BigDecimal unitPrice; private BigDecimal totalPrice; // Constructors, getters, setters } public class Customer { private Long id; private String name; private String email; private Address address; // Constructors, getters, setters } public class Product { private Long id; private String name; private String description; private BigDecimal price; private String category; // Constructors, getters, setters } // DTO classes public class OrderDTO { private String orderNumber; private String customerName; private String customerEmail; private String shippingAddress; private List<OrderItemDTO> items; private String formattedTotal; private String status; private String orderDate; // Constructors, getters, setters } public class OrderItemDTO { private String productName; private Integer quantity; private String formattedUnitPrice; private String formattedTotalPrice; // Constructors, getters, setters }

E-commerce Mapper:

import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.mapstruct.Named; import java.math.BigDecimal; import java.text.NumberFormat; import java.util.Locale; @Mapper public interface OrderMapper { OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class); @Mapping(target = "customerName", source = "customer.name") @Mapping(target = "customerEmail", source = "customer.email") @Mapping(target = "shippingAddress", source = "customer.address", qualifiedByName = "formatAddress") @Mapping(target = "formattedTotal", source = "totalAmount", qualifiedByName = "formatCurrency") @Mapping(target = "status", source = "status", qualifiedByName = "formatStatus") @Mapping(target = "orderDate", source = "orderDate", dateFormat = "MMMM dd, yyyy 'at' HH:mm") @Mapping(target = "items", source = "items") OrderDTO orderToOrderDTO(Order order); @Mapping(target = "productName", source = "product.name") @Mapping(target = "formattedUnitPrice", source = "unitPrice", qualifiedByName = "formatCurrency") @Mapping(target = "formattedTotalPrice", source = "totalPrice", qualifiedByName = "formatCurrency") OrderItemDTO orderItemToOrderItemDTO(OrderItem orderItem); @Named("formatAddress") default String formatAddress(Address address) { if (address == null) { return "No address provided"; } return String.format("%s, %s, %s %s, %s", address.getStreet(), address.getCity(), address.getState(), address.getZipCode(), address.getCountry()); } @Named("formatCurrency") default String formatCurrency(BigDecimal amount) { if (amount == null) { return "$0.00"; } return NumberFormat.getCurrencyInstance(Locale.US).format(amount); } @Named("formatStatus") default String formatStatus(OrderStatus status) { if (status == null) { return "UNKNOWN"; } return status.name().charAt(0) + status.name().substring(1).toLowerCase(); } }

Testing MapStruct Mappers

Example 8: Unit Testing

import org.junit.jupiter.api.Test; import org.mapstruct.factory.Mappers; import java.time.LocalDateTime; import java.util.List; import static org.junit.jupiter.api.Assertions.*; class UserMapperTest { private final UserMapper userMapper = Mappers.getMapper(UserMapper.class); @Test void testUserToUserDTO() { // Given User user = new User(1L, "johndoe", "[email protected]", "John", "Doe", LocalDateTime.now()); // When UserDTO userDTO = userMapper.userToUserDTO(user); // Then assertNotNull(userDTO); assertEquals(user.getId(), userDTO.getId()); assertEquals(user.getUsername(), userDTO.getUsername()); assertEquals(user.getEmail(), userDTO.getEmail()); assertEquals("John Doe", userDTO.getFullName()); assertNotNull(userDTO.getCreatedAt()); } @Test void testUserDTOToUser() { // Given UserDTO userDTO = new UserDTO(1L, "johndoe", "[email protected]", "John Doe", "2024-01-15 10:30:00"); // When User user = userMapper.userDTOToUser(userDTO); // Then assertNotNull(user); assertEquals(userDTO.getId(), user.getId()); assertEquals(userDTO.getUsername(), user.getUsername()); assertEquals(userDTO.getEmail(), user.getEmail()); assertEquals("John", user.getFirstName()); assertEquals("Doe", user.getLastName()); } @Test void testUsersToUserDTOs() { // Given List<User> users = List.of( new User(1L, "user1", "[email protected]", "John", "Doe", LocalDateTime.now()), new User(2L, "user2", "[email protected]", "Jane", "Smith", LocalDateTime.now()) ); // When List<UserDTO> userDTOs = userMapper.usersToUserDTOs(users); // Then assertNotNull(userDTOs); assertEquals(2, userDTOs.size()); assertEquals("John Doe", userDTOs.get(0).getFullName()); assertEquals("Jane Smith", userDTOs.get(1).getFullName()); } }

Best Practices

  1. Use Component Model: Prefer componentModel = "spring" for Spring applications
  2. Central Configuration: Use @MapperConfig for shared settings
  3. Custom Methods: Use @Named for complex transformations
  4. Testing: Always test your mappers
  5. Error Handling: Handle null values gracefully
  6. Performance: MapStruct generates efficient code, but avoid complex expressions in mappings
  7. Documentation: Use @Mapping annotations to document mapping rules

Conclusion

MapStruct provides a powerful, type-safe, and efficient solution for object mapping in Java:

Key Benefits:

  • Zero Runtime Overhead: Compile-time code generation
  • Type Safety: Compile-time error detection
  • Performance: As fast as hand-written code
  • Maintainability: Easy to refactor and understand
  • Flexibility: Custom methods and complex mappings
  • Spring Integration: Seamless Spring Boot integration

When to Use MapStruct:

  • Complex object transformations
  • Microservices with multiple DTOs
  • API development with request/response mapping
  • Data migration and transformation
  • Any project requiring object-to-object mapping

MapStruct eliminates the boilerplate of manual mapping while providing the performance and type safety that makes it the preferred choice for object mapping in modern Java applications.

Next Steps: Explore MapStruct's advanced features like decorators, inheritance, and custom mappers for complex mapping scenarios. Integrate with your build process and consider using it alongside other mapping libraries for specific use cases.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper