feat: add nullness annotations to public API part 2

benchmark/pom.xml

@@ -148,7 +148,6 @@
     <dependency>
       <groupId>org.jspecify</groupId>
       <artifactId>jspecify</artifactId>
-      <scope>test</scope>
     </dependency>
   </dependencies>
 

benchmark/src/main/java/ai/timefold/solver/benchmark/api/PlannerBenchmark.java

@@ -2,6 +2,8 @@
 
 import java.io.File;
 
+import org.jspecify.annotations.NonNull;
+
 /**
  * A planner benchmark that runs a number of single benchmarks.
  * <p>
@@ -12,16 +14,18 @@ public interface PlannerBenchmark {
     /**
      * Run all the single benchmarks and create an overview report.
      *
-     * @return never null, the directory in which the benchmark results are stored
+     * @return the directory in which the benchmark results are stored
      */
+    @NonNull
     File benchmark();
 
     /**
      * Run all the single benchmarks, create an overview report
      * and show it in the default browser.
      *
-     * @return never null, the directory in which the benchmark results are stored
+     * @return the directory in which the benchmark results are stored
      */
+    @NonNull
     File benchmarkAndShowReportInBrowser();
 
 }

benchmark/src/main/java/ai/timefold/solver/benchmark/api/PlannerBenchmarkException.java

@@ -2,14 +2,17 @@
 
 import ai.timefold.solver.benchmark.impl.result.SingleBenchmarkResult;
 
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
 /**
  * If at least one of the {@link SingleBenchmarkResult}s of a {@link PlannerBenchmark} fail,
  * the {@link PlannerBenchmark} throws this exception
  * after all {@link SingleBenchmarkResult}s are finished and the benchmark report has been written.
  */
 public class PlannerBenchmarkException extends RuntimeException {
 
-    public PlannerBenchmarkException(String message, Throwable cause) {
+    public PlannerBenchmarkException(@NonNull String message, @Nullable Throwable cause) {
         super(message, cause);
     }
 

benchmark/src/main/java/ai/timefold/solver/benchmark/config/ProblemBenchmarksConfig.java

@@ -15,6 +15,9 @@
 import ai.timefold.solver.core.config.util.ConfigUtils;
 import ai.timefold.solver.persistence.common.api.domain.solution.SolutionFileIO;
 
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
 @XmlType(propOrder = {
         "solutionFileIOClass",
         "writeOutputSolutionEnabled",
@@ -44,99 +47,104 @@ public class ProblemBenchmarksConfig extends AbstractConfig<ProblemBenchmarksCon
     // Constructors and simple getters/setters
     // ************************************************************************
 
-    public Class<? extends SolutionFileIO<?>> getSolutionFileIOClass() {
+    public @Nullable Class<? extends SolutionFileIO<?>> getSolutionFileIOClass() {
         return solutionFileIOClass;
     }
 
-    public void setSolutionFileIOClass(Class<? extends SolutionFileIO<?>> solutionFileIOClass) {
+    public void setSolutionFileIOClass(@Nullable Class<? extends SolutionFileIO<?>> solutionFileIOClass) {
         this.solutionFileIOClass = solutionFileIOClass;
     }
 
-    public Boolean getWriteOutputSolutionEnabled() {
+    public @Nullable Boolean getWriteOutputSolutionEnabled() {
         return writeOutputSolutionEnabled;
     }
 
-    public void setWriteOutputSolutionEnabled(Boolean writeOutputSolutionEnabled) {
+    public void setWriteOutputSolutionEnabled(@Nullable Boolean writeOutputSolutionEnabled) {
         this.writeOutputSolutionEnabled = writeOutputSolutionEnabled;
     }
 
-    public List<File> getInputSolutionFileList() {
+    public @Nullable List<@NonNull File> getInputSolutionFileList() {
         return inputSolutionFileList;
     }
 
-    public void setInputSolutionFileList(List<File> inputSolutionFileList) {
+    public void setInputSolutionFileList(@Nullable List<@NonNull File> inputSolutionFileList) {
         this.inputSolutionFileList = inputSolutionFileList;
     }
 
-    public Boolean getProblemStatisticEnabled() {
+    public @Nullable Boolean getProblemStatisticEnabled() {
         return problemStatisticEnabled;
     }
 
-    public void setProblemStatisticEnabled(Boolean problemStatisticEnabled) {
+    public void setProblemStatisticEnabled(@Nullable Boolean problemStatisticEnabled) {
         this.problemStatisticEnabled = problemStatisticEnabled;
     }
 
-    public List<ProblemStatisticType> getProblemStatisticTypeList() {
+    public @Nullable List<@NonNull ProblemStatisticType> getProblemStatisticTypeList() {
         return problemStatisticTypeList;
     }
 
-    public void setProblemStatisticTypeList(List<ProblemStatisticType> problemStatisticTypeList) {
+    public void setProblemStatisticTypeList(@Nullable List<@NonNull ProblemStatisticType> problemStatisticTypeList) {
         this.problemStatisticTypeList = problemStatisticTypeList;
     }
 
-    public List<SingleStatisticType> getSingleStatisticTypeList() {
+    public @Nullable List<@NonNull SingleStatisticType> getSingleStatisticTypeList() {
         return singleStatisticTypeList;
     }
 
-    public void setSingleStatisticTypeList(List<SingleStatisticType> singleStatisticTypeList) {
+    public void setSingleStatisticTypeList(@Nullable List<@NonNull SingleStatisticType> singleStatisticTypeList) {
         this.singleStatisticTypeList = singleStatisticTypeList;
     }
 
     // ************************************************************************
     // With methods
     // ************************************************************************
 
-    public ProblemBenchmarksConfig withSolutionFileIOClass(Class<? extends SolutionFileIO<?>> solutionFileIOClass) {
+    public @NonNull ProblemBenchmarksConfig
+            withSolutionFileIOClass(@NonNull Class<? extends SolutionFileIO<?>> solutionFileIOClass) {
         this.setSolutionFileIOClass(solutionFileIOClass);
         return this;
     }
 
-    public ProblemBenchmarksConfig withWriteOutputSolutionEnabled(Boolean writeOutputSolutionEnabled) {
+    public @NonNull ProblemBenchmarksConfig withWriteOutputSolutionEnabled(@NonNull Boolean writeOutputSolutionEnabled) {
         this.setWriteOutputSolutionEnabled(writeOutputSolutionEnabled);
         return this;
     }
 
-    public ProblemBenchmarksConfig withInputSolutionFileList(List<File> inputSolutionFileList) {
+    public @NonNull ProblemBenchmarksConfig withInputSolutionFileList(@NonNull List<@NonNull File> inputSolutionFileList) {
         this.setInputSolutionFileList(inputSolutionFileList);
         return this;
     }
 
-    public ProblemBenchmarksConfig withInputSolutionFiles(File... inputSolutionFiles) {
+    public @NonNull ProblemBenchmarksConfig withInputSolutionFiles(@NonNull File... inputSolutionFiles) {
         this.setInputSolutionFileList(List.of(inputSolutionFiles));
         return this;
     }
 
-    public ProblemBenchmarksConfig withProblemStatisticsEnabled(Boolean problemStatisticEnabled) {
+    public @NonNull ProblemBenchmarksConfig withProblemStatisticsEnabled(@NonNull Boolean problemStatisticEnabled) {
         this.setProblemStatisticEnabled(problemStatisticEnabled);
         return this;
     }
 
-    public ProblemBenchmarksConfig withProblemStatisticTypeList(List<ProblemStatisticType> problemStatisticTypeList) {
+    public @NonNull ProblemBenchmarksConfig
+            withProblemStatisticTypeList(@NonNull List<@NonNull ProblemStatisticType> problemStatisticTypeList) {
         this.setProblemStatisticTypeList(problemStatisticTypeList);
         return this;
     }
 
-    public ProblemBenchmarksConfig withProblemStatisticTypes(ProblemStatisticType... problemStatisticTypes) {
+    public @NonNull ProblemBenchmarksConfig
+            withProblemStatisticTypes(@NonNull ProblemStatisticType... problemStatisticTypes) {
         this.setProblemStatisticTypeList(List.of(problemStatisticTypes));
         return this;
     }
 
-    public ProblemBenchmarksConfig withSingleStatisticTypeList(List<SingleStatisticType> singleStatisticTypeList) {
+    public @NonNull ProblemBenchmarksConfig
+            withSingleStatisticTypeList(@NonNull List<@NonNull SingleStatisticType> singleStatisticTypeList) {
         this.setSingleStatisticTypeList(singleStatisticTypeList);
         return this;
     }
 
-    public ProblemBenchmarksConfig withSingleStatisticTypes(SingleStatisticType... singleStatisticTypes) {
+    public @NonNull ProblemBenchmarksConfig
+            withSingleStatisticTypes(@NonNull SingleStatisticType... singleStatisticTypes) {
         this.setSingleStatisticTypeList(List.of(singleStatisticTypes));
         return this;
     }
@@ -148,10 +156,8 @@ public ProblemBenchmarksConfig withSingleStatisticTypes(SingleStatisticType... s
     /**
      * Return the problem statistic type list, or a list containing default metrics if problemStatisticEnabled
      * is not false. If problemStatisticEnabled is false, an empty list is returned.
-     *
-     * @return never null
      */
-    public List<ProblemStatisticType> determineProblemStatisticTypeList() {
+    public @NonNull List<@NonNull ProblemStatisticType> determineProblemStatisticTypeList() {
         if (problemStatisticEnabled != null && !problemStatisticEnabled) {
             return Collections.emptyList();
         }
@@ -165,15 +171,13 @@ public List<ProblemStatisticType> determineProblemStatisticTypeList() {
 
     /**
      * Return the single statistic type list, or an empty list if it is null
-     *
-     * @return never null
      */
-    public List<SingleStatisticType> determineSingleStatisticTypeList() {
+    public @NonNull List<@NonNull SingleStatisticType> determineSingleStatisticTypeList() {
         return Objects.requireNonNullElse(singleStatisticTypeList, Collections.emptyList());
     }
 
     @Override
-    public ProblemBenchmarksConfig inherit(ProblemBenchmarksConfig inheritedConfig) {
+    public @NonNull ProblemBenchmarksConfig inherit(@NonNull ProblemBenchmarksConfig inheritedConfig) {
         solutionFileIOClass = ConfigUtils.inheritOverwritableProperty(solutionFileIOClass,
                 inheritedConfig.getSolutionFileIOClass());
         writeOutputSolutionEnabled = ConfigUtils.inheritOverwritableProperty(writeOutputSolutionEnabled,
@@ -190,12 +194,12 @@ public ProblemBenchmarksConfig inherit(ProblemBenchmarksConfig inheritedConfig)
     }
 
     @Override
-    public ProblemBenchmarksConfig copyConfig() {
+    public @NonNull ProblemBenchmarksConfig copyConfig() {
         return new ProblemBenchmarksConfig().inherit(this);
     }
 
     @Override
-    public void visitReferencedClasses(Consumer<Class<?>> classVisitor) {
+    public void visitReferencedClasses(@NonNull Consumer<Class<?>> classVisitor) {
         classVisitor.accept(solutionFileIOClass);
     }
 

benchmark/src/main/java/ai/timefold/solver/benchmark/config/SolverBenchmarkConfig.java

@@ -9,6 +9,9 @@
 import ai.timefold.solver.core.config.solver.SolverConfig;
 import ai.timefold.solver.core.config.util.ConfigUtils;
 
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
 @XmlType(propOrder = {
         "name",
         "solverConfig",
@@ -31,64 +34,65 @@ public class SolverBenchmarkConfig extends AbstractConfig<SolverBenchmarkConfig>
     // Constructors and simple getters/setters
     // ************************************************************************
 
-    public String getName() {
+    public @Nullable String getName() {
         return name;
     }
 
-    public void setName(String name) {
+    public void setName(@Nullable String name) {
         this.name = name;
     }
 
-    public SolverConfig getSolverConfig() {
+    public @Nullable SolverConfig getSolverConfig() {
         return solverConfig;
     }
 
-    public void setSolverConfig(SolverConfig solverConfig) {
+    public void setSolverConfig(@Nullable SolverConfig solverConfig) {
         this.solverConfig = solverConfig;
     }
 
-    public ProblemBenchmarksConfig getProblemBenchmarksConfig() {
+    public @Nullable ProblemBenchmarksConfig getProblemBenchmarksConfig() {
         return problemBenchmarksConfig;
     }
 
-    public void setProblemBenchmarksConfig(ProblemBenchmarksConfig problemBenchmarksConfig) {
+    public void setProblemBenchmarksConfig(@Nullable ProblemBenchmarksConfig problemBenchmarksConfig) {
         this.problemBenchmarksConfig = problemBenchmarksConfig;
     }
 
-    public Integer getSubSingleCount() {
+    public @Nullable Integer getSubSingleCount() {
         return subSingleCount;
     }
 
-    public void setSubSingleCount(Integer subSingleCount) {
+    public void setSubSingleCount(@Nullable Integer subSingleCount) {
         this.subSingleCount = subSingleCount;
     }
 
     // ************************************************************************
     // With methods
     // ************************************************************************
 
-    public SolverBenchmarkConfig withName(String name) {
+    public @NonNull SolverBenchmarkConfig withName(@NonNull String name) {
         this.setName(name);
         return this;
     }
 
-    public SolverBenchmarkConfig withSolverConfig(SolverConfig solverConfig) {
+    public @NonNull SolverBenchmarkConfig withSolverConfig(@NonNull SolverConfig solverConfig) {
         this.setSolverConfig(solverConfig);
         return this;
     }
 
-    public SolverBenchmarkConfig withProblemBenchmarksConfig(ProblemBenchmarksConfig problemBenchmarksConfig) {
+    public @NonNull SolverBenchmarkConfig
+            withProblemBenchmarksConfig(@NonNull ProblemBenchmarksConfig problemBenchmarksConfig) {
         this.setProblemBenchmarksConfig(problemBenchmarksConfig);
         return this;
     }
 
-    public SolverBenchmarkConfig withSubSingleCount(Integer subSingleCount) {
+    public @NonNull SolverBenchmarkConfig withSubSingleCount(@NonNull Integer subSingleCount) {
         this.setSubSingleCount(subSingleCount);
         return this;
     }
 
     @Override
-    public SolverBenchmarkConfig inherit(SolverBenchmarkConfig inheritedConfig) {
+    public @NonNull SolverBenchmarkConfig inherit(@NonNull SolverBenchmarkConfig inheritedConfig) {
         solverConfig = ConfigUtils.inheritConfig(solverConfig, inheritedConfig.getSolverConfig());
         problemBenchmarksConfig = ConfigUtils.inheritConfig(problemBenchmarksConfig,
                 inheritedConfig.getProblemBenchmarksConfig());
@@ -97,12 +101,12 @@ public SolverBenchmarkConfig inherit(SolverBenchmarkConfig inheritedConfig) {
     }
 
     @Override
-    public SolverBenchmarkConfig copyConfig() {
+    public @NonNull SolverBenchmarkConfig copyConfig() {
         return new SolverBenchmarkConfig().inherit(this);
     }
 
     @Override
-    public void visitReferencedClasses(Consumer<Class<?>> classVisitor) {
+    public void visitReferencedClasses(@NonNull Consumer<Class<?>> classVisitor) {
         if (solverConfig != null) {
             solverConfig.visitReferencedClasses(classVisitor);
         }

benchmark/src/main/java/ai/timefold/solver/benchmark/config/blueprint/SolverBenchmarkBluePrintConfig.java

@@ -6,26 +6,29 @@
 
 import ai.timefold.solver.benchmark.config.SolverBenchmarkConfig;
 
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
 @XmlType(propOrder = {
         "solverBenchmarkBluePrintType"
 })
 public class SolverBenchmarkBluePrintConfig {
 
     protected SolverBenchmarkBluePrintType solverBenchmarkBluePrintType = null;
 
-    public SolverBenchmarkBluePrintType getSolverBenchmarkBluePrintType() {
+    public @Nullable SolverBenchmarkBluePrintType getSolverBenchmarkBluePrintType() {
         return solverBenchmarkBluePrintType;
     }
 
-    public void setSolverBenchmarkBluePrintType(SolverBenchmarkBluePrintType solverBenchmarkBluePrintType) {
+    public void setSolverBenchmarkBluePrintType(@Nullable SolverBenchmarkBluePrintType solverBenchmarkBluePrintType) {
         this.solverBenchmarkBluePrintType = solverBenchmarkBluePrintType;
     }
 
     // ************************************************************************
     // Builder methods
     // ************************************************************************
 
-    public List<SolverBenchmarkConfig> buildSolverBenchmarkConfigList() {
+    public @NonNull List<SolverBenchmarkConfig> buildSolverBenchmarkConfigList() {
         validate();
         return solverBenchmarkBluePrintType.buildSolverBenchmarkConfigList();
     }
@@ -42,8 +45,8 @@ protected void validate() {
     // With methods
     // ************************************************************************
 
-    public SolverBenchmarkBluePrintConfig withSolverBenchmarkBluePrintType(
-            SolverBenchmarkBluePrintType solverBenchmarkBluePrintType) {
+    public @NonNull SolverBenchmarkBluePrintConfig withSolverBenchmarkBluePrintType(
+            @NonNull SolverBenchmarkBluePrintType solverBenchmarkBluePrintType) {
         this.solverBenchmarkBluePrintType = solverBenchmarkBluePrintType;
         return this;
     }