LUCENE-8662: Change TermsEnum.seekExact(BytesRef) to abstract + delegate seekExact(BytesRef) in FilterLeafReader.FilterTermsEnum

lucene/CHANGES.txt

@@ -22,6 +22,9 @@ Bug fixes:
 
 API Changes
 
+* LUCENE-8662: TermsEnum.seekExact(BytesRef) to abstract and delegate seekExact(BytesRef)
+  in FilterLeafReader.FilterTermsEnum. (Jeffery Yuan via Tomás Fernández Löbbe, Simon Willnauer)
+
 * LUCENE-8469: Deprecated StringHelper.compare has been removed. (Dawid Weiss)
 
 * LUCENE-8039: Introduce a "delta distance" method set to GeoDistance.  This

lucene/MIGRATE.txt

@@ -1,5 +1,12 @@
 # Apache Lucene Migration Guide
 
+## TermsEnum.seekExact(BytesRef) is abstract (LUCENE-8662) ##
+
+TermsEnum.seekExact has been changed to abstract, so non-abstract subclass must implement it.
+The default implementation can be seekCeil(text) == SeekStatus.FOUND.
+This method is performance critical, so subclass SHOULD have its own implementation
+if possible instead of using the default implementation.
+
 ## RAMDirectory, RAMFile, RAMInputStream, RAMOutputStream removed ##
 
 RAM-based directory implementation have been removed. (LUCENE-8474). 

lucene/backward-codecs/src/java/org/apache/lucene/codecs/lucene70/Lucene70DocValuesProducer.java

@@ -1031,6 +1031,11 @@ public BytesRef next() throws IOException {
       return term;
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) throws IOException {
       if (ord < 0 || ord >= entry.termsDictSize) {

lucene/codecs/src/java/org/apache/lucene/codecs/blockterms/BlockTermsReader.java

@@ -685,6 +685,11 @@ public TermState termState() throws IOException {
         return ts;
       }
 
+      @Override
+      public boolean seekExact(BytesRef text) throws IOException {
+        return seekCeil(text) == SeekStatus.FOUND;
+      }
+
       @Override
       public void seekExact(long ord) throws IOException {
         //System.out.println("BTR.seek by ord ord=" + ord);

lucene/codecs/src/java/org/apache/lucene/codecs/memory/DirectPostingsFormat.java

@@ -1507,6 +1507,11 @@ public SeekStatus seekCeil(BytesRef term) {
       public void seekExact(long ord) {
         throw new UnsupportedOperationException();
       }
+
+      @Override
+      public boolean seekExact(BytesRef text) throws IOException {
+        return seekCeil(text) == SeekStatus.FOUND;
+      }
     }
   }
 

lucene/codecs/src/java/org/apache/lucene/codecs/memory/FSTOrdTermsReader.java

@@ -626,6 +626,11 @@ void decodeStats() throws IOException {
         super.decodeStats();
       }
 
+      @Override
+      public boolean seekExact(BytesRef text) throws IOException {
+        return seekCeil(text) == SeekStatus.FOUND;
+      }
+
       @Override
       public SeekStatus seekCeil(BytesRef target) throws IOException {
         throw new UnsupportedOperationException();

lucene/codecs/src/java/org/apache/lucene/codecs/memory/FSTTermsReader.java

@@ -519,6 +519,11 @@ void loadMetaData() throws IOException {
         state.totalTermFreq = meta.totalTermFreq;
       }
 
+      @Override
+      public boolean seekExact(BytesRef text) throws IOException {
+        return seekCeil(text) == SeekStatus.FOUND;
+      }
+
       @Override
       public SeekStatus seekCeil(BytesRef target) throws IOException {
         decoded = false;

lucene/codecs/src/java/org/apache/lucene/codecs/simpletext/SimpleTextTermVectorsReader.java

@@ -358,6 +358,11 @@ public SeekStatus seekCeil(BytesRef text) throws IOException {
       }
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) throws IOException {
       throw new UnsupportedOperationException();

lucene/core/src/java/org/apache/lucene/codecs/compressing/CompressingTermVectorsReader.java

@@ -906,6 +906,11 @@ public SeekStatus seekCeil(BytesRef text)
       }
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) throws IOException {
       throw new UnsupportedOperationException();

lucene/core/src/java/org/apache/lucene/codecs/lucene80/Lucene80DocValuesProducer.java

@@ -973,6 +973,11 @@ public BytesRef next() throws IOException {
       return term;
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) throws IOException {
       if (ord < 0 || ord >= entry.termsDictSize) {

lucene/core/src/java/org/apache/lucene/index/FilterLeafReader.java

@@ -178,6 +178,11 @@ public AttributeSource attributes() {
     public SeekStatus seekCeil(BytesRef text) throws IOException {
       return in.seekCeil(text);
     }
+
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return in.seekExact(text);
+    }
 
     @Override
     public void seekExact(long ord) throws IOException {

lucene/core/src/java/org/apache/lucene/index/FreqProxFields.java

@@ -180,6 +180,11 @@ public SeekStatus seekCeil(BytesRef text) {
       }
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     public void seekExact(long ord) {
       this.ord = (int) ord;
       int textStart = postingsArray.textStarts[sortedTermIDs[this.ord]];

lucene/core/src/java/org/apache/lucene/index/TermsEnum.java

@@ -65,13 +65,19 @@ public static enum SeekStatus {
     NOT_FOUND
   };
 
-  /** Attempts to seek to the exact term, returning
-   *  true if the term is found.  If this returns false, the
-   *  enum is unpositioned.  For some codecs, seekExact may
-   *  be substantially faster than {@link #seekCeil}. */
-  public boolean seekExact(BytesRef text) throws IOException {
-    return seekCeil(text) == SeekStatus.FOUND;
-  }
+  /**
+   * Attempts to seek to the exact term, returning true if the term is found. If this returns false, the enum is
+   * unpositioned. For some codecs, seekExact may be substantially faster than {@link #seekCeil}.
+   * <p>
+   * 
+   * The default implementation can be <code>seekCeil(text) == SeekStatus.FOUND; </code><br>
+   * But this method is performance critical. In some cases, the default implementation may be slow and consume huge memory,
+   * so subclass SHOULD have its own implementation if possible.
+   * 
+   * @return true if the term is found; return false if the enum is unpositioned.
+   */
+  public abstract boolean seekExact(BytesRef text) throws IOException;
+
 
   /** Seeks to the specified term, if it exists, or to the
    *  next (ceiling) term.  Returns SeekStatus to
@@ -206,6 +212,11 @@ public void copyFrom(TermState other) {
     @Override
     public SeekStatus seekCeil(BytesRef term) { return SeekStatus.END; }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) {}
 

lucene/core/src/test/org/apache/lucene/index/TestCodecs.java

@@ -653,6 +653,11 @@ public SeekStatus seekCeil(BytesRef text) {
       return SeekStatus.END;
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) {
       throw new UnsupportedOperationException();

lucene/test-framework/src/java/org/apache/lucene/codecs/ramonly/RAMOnlyPostingsFormat.java

@@ -443,6 +443,11 @@ public SeekStatus seekCeil(BytesRef term) {
         }
       }
     }
+
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }    
 
     @Override
     public void seekExact(long ord) {

lucene/test-framework/src/java/org/apache/lucene/index/RandomPostingsTester.java

@@ -564,6 +564,11 @@ public BytesRef next() {
       }
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long ord) {
       throw new UnsupportedOperationException();

solr/core/src/java/org/apache/solr/uninverting/DocTermOrds.java

@@ -703,6 +703,11 @@ public SeekStatus seekCeil(BytesRef target) throws IOException {
       }
     }
 
+    @Override
+    public boolean seekExact(BytesRef text) throws IOException {
+      return seekCeil(text) == SeekStatus.FOUND;
+    }
+
     @Override
     public void seekExact(long targetOrd) throws IOException {
       int delta = (int) (targetOrd - ordBase - ord);