Serialization and docs

core/src/main/java/ai/timefold/solver/core/api/score/analysis/MatchAnalysis.java

@@ -22,8 +22,10 @@ public record MatchAnalysis<Score_ extends Score<Score_>>(@NonNull ConstraintRef
     public MatchAnalysis {
         Objects.requireNonNull(constraintRef);
         Objects.requireNonNull(score);
-        Objects.requireNonNull(justification, """
-                Received a null justification.
+        // Null justification is impossible;
+        // if the fetch policy doesn't requre match analysis, the code shouldn't even get here.
+        Objects.requireNonNull(justification, () -> """
+                Impossible state: Received a null justification.
                 Maybe check your %s's justifyWith() implementation for that constraint?"""
                 .formatted(ConstraintProvider.class));
     }
@@ -42,8 +44,9 @@ public int compareTo(MatchAnalysis<Score_> other) {
         if (scoreComparison != 0) {
             return scoreComparison;
         } else {
-            if (this.justification instanceof Comparable && other.justification instanceof Comparable) {
-                return ((Comparable) this.justification).compareTo(other.justification);
+            if (this.justification instanceof Comparable comparableJustification
+                    && other.justification instanceof Comparable otherComparableJustification) {
+                return comparableJustification.compareTo(otherComparableJustification);
             } else {
                 return 0;
             }

docs/src/modules/ROOT/pages/constraints-and-score/understanding-the-score.adoc

@@ -108,6 +108,15 @@ Using score analysis, you can find out:
 * Which constraints are broken, and how many times.
 * Which planning entities and problem facts are responsible for breaking which constraints.
 
+[NOTE]
+====
+For performance reasons and especially with large datasets that you'll later need to serialize,
+you may choose to use `ScoreAnalysis` without justifications,
+while still maintaining the count of constraint matches.
+In that case, use `ScoreAnalysisFetchPolicy.FETCH_MATCH_COUNT` instead of
+the default `ScoreAnalysisFetchPolicy.FETCH_ALL` when calling `SolutionManager.analyze(...)`.
+====
+
 It is also possible to print the score summary:
 
 [tabs]
@@ -213,7 +222,6 @@ Each match is accompanied by the score difference it caused, and a justification
 Typically, the scoring engine creates justification objects automatically
 by using the results of xref:constraints-and-score/score-calculation.adoc#constraintStreamsCustomizingJustificationsAndIndictments[Constraint Streams' `justifyWith(...)` call].
 
-
 [#scoreAnalysisDiff]
 === Identifying changes between two solutions
 
@@ -304,6 +312,12 @@ However, deserialization is easy to implement yourself by extending `AbstractSco
 and registering it with Jackson's `ObjectMapper`.
 ====
 
+With large datasets,
+you may choose to use `ScoreAnalysis` without justifications,
+while still maintaining the count of constraint matches.
+In that case, use `ScoreAnalysisFetchPolicy.FETCH_MATCH_COUNT` instead of
+the default `ScoreAnalysisFetchPolicy.FETCH_ALL` when calling `SolutionManager.analyze(...)`.
+
 
 [#indictmentHeatMap]
 == Heat map: Visualize the hot planning entities

persistence/jackson/src/main/java/ai/timefold/solver/jackson/api/score/analysis/AbstractScoreAnalysisJacksonDeserializer.java

@@ -48,6 +48,11 @@ public final ScoreAnalysis<Score_> deserialize(JsonParser p, DeserializationCont
                 for (var matchNode : constraintNode.get("matches")) {
                     var matchScore = parseScore(matchNode.get("score").asText());
                     var justificationNode = matchNode.get("justification");
+                    if (justificationNode == null) {
+                        // Not allowed; if matches are present, they must have justifications.
+                        throw new IllegalStateException("The match justification of constraint (%s)'s match is missing."
+                                .formatted(constraintRef));
+                    }
                     var justificationString = justificationNode.toString();
                     if (getConstraintJustificationClass(constraintRef) == null) { // String-based fallback.
                         var parsedJustification = parseConstraintJustification(constraintRef, justificationString, matchScore);