mapstruct · hduelme · Jul 4, 2026 · Jul 22, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/...t/src/test/java/org/mapstruct/itest/tests/FullFeatureCompilationExclusionCliEnhancer.java b/...t/src/test/java/org/mapstruct/itest/tests/FullFeatureCompilationExclusionCliEnhancer.java
@@ -41,6 +41,21 @@ public Collection<String> getAdditionalCommandLineArguments(ProcessorTest.Proces
                     additionalExcludes.add(
                         "org/mapstruct/ap/test/selection/methodgenerics/wildcards/LifecycleIntersectionMapper.java" );
                 }
+                // JDK 8 javac does not support @NullMarked applied to a method or constructor, so these
+                // mappers (which use a method-level @NullMarked) cannot be compiled on Java 8.
+                // see https://github.com/jspecify/jspecify/wiki/version-compatibility#issues-with-java-8
+                additionalExcludes.add(
+                        "org/mapstruct/ap/test/nullcheck/jspecify/JSpecifyInnerClassMapper.java" );
+                additionalExcludes.add(
+                        "org/mapstruct/ap/test/nullcheck/jspecify/DeepNestedJSpecifyMapper.java" );
+                additionalExcludes.add(
+                        "org/mapstruct/ap/test/nullcheck/jspecify/FqNameCollisionJSpecifyMapper.java" );
+                additionalExcludes.add(
+                        "org/mapstruct/ap/test/nullcheck/jspecify/annotation/*.java" );
+                // JVMs pre 22 have problems reading type in use annotations
+                // Here Java 8 does not see the nested class annotation
+                // https://github.com/jspecify/jspecify/wiki/version-compatibility#issues-with-javac-before-version-22
+                additionalExcludes.add( "org/mapstruct/ap/test/bugs/_4086/*" );
                 break;
             case JAVA_11:
                 additionalExcludes.add( "org/mapstruct/ap/test/**/spring/**/*.java" );

diff --git a/integrationtest/src/test/java/org/mapstruct/itest/tests/MavenIntegrationTest.java b/integrationtest/src/test/java/org/mapstruct/itest/tests/MavenIntegrationTest.java
@@ -200,6 +200,12 @@ void moduleInfoTest() {
 
     }
 
+    @ProcessorTest(baseDir = "moduleNullMarkedTest")
+    @EnabledForJreRange(min = JRE.JAVA_11)
+    void moduleNullMarkedTest() {
+
+    }
+
     /**
      * Tests usage of MapStruct with another processor that generates the uses type of a mapper.
      */

diff --git a/integrationtest/src/test/resources/fullFeatureTest/pom.xml b/integrationtest/src/test/resources/fullFeatureTest/pom.xml
@@ -32,6 +32,10 @@
         <additionalExclude9>x</additionalExclude9>
         <additionalExclude10>x</additionalExclude10>
         <additionalExclude11>x</additionalExclude11>
+        <additionalExclude12>x</additionalExclude12>
+        <additionalExclude13>x</additionalExclude13>
+        <additionalExclude14>x</additionalExclude14>
+        <additionalExclude15>x</additionalExclude15>
     </properties>
 
     <build>
@@ -62,6 +66,8 @@
                         <exclude>${additionalExclude11}</exclude>
                         <exclude>${additionalExclude12}</exclude>
                         <exclude>${additionalExclude13}</exclude>
+                        <exclude>${additionalExclude14}</exclude>
+                        <exclude>${additionalExclude15}</exclude>
                     </excludes>
                 </configuration>
             </plugin>

diff --git a/integrationtest/src/test/resources/moduleNullMarkedTest/pom.xml b/integrationtest/src/test/resources/moduleNullMarkedTest/pom.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright MapStruct Authors.
+
+    Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.mapstruct</groupId>
+        <artifactId>mapstruct-it-parent</artifactId>
+        <version>1.0.0</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>moduleNullMarkedTest</artifactId>
+    <packaging>jar</packaging>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+        </dependency>
+    </dependencies>
+</project>
diff --git a/integrationtest/src/test/resources/moduleNullMarkedTest/src/main/java/module-info.java b/integrationtest/src/test/resources/moduleNullMarkedTest/src/main/java/module-info.java
@@ -0,0 +1,15 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+module test.mapstruct {
+    requires static org.jspecify;
+    requires org.mapstruct;
+
+    exports org.mapstruct.itest.modules.nullmarked;
+    exports org.mapstruct.itest.modules.nullunmarked;
+}
diff --git a/...NullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedMapper.java b/...NullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedMapper.java
@@ -0,0 +1,26 @@
+/*
+ * 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.modules.nullmarked;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.NullValueCheckStrategy;
+import org.mapstruct.factory.Mappers;
+
+/**
+ * Mapper in a {@code @NullMarked} module with {@link NullValueCheckStrategy#ALWAYS}.
+ * <p>
+ * With the module (and package) in a {@code @NullMarked} scope, the source getter and target
+ * setter parameter are both effectively {@code @NonNull}. The {@code ALWAYS} null-check must
+ * therefore be suppressed: the target setter is called even when the source value is {@code null},
+ * because the mapping is between two {@code @NonNull} types.
+ */
+@Mapper(nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
+public interface NullMarkedMapper {
+
+    NullMarkedMapper INSTANCE = Mappers.getMapper( NullMarkedMapper.class );
+
+    NullMarkedTargetBean map(NullMarkedSourceBean source);
+}
diff --git a/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedSourceBean.java b/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedSourceBean.java
@@ -0,0 +1,23 @@
+/*
+ * 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.modules.nullmarked;
+
+/**
+ * Source bean in a {@code @NullMarked} module + {@code @NullMarked} package.
+ * The unannotated {@code String value} getter is effectively {@code @NonNull}.
+ */
+public class NullMarkedSourceBean {
+
+    private String value;
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.value = value;
+    }
+}
diff --git a/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedTargetBean.java b/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/NullMarkedTargetBean.java
@@ -0,0 +1,29 @@
+/*
+ * 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.modules.nullmarked;
+
+/**
+ * Target bean in a {@code @NullMarked} module + {@code @NullMarked} package.
+ * The unannotated {@code String value} setter parameter is effectively {@code @NonNull}.
+ */
+public class NullMarkedTargetBean {
+
+    private String value;
+    private boolean valueSet;
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.valueSet = true;
+        this.value = value;
+    }
+
+    public boolean isValueSet() {
+        return valueSet;
+    }
+}
diff --git a/...duleNullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/package-info.java b/...duleNullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullmarked/package-info.java
@@ -0,0 +1,6 @@
+/*
+ * 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.modules.nullmarked;
diff --git a/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedMapper.java b/...MarkedTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedMapper.java
@@ -0,0 +1,27 @@
+/*
+ * 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.modules.nullunmarked;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.NullValueCheckStrategy;
+import org.mapstruct.factory.Mappers;
+
+/**
+ * Mapper in a {@code @NullUnmarked} package (inside a {@code @NullMarked} module) with
+ * {@link NullValueCheckStrategy#ALWAYS}.
+ * <p>
+ * The package-level {@code @NullUnmarked} reverses the module-level {@code @NullMarked} scope.
+ * The source getter and target setter parameter therefore have UNKNOWN nullability and the
+ * {@code ALWAYS} null-check strategy applies: the target setter is NOT called when the source
+ * value is {@code null}.
+ */
+@Mapper(nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
+public interface NullUnmarkedMapper {
+
+    NullUnmarkedMapper INSTANCE = Mappers.getMapper( NullUnmarkedMapper.class );
+
+    NullUnmarkedTargetBean map(NullUnmarkedSourceBean source);
+}
diff --git a/...edTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedSourceBean.java b/...edTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedSourceBean.java
@@ -0,0 +1,24 @@
+/*
+ * 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.modules.nullunmarked;
+
+/**
+ * Source bean in an {@code @NullUnmarked} package (inside a {@code @NullMarked} module).
+ * The package-level {@code @NullUnmarked} reverses the scope: the unannotated
+ * {@code String value} getter has UNKNOWN nullability.
+ */
+public class NullUnmarkedSourceBean {
+
+    private String value;
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.value = value;
+    }
+}
diff --git a/...edTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedTargetBean.java b/...edTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/NullUnmarkedTargetBean.java
@@ -0,0 +1,29 @@
+/*
+ * 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.modules.nullunmarked;
+
+/**
+ * Target bean in an {@code @NullUnmarked} package (inside a {@code @NullMarked} module).
+ * The unannotated {@code String value} setter parameter has UNKNOWN nullability.
+ */
+public class NullUnmarkedTargetBean {
+
+    private String value;
+    private boolean valueSet;
+
+    public String getValue() {
+        return value;
+    }
+
+    public void setValue(String value) {
+        this.valueSet = true;
+        this.value = value;
+    }
+
+    public boolean isValueSet() {
+        return valueSet;
+    }
+}
diff --git a/...leNullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/package-info.java b/...leNullMarkedTest/src/main/java/org/mapstruct/itest/modules/nullunmarked/package-info.java
@@ -0,0 +1,9 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+@NullUnmarked
+package org.mapstruct.itest.modules.nullunmarked;
+
+import org.jspecify.annotations.NullUnmarked;
diff --git a/...resources/moduleNullMarkedTest/src/test/java/org/mapstruct/itest/modules/ModulesTest.java b/...resources/moduleNullMarkedTest/src/test/java/org/mapstruct/itest/modules/ModulesTest.java
@@ -0,0 +1,54 @@
+/*
+ * 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.modules;
+
+import org.junit.jupiter.api.Test;
+import org.mapstruct.itest.modules.nullmarked.NullMarkedMapper;
+import org.mapstruct.itest.modules.nullmarked.NullMarkedSourceBean;
+import org.mapstruct.itest.modules.nullmarked.NullMarkedTargetBean;
+import org.mapstruct.itest.modules.nullunmarked.NullUnmarkedMapper;
+import org.mapstruct.itest.modules.nullunmarked.NullUnmarkedSourceBean;
+import org.mapstruct.itest.modules.nullunmarked.NullUnmarkedTargetBean;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Integration tests that verify JSpecify {@code @NullMarked} on a JPMS module is
+ * honored by the MapStruct processor, and that a package-level {@code @NullUnmarked}
+ * correctly reverses the module-level {@code @NullMarked} scope.
+ */
+class ModulesTest {
+
+    @Test
+    void nullMarkedModuleSuppressesNullCheck() {
+        // The module is @NullMarked, so unannotated types are effectively @NonNull.
+        // With NullValueCheckStrategy.ALWAYS, a source getter that is effectively
+        // @NonNull must NOT have a null check generated -> the target setter is
+        // called even when the source value is null.
+        NullMarkedSourceBean source = new NullMarkedSourceBean();
+        assertThat( source.getValue() ).isNull();
+
+        NullMarkedTargetBean target = NullMarkedMapper.INSTANCE.map( source );
+
+        assertThat( target.isValueSet() ).isTrue();
+        assertThat( target.getValue() ).isNull();
+    }
+
+    @Test
+    void nullUnmarkedPackageReversesModuleNullMarked() {
+        // The package is @NullUnmarked inside a @NullMarked module. The
+        // package-level scope reversal makes unannotated types have UNKNOWN
+        // nullability, so NullValueCheckStrategy.ALWAYS generates a null check
+        // and the target setter is NOT called when the source value is null.
+        NullUnmarkedSourceBean source = new NullUnmarkedSourceBean();
+        assertThat( source.getValue() ).isNull();
+
+        NullUnmarkedTargetBean target = NullUnmarkedMapper.INSTANCE.map( source );
+
+        assertThat( target.isValueSet() ).isFalse();
+        assertThat( target.getValue() ).isNull();
+    }
+}
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/conversion/CreateDecimalFormat.java b/processor/src/main/java/org/mapstruct/ap/internal/conversion/CreateDecimalFormat.java
@@ -17,6 +17,7 @@
 import org.mapstruct.ap.internal.model.common.Type;
 import org.mapstruct.ap.internal.model.common.TypeFactory;
 import org.mapstruct.ap.internal.model.source.MappingMethodOptions;
+import org.mapstruct.ap.internal.util.accessor.Nullability;
 
 import static org.mapstruct.ap.internal.util.Collections.asSet;
 
@@ -36,8 +37,10 @@ public class CreateDecimalFormat extends HelperMethod {
     private final Set<Type> importTypes;
 
     public CreateDecimalFormat(TypeFactory typeFactory, boolean withLocale) {
-        this.parameter = new Parameter( "numberFormat", typeFactory.getType( String.class ) );
-        this.localeParameter = withLocale ? new Parameter( "locale", typeFactory.getType( Locale.class ) ) : null;
+        this.parameter = new Parameter( "numberFormat", typeFactory.getType( String.class ),
+                Nullability.hardcodedNullability( Nullability.NullabilityState.NON_NULL ) );
+        this.localeParameter = withLocale ? new Parameter( "locale", typeFactory.getType( Locale.class ),
+                Nullability.hardcodedNullability( Nullability.NullabilityState.NON_NULL ) ) : null;
         this.returnType = typeFactory.getType( DecimalFormat.class );
         if ( withLocale ) {
             this.importTypes = asSet(
@@ -89,4 +92,9 @@ public List<Parameter> getParameters() {
         }
         return Arrays.asList( getParameter(), localeParameter );
     }
+
+    @Override
+    public Nullability getReturnTypeNullability() {
+        return Nullability.hardcodedNullability( Nullability.NullabilityState.NON_NULL );
+    }
 }
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/conversion/DateToStringConversion.java b/processor/src/main/java/org/mapstruct/ap/internal/conversion/DateToStringConversion.java
@@ -34,15 +34,17 @@ public class DateToStringConversion implements ConversionProvider {
     public Assignment to(ConversionContext conversionContext) {
         return new TypeConversion( getImportTypes( conversionContext ),
             Collections.emptyList(),
-            getConversionExpression( conversionContext, "format" )
+            getConversionExpression( conversionContext, "format" ),
+            conversionContext.getTargetType()
         );
     }
 
     @Override
     public Assignment from(ConversionContext conversionContext) {
         return new TypeConversion( getImportTypes( conversionContext ),
             Collections.singletonList( conversionContext.getTypeFactory().getType( ParseException.class ) ),
-            getConversionExpression( conversionContext, "parse" )
+            getConversionExpression( conversionContext, "parse" ),
+            conversionContext.getSourceType()
         );
     }