LUCENE-8229: add lucene.experimental, plus small changes

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

@@ -93,11 +93,7 @@ final class DisjunctionMatchesIterator implements MatchesIterator {
         }
       }
     }
-    if (mis.size() == 0)
-      return null;
-    if (mis.size() == 1)
-      return mis.get(0);
-    return new DisjunctionMatchesIterator(mis);
+    return fromSubIterators(mis);
   }
 
   static MatchesIterator fromSubIterators(List<MatchesIterator> mis) throws IOException {

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

@@ -20,12 +20,11 @@ package org.apache.lucene.search;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
-import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
-import java.util.Set;
 import java.util.stream.Collectors;
+import java.util.stream.StreamSupport;
 
 /**
  * Reports the positions and optionally offsets of all matching terms in a query
@@ -34,6 +33,8 @@ import java.util.stream.Collectors;
  * To obtain a {@link MatchesIterator} for a particular field, call {@link #getMatches(String)}.
  * Note that you can call {@link #getMatches(String)} multiple times to retrieve new
  * iterators, but it is not thread-safe.
+ *
+ * @lucene.experimental
  */
 public interface Matches extends Iterable<String> {
 
@@ -73,16 +74,11 @@ public interface Matches extends Iterable<String> {
     if (sm.size() == 1) {
       return sm.get(0);
     }
-    Set<String> fields = new HashSet<>();
-    for (Matches m : sm) {
-      for (String field : m) {
-        fields.add(field);
-      }
-    }
+
     return new Matches() {
       @Override
       public MatchesIterator getMatches(String field) throws IOException {
-        List<MatchesIterator> subIterators = new ArrayList<>();
+        List<MatchesIterator> subIterators = new ArrayList<>(sm.size());
         for (Matches m : sm) {
           MatchesIterator it = m.getMatches(field);
           if (it != null) {
@@ -94,7 +90,8 @@ public interface Matches extends Iterable<String> {
 
       @Override
       public Iterator<String> iterator() {
-        return fields.iterator();
+        // for each sub-match, iterate its fields (it's an Iterable of the fields), and return the distinct set
+        return sm.stream().flatMap(m -> StreamSupport.stream(m.spliterator(), false)).distinct().iterator();
       }
     };
   }

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

@@ -32,6 +32,8 @@ import org.apache.lucene.util.BytesRef;
  * Matches are ordered by start position, and then by end position.  Match intervals may overlap.
  *
  * @see Weight#matches(LeafReaderContext, int)
+ *
+ * @lucene.experimental
  */
 public interface MatchesIterator {
 

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

@@ -78,6 +78,7 @@ public abstract class Weight implements SegmentCacheable {
    *
    * @param context the reader's context to create the {@link Matches} for
    * @param doc     the document's id relative to the given context's reader
+   * @lucene.experimental
    */
   public Matches matches(LeafReaderContext context, int doc) throws IOException {
     Scorer scorer = scorer(context);