mapstruct · DanielLiu1123 · Nov 5, 2025 · Nov 10, 2025 · Nov 10, 2025 · Nov 10, 2025
diff --git a/documentation/src/main/asciidoc/chapter-5-data-type-conversions.asciidoc b/documentation/src/main/asciidoc/chapter-5-data-type-conversions.asciidoc
@@ -133,6 +133,28 @@ public interface CarMapper {
 * Between `java.util.Locale` and `String`.
 ** When converting from a `Locale`, the resulting `String` will be a well-formed IETF BCP 47 language tag representing the locale. When converting from a `String`, the locale that best represents the language tag will be returned. See https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#forLanguageTag-java.lang.String-[Locale.forLanguageTag()] and https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toLanguageTag--[Locale.toLanguageTag()] for more information.
 
+* Between Protocol Buffers (Protobuf) types and corresponding Java types:
+** Between `com.google.protobuf.ByteString` and `String`
+** Between Protobuf wrapper types and their corresponding Java primitive types:
+*** `com.google.protobuf.DoubleValue` and `Double` / `double`
+*** `com.google.protobuf.FloatValue` and `Float` / `float`
+*** `com.google.protobuf.Int32Value` and `Integer` / `int`
+*** `com.google.protobuf.UInt32Value` and `Integer` / `int`
+*** `com.google.protobuf.Int64Value` and `Long` / `long`
+*** `com.google.protobuf.UInt64Value` and `Long` / `long`
+*** `com.google.protobuf.BoolValue` and `Boolean` / `boolean`
+*** `com.google.protobuf.StringValue` and `String`
+*** `com.google.protobuf.BytesValue` and `com.google.protobuf.ByteString`
+** Between `com.google.protobuf.ProtocolMessageEnum` and `Integer` / `int` (using the enum's numeric value, not ordinal)
+** Between Protobuf well-known types and Java 8 Date-Time types:
+*** `com.google.protobuf.Timestamp` and `java.time.Instant`
+*** `com.google.protobuf.Duration` and `java.time.Duration`
+** Between Protobuf `google.type` package types and Java 8 Date-Time types:
+*** `com.google.type.Date` and `java.time.LocalDate`
+*** `com.google.type.TimeOfDay` and `java.time.LocalTime`
+*** `com.google.type.DayOfWeek` and `java.time.DayOfWeek`
+*** `com.google.type.Month` and `java.time.Month`
+
 [[mapping-object-references]]
 === Mapping object references
 

diff --git a/integrationtest/src/test/java/org/mapstruct/itest/tests/MavenIntegrationTest.java b/integrationtest/src/test/java/org/mapstruct/itest/tests/MavenIntegrationTest.java
@@ -111,10 +111,10 @@ void namingStrategyTest() {
     /**
      * ECLIPSE_JDT is not working with Protobuf. Use all other available processor types.
      */
-    @ProcessorTest(baseDir = "protobufBuilderTest", processorTypes = {
+    @ProcessorTest(baseDir = "protobufTest", processorTypes = {
         ProcessorTest.ProcessorType.JAVAC
     })
-    void protobufBuilderTest() {
+    void protobufTest() {
     }
 
     @ProcessorTest(baseDir = "sealedSubclassTest")

diff --git a/...es/protobufBuilderTest/src/test/java/org/mapstruct/itest/protobuf/ProtobufMapperTest.java b/...es/protobufBuilderTest/src/test/java/org/mapstruct/itest/protobuf/ProtobufMapperTest.java
diff --git a/...est/resources/protobufBuilderTest/pom.xml → ...t/src/test/resources/protobufTest/pom.xml b/...est/resources/protobufBuilderTest/pom.xml → ...t/src/test/resources/protobufTest/pom.xml
@@ -24,13 +24,23 @@
     <properties>
         <os.mavenplugin.version>1.6.0</os.mavenplugin.version>
         <protobuf.mavenplugin.version>0.6.1</protobuf.mavenplugin.version>
+        <!-- Override parent AssertJ version to support usingRecursiveComparison() -->
+        <assertj.version>3.24.2</assertj.version>
     </properties>
 
     <dependencies>
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <scope>compile</scope>
+        </dependency>
         <dependency>
             <groupId>com.google.protobuf</groupId>
             <artifactId>protobuf-java</artifactId>
-            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.api.grpc</groupId>
+            <artifactId>proto-google-common-protos</artifactId>
         </dependency>
     </dependencies>
 
@@ -55,11 +65,8 @@
                             <goal>compile-custom</goal>
                         </goals>
                         <configuration>
-                            <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
-                            </protocArtifact>
+                            <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
                             <pluginId>grpc-java</pluginId>
-                            <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.47.0:exe:${os.detected.classifier}
-                            </pluginArtifact>
                         </configuration>
                     </execution>
                 </executions>

@@ -0,0 +1,116 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.protobuf;
+
+import java.time.DayOfWeek;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.LocalTime;
+import java.time.Month;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import com.google.protobuf.BoolValue;
+import com.google.protobuf.ByteString;
+import com.google.protobuf.BytesValue;
+import com.google.protobuf.DoubleValue;
+import com.google.protobuf.FloatValue;
+import com.google.protobuf.Int32Value;
+import com.google.protobuf.StringValue;
+import lombok.Data;
+
+@Data
+public class Everything {
+    // Primitive types
+    private Integer int32;
+    private long int64;
+    private Float float_;
+    private Double double_;
+    private Boolean bool;
+    private String string;
+    private ByteString bytes;
+
+    // Wrapper types
+    private Integer int32Value;
+    private long int64Value;
+    private FloatValue floatValue;
+    private double doubleValue;
+    private boolean boolValue;
+    private StringValue stringValue;
+    private ByteString bytesValue;
+
+    // repeated
+    private Integer[] repeatedInt32;
+    private Set<Long> repeatedInt64;
+    private List<Float> repeatedFloat;
+    private List<DoubleValue> repeatedDouble;
+    private List<BoolValue> repeatedBool;
+    private List<String> repeatedString;
+    private List<BytesValue> repeatedBytes;
+
+    // map
+    private Map<Integer, ByteString> mapInt32String;
+    private Map<Long, String> mapInt64String;
+    private Map<BoolValue, String> mapBoolString;
+    private Map<String, String> mapStringString;
+    private Map<String, BytesValue> mapStringBytes;
+
+    // message
+    private Message message;
+    private List<Message> repeatedMessage;
+    private Map<StringValue, Message> mapStringMessage;
+
+    // enum
+    private Integer enum_;
+    private int optionalEnum;
+    private List<String> repeatedEnum;
+    private Map<String, Integer> mapStringEnum;
+
+    // wellknown
+    private Instant timestamp;
+    private Duration duration;
+
+    // google/type package
+    private LocalTime timeOfDay;
+    private String date;
+    private DayOfWeek dayOfWeek;
+    private Month month;
+
+    // oneof
+    private Int32Value oneofInt32;
+    private StringValue oneofString;
+    private Integer oneofEnum;
+    private Message oneofMessage;
+
+    //  deprecated field
+    @Deprecated
+    private Integer deprecatedInt32;
+    @Deprecated
+    private String deprecatedString;
+    @Deprecated
+    private List<String> deprecatedRepeatedString;
+    @Deprecated
+    private Map<String, Integer> deprecatedMapStringInt32;
+    @Deprecated
+    private Integer deprecatedEnum;
+
+    //  special naming
+    private String strBytes;
+    private Integer enValue;
+    private List<String> reStringList;
+    private List<Integer> reEnumValueList;
+    private Map<String, String> maStringStringMap;
+    private Map<String, String> maStringEnumMap;
+    private Message msgBuilder;
+    private Message msgOrBuilder;
+
+    @Data
+    public static class Message {
+        private long id;
+        private String name;
+    }
+}
@@ -0,0 +1,152 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.itest.protobuf;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.Mapping;
+import org.mapstruct.MappingTarget;
+import org.mapstruct.factory.Mappers;
+import org.mapstruct.itest.protobuf.Everything;
+
+import static org.mapstruct.CollectionMappingStrategy.TARGET_IMMUTABLE;
+import static org.mapstruct.NullValueCheckStrategy.ALWAYS;
+import static org.mapstruct.NullValuePropertyMappingStrategy.IGNORE;
+import static org.mapstruct.ReportingPolicy.ERROR;
+
+@Mapper(
+    nullValueCheckStrategy = ALWAYS,
+    nullValuePropertyMappingStrategy = IGNORE,
+    collectionMappingStrategy = TARGET_IMMUTABLE,
+    unmappedTargetPolicy = ERROR,
+    unmappedSourcePolicy = ERROR)
+public abstract class EverythingMapper {
+
+    public static final EverythingMapper INSTANCE = Mappers.getMapper( EverythingMapper.class );
+
+    // proto2
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract Everything proto2ToJavaBean(EverythingProto2 proto);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract EverythingProto2 javaBeanToProto2(Everything javaBean);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract void updateProto2FromJavaBean(@MappingTarget EverythingProto2.Builder proto, Everything javaBean);
+
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract void updateJavaBeanFromProto2(@MappingTarget Everything javaBean, EverythingProto2 proto);
+
+    // proto3
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract Everything proto3ToJavaBean(EverythingProto3 proto);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract EverythingProto3 javaBeanToProto3(Everything javaBean);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract void updateProto3FromJavaBean(@MappingTarget EverythingProto3.Builder proto, Everything javaBean);
+
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract void updateJavaBeanFromProto3(@MappingTarget Everything javaBean, EverythingProto3 proto);
+
+    // edition 2023
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract Everything edition2023ToJavaBean(EverythingEdition2023 proto);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract EverythingEdition2023 javaBeanToEdition2023(Everything javaBean);
+
+    @Mapping(target = "float", source = "float_")
+    @Mapping(target = "double", source = "double_")
+    @Mapping(target = "enum", source = "enum_")
+    public abstract void updateEdition2023FromJavaBean(
+        @MappingTarget EverythingEdition2023.Builder proto, Everything javaBean);
+
+    @Mapping(target = "float_", source = "float")
+    @Mapping(target = "double_", source = "double")
+    @Mapping(target = "enum_", source = "enum")
+    public abstract void updateJavaBeanFromEdition2023(@MappingTarget Everything javaBean, EverythingEdition2023 proto);
+
+    protected EverythingProto2.Message javaBeanMessageToProto2Message(Everything.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        var builder = EverythingProto2.Message.newBuilder();
+        builder.setId( value.getId() );
+        builder.setName( value.getName() );
+        return builder.build();
+    }
+
+    protected Everything.Message proto2MessageToJavaBeanMessage(EverythingProto2.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        Everything.Message message = new Everything.Message();
+        message.setId( value.getId() );
+        message.setName( value.getName() );
+        return message;
+    }
+
+    protected EverythingProto3.Message javaBeanMessageToProto3Message(Everything.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        var builder = EverythingProto3.Message.newBuilder();
+        builder.setId( value.getId() );
+        builder.setName( value.getName() );
+        return builder.build();
+    }
+
+    protected Everything.Message proto3MessageToJavaBeanMessage(EverythingProto3.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        Everything.Message message = new Everything.Message();
+        message.setId( value.getId() );
+        message.setName( value.getName() );
+        return message;
+    }
+
+    protected EverythingEdition2023.Message javaBeanMessageToEdition2023Message(Everything.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        var builder = EverythingEdition2023.Message.newBuilder();
+        builder.setId( value.getId() );
+        builder.setName( value.getName() );
+        return builder.build();
+    }
+
+    protected Everything.Message edition2023MessageToJavaBeanMessage(EverythingEdition2023.Message value) {
+        if ( value == null ) {
+            return null;
+        }
+        Everything.Message message = new Everything.Message();
+        message.setId( value.getId() );
+        message.setName( value.getName() );
+        return message;
+    }
+}