Deprecate SortField.setMissingValue()

lucene/CHANGES.txt

@@ -158,7 +158,10 @@ API Changes
 * GITHUB#15422: Add a new method in DirectWriter to compute how many bytes are written for encoding a number of values using a number of
   bits per value. (Ignacio Vera)
 
-* GITHUB##15428: Add support for ExecutorServices to be passed into DirectoryReader.open() and DirectoryReader.openIfChanged() APIs (Bryce Kane)
+* GITHUB#15428: Add support for ExecutorServices to be passed into DirectoryReader.open() and DirectoryReader.openIfChanged() APIs (Bryce Kane)
+
+* GITHUB#15483: Deprecate SortField.setMissingValue() in preparation for making SortField immutable
+  in Lucene 11.0. Missing values can be set as constructor parameters.  (Alan Woodward)
 
 New Features
 ---------------------

lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene70/Lucene70SegmentInfoFormat.java

@@ -231,15 +231,6 @@ private SegmentInfo parseSegmentInfo(
           throw new CorruptIndexException("invalid index sort reverse: " + b, input);
         }
 
-        if (sortedSetSelector != null) {
-          sortFields[i] = new SortedSetSortField(fieldName, reverse, sortedSetSelector);
-        } else if (sortedNumericSelector != null) {
-          sortFields[i] =
-              new SortedNumericSortField(fieldName, sortType, reverse, sortedNumericSelector);
-        } else {
-          sortFields[i] = new SortField(fieldName, sortType, reverse);
-        }
-
         Object missingValue;
         b = input.readByte();
         if (b == 0) {
@@ -288,8 +279,16 @@ private SegmentInfo parseSegmentInfo(
               throw new AssertionError("unhandled sortType=" + sortType);
           }
         }
-        if (missingValue != null) {
-          sortFields[i].setMissingValue(missingValue);
+
+        if (sortedSetSelector != null) {
+          sortFields[i] =
+              new SortedSetSortField(fieldName, reverse, sortedSetSelector, missingValue);
+        } else if (sortedNumericSelector != null) {
+          sortFields[i] =
+              new SortedNumericSortField(
+                  fieldName, sortType, reverse, sortedNumericSelector, missingValue);
+        } else {
+          sortFields[i] = new SortField(fieldName, sortType, reverse);
         }
       }
       indexSort = new Sort(sortFields);

lucene/core/src/java/org/apache/lucene/document/DoubleField.java

@@ -179,6 +179,20 @@ public static Query newSetQuery(String field, double... values) {
    */
   public static SortField newSortField(
       String field, boolean reverse, SortedNumericSelector.Type selector) {
-    return new SortedNumericSortField(field, SortField.Type.DOUBLE, reverse, selector);
+    return new SortedNumericSortField(field, SortField.Type.DOUBLE, reverse, selector, null);
+  }
+
+  /**
+   * Create a new {@link SortField} for double values.
+   *
+   * @param field field name. must not be {@code null}.
+   * @param reverse true if natural order should be reversed.
+   * @param selector custom selector type for choosing the sort value from the set.
+   * @param missingValue a sort value to use for documents with no value in the field
+   */
+  public static SortField newSortField(
+      String field, boolean reverse, SortedNumericSelector.Type selector, double missingValue) {
+    return new SortedNumericSortField(
+        field, SortField.Type.DOUBLE, reverse, selector, missingValue);
   }
 }

lucene/core/src/java/org/apache/lucene/document/FloatField.java

@@ -179,6 +179,19 @@ public static Query newSetQuery(String field, float... values) {
    */
   public static SortField newSortField(
       String field, boolean reverse, SortedNumericSelector.Type selector) {
-    return new SortedNumericSortField(field, SortField.Type.FLOAT, reverse, selector);
+    return new SortedNumericSortField(field, SortField.Type.FLOAT, reverse, selector, null);
+  }
+
+  /**
+   * Create a new {@link SortField} for float values.
+   *
+   * @param field field name. must not be {@code null}.
+   * @param reverse true if natural order should be reversed.
+   * @param selector custom selector type for choosing the sort value from the set.
+   * @param missingValue a sort value to use for documents with no value in the field
+   */
+  public static SortField newSortField(
+      String field, boolean reverse, SortedNumericSelector.Type selector, float missingValue) {
+    return new SortedNumericSortField(field, SortField.Type.FLOAT, reverse, selector, missingValue);
   }
 }

lucene/core/src/java/org/apache/lucene/document/IntField.java

@@ -172,6 +172,19 @@ public static Query newSetQuery(String field, int... values) {
    */
   public static SortField newSortField(
       String field, boolean reverse, SortedNumericSelector.Type selector) {
-    return new SortedNumericSortField(field, SortField.Type.INT, reverse, selector);
+    return new SortedNumericSortField(field, SortField.Type.INT, reverse, selector, null);
+  }
+
+  /**
+   * Create a new {@link SortField} for int values.
+   *
+   * @param field field name. must not be {@code null}.
+   * @param reverse true if natural order should be reversed.
+   * @param selector custom selector type for choosing the sort value from the set.
+   * @param missingValue a sort value to use for documents with no value in the field
+   */
+  public static SortField newSortField(
+      String field, boolean reverse, SortedNumericSelector.Type selector, int missingValue) {
+    return new SortedNumericSortField(field, SortField.Type.INT, reverse, selector, missingValue);
   }
 }

lucene/core/src/java/org/apache/lucene/document/KeywordField.java

@@ -178,6 +178,20 @@ public static Query newSetQuery(String field, Collection<BytesRef> values) {
         MultiTermQuery.CONSTANT_SCORE_BLENDED_REWRITE, field, values);
   }
 
+  /**
+   * Create a new {@link SortField} for {@link BytesRef} values.
+   *
+   * @param field field name. must not be {@code null}.
+   * @param reverse true if natural order should be reversed.
+   * @param selector custom selector type for choosing the sort value from the set.
+   */
+  public static SortField newSortField(
+      String field, boolean reverse, SortedSetSelector.Type selector, Object missingValue) {
+    Objects.requireNonNull(field, "field must not be null");
+    Objects.requireNonNull(selector, "selector must not be null");
+    return new SortedSetSortField(field, reverse, selector, missingValue);
+  }
+
   /**
    * Create a new {@link SortField} for {@link BytesRef} values.
    *
@@ -189,6 +203,6 @@ public static SortField newSortField(
       String field, boolean reverse, SortedSetSelector.Type selector) {
     Objects.requireNonNull(field, "field must not be null");
     Objects.requireNonNull(selector, "selector must not be null");
-    return new SortedSetSortField(field, reverse, selector);
+    return new SortedSetSortField(field, reverse, selector, null);
   }
 }

lucene/core/src/java/org/apache/lucene/document/LatLonPointSortField.java

@@ -27,15 +27,14 @@ final class LatLonPointSortField extends SortField {
   final double longitude;
 
   LatLonPointSortField(String field, double latitude, double longitude) {
-    super(field, SortField.Type.CUSTOM);
+    super(field, SortField.Type.CUSTOM, false, Double.POSITIVE_INFINITY);
     if (field == null) {
       throw new IllegalArgumentException("field must not be null");
     }
     GeoUtils.checkLatitude(latitude);
     GeoUtils.checkLongitude(longitude);
     this.latitude = latitude;
     this.longitude = longitude;
-    setMissingValue(Double.POSITIVE_INFINITY);
   }
 
   @Override

lucene/core/src/java/org/apache/lucene/document/LongField.java

@@ -172,7 +172,20 @@ public static Query newSetQuery(String field, long... values) {
    */
   public static SortField newSortField(
       String field, boolean reverse, SortedNumericSelector.Type selector) {
-    return new SortedNumericSortField(field, SortField.Type.LONG, reverse, selector);
+    return new SortedNumericSortField(field, SortField.Type.LONG, reverse, selector, null);
+  }
+
+  /**
+   * Create a new {@link SortField} for long values.
+   *
+   * @param field field name. must not be {@code null}.
+   * @param reverse true if natural order should be reversed.
+   * @param selector custom selector type for choosing the sort value from the set.
+   * @param missingValue a sort value to use for documents with no value in the field
+   */
+  public static SortField newSortField(
+      String field, boolean reverse, SortedNumericSelector.Type selector, long missingValue) {
+    return new SortedNumericSortField(field, SortField.Type.LONG, reverse, selector, missingValue);
   }
 
   /**

lucene/core/src/java/org/apache/lucene/document/XYPointSortField.java

@@ -26,13 +26,12 @@ final class XYPointSortField extends SortField {
   final float y;
 
   XYPointSortField(String field, float x, float y) {
-    super(field, Type.CUSTOM);
+    super(field, Type.CUSTOM, false, Double.POSITIVE_INFINITY);
     if (field == null) {
       throw new IllegalArgumentException("field must not be null");
     }
     this.x = x;
     this.y = y;
-    setMissingValue(Double.POSITIVE_INFINITY);
   }
 
   @Override

lucene/core/src/java/org/apache/lucene/search/DoubleValuesSource.java

@@ -98,7 +98,17 @@ public Explanation explain(LeafReaderContext ctx, int docId, Explanation scoreEx
    * @param reverse true if the sort should be decreasing
    */
   public SortField getSortField(boolean reverse) {
-    return new DoubleValuesSortField(this, reverse);
+    return new DoubleValuesSortField(this, reverse, 0);
+  }
+
+  /**
+   * Create a sort field based on the value of this producer
+   *
+   * @param reverse true if the sort should be decreasing
+   * @param missingValue a placeholder to use for documents with no value
+   */
+  public SortField getSortField(boolean reverse, double missingValue) {
+    return new DoubleValuesSortField(this, reverse, missingValue);
   }
 
   @Override
@@ -514,8 +524,8 @@ private static class DoubleValuesSortField extends SortField {
 
     final DoubleValuesSource producer;
 
-    DoubleValuesSortField(DoubleValuesSource producer, boolean reverse) {
-      super(producer.toString(), new DoubleValuesComparatorSource(producer), reverse);
+    DoubleValuesSortField(DoubleValuesSource producer, boolean reverse, double missingValue) {
+      super(producer.toString(), new DoubleValuesComparatorSource(producer, missingValue), reverse);
       this.producer = producer;
     }
 
@@ -549,11 +559,10 @@ public SortField rewrite(IndexSearcher searcher) throws IOException {
       if (rewrittenSource == producer) {
         return this;
       }
-      DoubleValuesSortField rewritten = new DoubleValuesSortField(rewrittenSource, reverse);
-      if (missingValue != null) {
-        rewritten.setMissingValue(missingValue);
-      }
-      return rewritten;
+      return new DoubleValuesSortField(
+          rewrittenSource,
+          reverse,
+          ((DoubleValuesComparatorSource) getComparatorSource()).missingValue);
     }
   }
 
@@ -565,9 +574,9 @@ private static class DoubleValuesComparatorSource extends FieldComparatorSource
     private final DoubleValuesSource producer;
     private double missingValue;
 
-    DoubleValuesComparatorSource(DoubleValuesSource producer) {
+    DoubleValuesComparatorSource(DoubleValuesSource producer, double missingValue) {
       this.producer = producer;
-      this.missingValue = 0d;
+      this.missingValue = missingValue;
     }
 
     void setMissingValue(double missingValue) {

lucene/core/src/java/org/apache/lucene/search/LongValuesSource.java

@@ -75,7 +75,17 @@ public abstract LongValues getValues(LeafReaderContext ctx, DoubleValues scores)
    * @param reverse true if the sort should be decreasing
    */
   public SortField getSortField(boolean reverse) {
-    return new LongValuesSortField(this, reverse);
+    return new LongValuesSortField(this, reverse, 0);
+  }
+
+  /**
+   * Create a sort field based on the value of this producer
+   *
+   * @param reverse true if the sort should be decreasing
+   * @param missingValue a placeholder to use for documents with no value
+   */
+  public SortField getSortField(boolean reverse, long missingValue) {
+    return new LongValuesSortField(this, reverse, missingValue);
   }
 
   /** Convert to a DoubleValuesSource by casting long values to doubles */
@@ -275,8 +285,8 @@ private static class LongValuesSortField extends SortField {
 
     final LongValuesSource producer;
 
-    public LongValuesSortField(LongValuesSource producer, boolean reverse) {
-      super(producer.toString(), new LongValuesComparatorSource(producer), reverse);
+    public LongValuesSortField(LongValuesSource producer, boolean reverse, long missingValue) {
+      super(producer.toString(), new LongValuesComparatorSource(producer, missingValue), reverse);
       this.producer = producer;
     }
 
@@ -310,11 +320,10 @@ public SortField rewrite(IndexSearcher searcher) throws IOException {
       if (producer == rewrittenSource) {
         return this;
       }
-      LongValuesSortField rewritten = new LongValuesSortField(rewrittenSource, reverse);
-      if (missingValue != null) {
-        rewritten.setMissingValue(missingValue);
-      }
-      return rewritten;
+      return new LongValuesSortField(
+          rewrittenSource,
+          reverse,
+          ((LongValuesComparatorSource) getComparatorSource()).missingValue);
     }
   }
 
@@ -326,9 +335,9 @@ private static class LongValuesComparatorSource extends FieldComparatorSource {
     private final LongValuesSource producer;
     private long missingValue;
 
-    public LongValuesComparatorSource(LongValuesSource producer) {
+    public LongValuesComparatorSource(LongValuesSource producer, long missingValue) {
       this.producer = producer;
-      this.missingValue = 0L;
+      this.missingValue = missingValue;
     }
 
     void setMissingValue(long missingValue) {