refactor: replace score()+impact() with getScore()+getImpact()

In the fluent API, it reads better this way.

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/score/stream/test/MultiConstraintAssertion.java

@@ -3,9 +3,10 @@
 import ai.timefold.solver.core.api.score.Score;
 import ai.timefold.solver.core.api.score.stream.ConstraintProvider;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public interface MultiConstraintAssertion {
 
     /**
@@ -14,7 +15,7 @@ public interface MultiConstraintAssertion {
      * @param score total score calculated for the given set of facts
      * @throws AssertionError when the expected score does not match the calculated score
      */
-    default void scores(@NonNull Score<?> score) {
+    default void scores(Score<?> score) {
         scores(score, null);
     }
 
@@ -25,7 +26,7 @@ default void scores(@NonNull Score<?> score) {
      * @param message description of the scenario being asserted
      * @throws AssertionError when the expected score does not match the calculated score
      */
-    void scores(@NonNull Score<?> score, @Nullable String message);
+    void scores(Score<?> score, @Nullable String message);
 
     /**
      * Returns the {@link Score} produced by all constraints in the {@link ConstraintProvider} for the given set of facts.
@@ -39,16 +40,15 @@ default void scores(@NonNull Score<?> score) {
      * {@snippet :
      * HardSoftScore scoreA = constraintVerifier.verifyThat()
      *         .givenSolution(solutionA)
-     *         .score();
+     *         .getScore();
      * HardSoftScore scoreB = constraintVerifier.verifyThat()
      *         .givenSolution(solutionB)
-     *         .score();
+     *         .getScore();
      * assertThat(scoreA).isGreaterThan(scoreB);
      * }
      *
      * @return the score produced by all constraints for the given facts, never null
      */
-    @NonNull
-    <S extends Score<S>> S score();
+    <S extends Score<S>> S getScore();
 
 }

core/src/main/java/ai/timefold/solver/core/api/score/stream/test/SingleConstraintAssertion.java

@@ -7,9 +7,10 @@
 import ai.timefold.solver.core.api.score.stream.Constraint;
 import ai.timefold.solver.core.api.score.stream.ConstraintJustification;
 
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public interface SingleConstraintAssertion {
 
     /**
@@ -19,9 +20,8 @@ public interface SingleConstraintAssertion {
      * @param message description of the scenario being asserted
      * @throws AssertionError when the expected penalty is not observed
      */
-    @NonNull
     SingleConstraintAssertion justifiesWith(@Nullable String message,
-            @NonNull ConstraintJustification @NonNull... justifications);
+            ConstraintJustification... justifications);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts, results in a given
@@ -30,7 +30,7 @@ SingleConstraintAssertion justifiesWith(@Nullable String message,
      * @param justifications the expected justifications.
      * @throws AssertionError when the expected penalty is not observed
      */
-    default @NonNull SingleConstraintAssertion justifiesWith(@NonNull ConstraintJustification @NonNull... justifications) {
+    default SingleConstraintAssertion justifiesWith(ConstraintJustification... justifications) {
         return justifiesWith(null, justifications);
     }
 
@@ -41,9 +41,8 @@ SingleConstraintAssertion justifiesWith(@Nullable String message,
      * @param message description of the scenario being asserted
      * @throws AssertionError when the expected penalty is not observed
      */
-    @NonNull
     SingleConstraintAssertion justifiesWithExactly(@Nullable String message,
-            @NonNull ConstraintJustification @NonNull... justifications);
+            ConstraintJustification... justifications);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts, results in a given
@@ -52,8 +51,8 @@ SingleConstraintAssertion justifiesWithExactly(@Nullable String message,
      * @param justifications the expected justifications.
      * @throws AssertionError when the expected penalty is not observed
      */
-    default @NonNull SingleConstraintAssertion
-            justifiesWithExactly(@NonNull ConstraintJustification @NonNull... justifications) {
+    default SingleConstraintAssertion
+            justifiesWithExactly(ConstraintJustification... justifications) {
         return justifiesWithExactly(null, justifications);
     }
 
@@ -126,7 +125,7 @@ default void penalizesBy(long matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    default void penalizesBy(@NonNull BigDecimal matchWeightTotal) {
+    default void penalizesBy(BigDecimal matchWeightTotal) {
         penalizesBy(null, matchWeightTotal);
     }
 
@@ -137,7 +136,7 @@ default void penalizesBy(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    void penalizesBy(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void penalizesBy(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts, results in a given number of penalties.
@@ -232,7 +231,7 @@ default void rewardsWith(long matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    default void rewardsWith(@NonNull BigDecimal matchWeightTotal) {
+    default void rewardsWith(BigDecimal matchWeightTotal) {
         rewardsWith(null, matchWeightTotal);
     }
 
@@ -243,7 +242,7 @@ default void rewardsWith(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    void rewardsWith(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void rewardsWith(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts, results in a given number of rewards.
@@ -341,7 +340,7 @@ default void penalizesByMoreThan(long matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    default void penalizesByMoreThan(@NonNull BigDecimal matchWeightTotal) {
+    default void penalizesByMoreThan(BigDecimal matchWeightTotal) {
         penalizesByMoreThan(null, matchWeightTotal);
     }
 
@@ -352,7 +351,7 @@ default void penalizesByMoreThan(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    void penalizesByMoreThan(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void penalizesByMoreThan(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts,
@@ -431,7 +430,7 @@ default void rewardsWithMoreThan(long matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    default void rewardsWithMoreThan(@NonNull BigDecimal matchWeightTotal) {
+    default void rewardsWithMoreThan(BigDecimal matchWeightTotal) {
         rewardsWithMoreThan(null, matchWeightTotal);
     }
 
@@ -442,7 +441,7 @@ default void rewardsWithMoreThan(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 0, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    void rewardsWithMoreThan(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void rewardsWithMoreThan(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts,
@@ -522,7 +521,7 @@ default void penalizesByLessThan(long matchWeightTotal) {
      * @param matchWeightTotal at least 1, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    default void penalizesByLessThan(@NonNull BigDecimal matchWeightTotal) {
+    default void penalizesByLessThan(BigDecimal matchWeightTotal) {
         penalizesByLessThan(null, matchWeightTotal);
     }
 
@@ -533,7 +532,7 @@ default void penalizesByLessThan(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 1, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected penalty is not observed
      */
-    void penalizesByLessThan(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void penalizesByLessThan(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts,
@@ -612,7 +611,7 @@ default void rewardsWithLessThan(long matchWeightTotal) {
      * @param matchWeightTotal at least 1, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    default void rewardsWithLessThan(@NonNull BigDecimal matchWeightTotal) {
+    default void rewardsWithLessThan(BigDecimal matchWeightTotal) {
         rewardsWithLessThan(null, matchWeightTotal);
     }
 
@@ -623,7 +622,7 @@ default void rewardsWithLessThan(@NonNull BigDecimal matchWeightTotal) {
      * @param matchWeightTotal at least 1, expected sum of match weights of matches of the constraint.
      * @throws AssertionError when the expected reward is not observed
      */
-    void rewardsWithLessThan(@Nullable String message, @NonNull BigDecimal matchWeightTotal);
+    void rewardsWithLessThan(@Nullable String message, BigDecimal matchWeightTotal);
 
     /**
      * Asserts that the {@link Constraint} being tested, given a set of facts,
@@ -662,22 +661,21 @@ default void rewardsLessThan(long times) {
      * {@snippet :
      * HardSoftScore scoreA = constraintVerifier.verifyThat(MyConstraints::roomConflict)
      *         .given(entity1, entity2)
-     *         .score();
+     *         .getScore();
      * HardSoftScore scoreB = constraintVerifier.verifyThat(MyConstraints::roomConflict)
      *         .given(entity3, entity4)
-     *         .score();
+     *         .getScore();
      * assertThat(scoreA).isLessThan(scoreB);
      * }
      *
      * @return the score produced by this single constraint for the given facts, never null
      */
-    @NonNull
-    <S extends Score<S>> S score();
+    <S extends Score<S>> S getScore();
 
     /**
      * Returns the match weight total of the {@link Constraint} being tested for the given set of facts.
      * <p>
-     * Unlike {@link #score()}, which returns the full score (match weight × constraint weight),
+     * Unlike {@link #getScore()}, which returns the full score (match weight × constraint weight),
      * this method returns only the <b>match weight</b> — the same number you would pass
      * to assertion methods like {@link #penalizesBy(int)} or {@link #rewardsWith(int)}.
      * <p>
@@ -687,19 +685,18 @@ default void rewardsLessThan(long times) {
      * Usage example:
      *
      * {@snippet :
-     * Number impactA = constraintVerifier.verifyThat(MyConstraints::roomConflict)
+     * var impactA = constraintVerifier.verifyThat(MyConstraints::roomConflict)
      *         .given(entity1, entity2)
-     *         .impact();
-     * Number impactB = constraintVerifier.verifyThat(MyConstraints::roomConflict)
+     *         .getImpact();
+     * var impactB = constraintVerifier.verifyThat(MyConstraints::roomConflict)
      *         .given(entity3, entity4)
-     *         .impact();
+     *         .getImpact();
      * assertThat(impactA.intValue()).isGreaterThan(impactB.intValue());
      * }
      *
      * @return the match weight total produced by this single constraint, never null.
      *         Positive for rewards, negative for penalties, zero when there is no impact.
      */
-    @NonNull
-    Number impact();
+    Number getImpact();
 
 }

core/src/main/java/ai/timefold/solver/core/impl/score/stream/test/AbstractMultiConstraintAssertion.java

@@ -59,7 +59,7 @@ public void scores(@NonNull Score<?> score, String message) {
 
     @Override
     @SuppressWarnings("unchecked")
-    public <S extends Score<S>> S score() {
+    public <S extends Score<S>> S getScore() {
         ensureInitialized();
         return (S) actualScore.raw();
     }

core/src/main/java/ai/timefold/solver/core/impl/score/stream/test/AbstractSingleConstraintAssertion.java

@@ -254,13 +254,13 @@ public void rewardsWithLessThan(@Nullable String message, @NonNull BigDecimal ma
 
     @Override
     @SuppressWarnings("unchecked")
-    public <S extends Score<S>> S score() {
+    public <S extends Score<S>> S getScore() {
         ensureInitialized();
         return (S) actualScore.raw();
     }
 
     @Override
-    public Number impact() {
+    public Number getImpact() {
         ensureInitialized();
         return deduceImpact().key();
     }

core/src/test/java/ai/timefold/solver/core/impl/score/stream/test/MultiConstraintAssertionTest.java

@@ -71,7 +71,7 @@ void checksScore() {
     }
 
     @Test
-    void scoreReturnsTypedScoreWithGivenFacts() {
+    void getScoreReturnsTypedScoreWithGivenFacts() {
         var constraintVerifier = ConstraintVerifier.build(new TestdataConstraintVerifierConstraintProvider(),
                 TestdataConstraintVerifierExtendedSolution.class,
                 TestdataConstraintVerifierFirstEntity.class,
@@ -81,7 +81,7 @@ void scoreReturnsTypedScoreWithGivenFacts() {
         HardSoftScore score = constraintVerifier
                 .verifyThat()
                 .given(entity)
-                .score();
+                .getScore();
 
         assertThat(score).isNotNull();
         assertThat(score).isInstanceOf(HardSoftScore.class);
@@ -91,7 +91,7 @@ void scoreReturnsTypedScoreWithGivenFacts() {
     }
 
     @Test
-    void scoreEnablesRelativeComparisonWithGivenFacts() {
+    void getScoreEnablesRelativeComparisonWithGivenFacts() {
         var constraintVerifier = ConstraintVerifier.build(new TestdataConstraintVerifierConstraintProvider(),
                 TestdataConstraintVerifierExtendedSolution.class,
                 TestdataConstraintVerifierFirstEntity.class,
@@ -106,11 +106,11 @@ void scoreEnablesRelativeComparisonWithGivenFacts() {
         HardSoftScore scoreA = constraintVerifier
                 .verifyThat()
                 .given(entityA)
-                .score();
+                .getScore();
         HardSoftScore scoreB = constraintVerifier
                 .verifyThat()
                 .given(entityB1, entityB2)
-                .score();
+                .getScore();
 
         assertThat(scoreA).isGreaterThan(scoreB);
     }

core/src/test/java/ai/timefold/solver/core/impl/score/stream/test/SingleConstraintAssertionTest.java

@@ -587,35 +587,35 @@ void impactsByLessThan() {
     }
 
     @Test
-    void impactEnablesRelativeComparison() {
+    void getImpactEnablesRelativeComparison() {
         var entityA = new TestdataConstraintVerifierFirstEntity("A", new TestdataValue());
         var solution = TestdataConstraintVerifierSolution.generateSolution(2, 3);
 
-        Number impactA = constraintVerifier
+        var impactA = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::penalizeEveryEntity)
                 .given(entityA)
-                .impact();
-        Number impactB = constraintVerifier
+                .getImpact();
+        var impactB = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::penalizeEveryEntity)
                 .given(solution.getEntityList().toArray())
-                .impact();
+                .getImpact();
 
         assertThat(impactB.intValue()).isGreaterThan(impactA.intValue());
     }
 
     @Test
-    void scoreEnablesRelativeComparisonForRewards() {
+    void getScoreEnablesRelativeComparisonForRewards() {
         var entityA = new TestdataConstraintVerifierFirstEntity("A", new TestdataValue());
         var solution = TestdataConstraintVerifierSolution.generateSolution(2, 3);
 
         HardSoftScore scoreA = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::rewardEveryEntity)
                 .given(entityA)
-                .score();
+                .getScore();
         HardSoftScore scoreB = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::rewardEveryEntity)
                 .given(solution.getEntityList().toArray())
-                .score();
+                .getScore();
 
         assertThat(scoreA).isNotNull();
         assertThat(scoreA).isInstanceOf(HardSoftScore.class);
@@ -631,18 +631,18 @@ void scoreEnablesRelativeComparisonForRewards() {
     }
 
     @Test
-    void scoreComparesGivenSolutions() {
+    void getScoreComparesGivenSolutions() {
         var smallSolution = TestdataConstraintVerifierExtendedSolution.generateSolution(2, 2);
         var largeSolution = TestdataConstraintVerifierExtendedSolution.generateSolution(2, 4);
 
         HardSoftScore smallScore = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::penalizeEveryEntity)
                 .givenSolution(smallSolution)
-                .score();
+                .getScore();
         HardSoftScore largeScore = constraintVerifier
                 .verifyThat(TestdataConstraintVerifierConstraintProvider::penalizeEveryEntity)
                 .givenSolution(largeSolution)
-                .score();
+                .getScore();
 
         assertThat(smallScore).isGreaterThan(largeScore);
     }