Improvements to patch #31841 from Wolf Siberski. Deprecation is now consistent. Tests now pass.

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@164865 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/lucene/search/FieldDoc.java

@@ -46,7 +46,7 @@ extends ScoreDoc {
 	 * Sort object.  Each Object will be either an Integer, Float or String,
 	 * depending on the type of values in the terms of the original field.
 	 * @see Sort
-	 * @see Searchable#search(Query,Filter,int,Sort)
+	 * @see Searcher#search(Query,Filter,int,Sort)
 	 */
 	public Comparable[] fields;
 

src/java/org/apache/lucene/search/FieldSortedHitQueue.java

@@ -35,7 +35,7 @@ import java.text.Collator;
  * @author  Tim Jones (Nacimiento Software)
  * @since   lucene 1.4
  * @version $Id$
- * @see Searchable#search(Query,Filter,int,Sort)
+ * @see Searcher#search(Query,Filter,int,Sort)
  * @see FieldCache
  */
 class FieldSortedHitQueue
@@ -110,7 +110,7 @@ extends PriorityQueue {
    * by a MultiSearcher with other search hits.
    * @param  doc  The FieldDoc to store sort values into.
    * @return  The same FieldDoc passed in.
-   * @see Searchable#search(Query,Filter,int,Sort)
+   * @see Searchable#search(Weight,Filter,int,Sort)
    */
   FieldDoc fillFields (final FieldDoc doc) {
     final int n = comparators.length;

src/java/org/apache/lucene/search/IndexSearcher.java

@@ -85,12 +85,6 @@ public class IndexSearcher extends Searcher {
     return reader.maxDoc();
   }
 
-  // inherit javadoc
-  public TopDocs search(Query query, Filter filter, final int nDocs)
-       throws IOException {
-    return search(query.weight(this), filter, nDocs);
-  }
-
   // inherit javadoc
   public TopDocs search(Weight weight, Filter filter, final int nDocs)
        throws IOException {
@@ -126,13 +120,6 @@ public class IndexSearcher extends Searcher {
     return new TopDocs(totalHits[0], scoreDocs);
   }
 
-  // inherit javadoc
-  public TopFieldDocs search(Query query, Filter filter, final int nDocs,
-                             Sort sort)
-    throws IOException {
-    return search(query.weight(this), filter, nDocs, sort);
-  }
-
   // inherit javadoc
   public TopFieldDocs search(Weight weight, Filter filter, final int nDocs,
                              Sort sort)
@@ -162,13 +149,6 @@ public class IndexSearcher extends Searcher {
     return new TopFieldDocs(totalHits[0], scoreDocs, hq.getFields());
   }
 
-
-  // inherit javadoc
-  public void search(Query query, Filter filter,
-                     final HitCollector results) throws IOException {
-    search(query.weight(this), filter, results);
-  }
-
   // inherit javadoc
   public void search(Weight weight, Filter filter,
                      final HitCollector results) throws IOException {
@@ -199,10 +179,6 @@ public class IndexSearcher extends Searcher {
     return query;
   }
 
-  public Explanation explain(Query query, int doc) throws IOException {
-    return explain(query.weight(this), doc);
-  }
-
   public Explanation explain(Weight weight, int doc) throws IOException {
     return weight.explain(reader, doc);
   }

src/java/org/apache/lucene/search/MultiSearcher.java

@@ -84,34 +84,18 @@ public class MultiSearcher extends Searcher {
       throw new UnsupportedOperationException();
     }
 
-    public Explanation explain(Query query,int doc) throws IOException{
-      throw new UnsupportedOperationException();
-    }
-
     public Explanation explain(Weight weight,int doc) throws IOException {
       throw new UnsupportedOperationException();
     }
 
-    public void search(Query query, Filter filter, HitCollector results) throws IOException {
-      throw new UnsupportedOperationException();
-    }
-
     public void search(Weight weight, Filter filter, HitCollector results) throws IOException {
       throw new UnsupportedOperationException();
     }
 
-    public TopDocs search(Query query,Filter filter,int n) throws IOException {
-      throw new UnsupportedOperationException();
-    }
-
     public TopDocs search(Weight weight,Filter filter,int n) throws IOException {
       throw new UnsupportedOperationException();
     }
 
-    public TopFieldDocs search(Query query,Filter filter,int n,Sort sort) throws IOException {
-      throw new UnsupportedOperationException();
-    }
-
     public TopFieldDocs search(Weight weight,Filter filter,int n,Sort sort) throws IOException {
       throw new UnsupportedOperationException();
     }
@@ -203,12 +187,6 @@ public class MultiSearcher extends Searcher {
     return maxDoc;
   }
 
-  public TopDocs search(Query query, Filter filter, int nDocs)
-      throws IOException {
-    Weight weight = prepareWeight(query);
-    return search(weight, filter, nDocs);
-  }
-
   public TopDocs search(Weight weight, Filter filter, int nDocs)
   throws IOException {
 
@@ -234,13 +212,6 @@ public class MultiSearcher extends Searcher {
     return new TopDocs(totalHits, scoreDocs);
   }
 
-
-  public TopFieldDocs search (Query query, Filter filter, int n, Sort sort)
-    throws IOException {
-    Weight weight = prepareWeight(query);
-    return search(weight, filter, n, sort);
-  }
-
   public TopFieldDocs search (Weight weight, Filter filter, int n, Sort sort)
   throws IOException {
     FieldDocSortedHitQueue hq = null;
@@ -267,13 +238,6 @@ public class MultiSearcher extends Searcher {
   }
 
 
-  // inherit javadoc
-  public void search(Query query, Filter filter, final HitCollector results)
-    throws IOException {
-      Weight weight = prepareWeight(query);
-      search(weight, filter, results);
-  }
-
   // inherit javadoc
   public void search(Weight weight, Filter filter, final HitCollector results)
     throws IOException {
@@ -298,12 +262,6 @@ public class MultiSearcher extends Searcher {
     return queries[0].combine(queries);
   }
 
-  public Explanation explain(Query query, int doc) throws IOException {
-    Weight weight = prepareWeight(query);
-    return explain(weight, doc);
-  }
-
-
   public Explanation explain(Weight weight, int doc) throws IOException {
     int i = subSearcher(doc);			  // find searcher index
     return searchables[i].explain(weight,doc-starts[i]); // dispatch to searcher
@@ -322,7 +280,7 @@ public class MultiSearcher extends Searcher {
    *
    * @return rewritten queries
    */
-  private Weight prepareWeight(Query original) throws IOException {
+  protected Weight createWeight(Query original) throws IOException {
     // step 1
     Query rewrittenQuery = rewrite(original);
 

src/java/org/apache/lucene/search/ParallelMultiSearcher.java

@@ -158,13 +158,13 @@ public class ParallelMultiSearcher extends MultiSearcher {
    * 
    * TODO: parallelize this one too
    */
-  public void search(Query query, Filter filter, final HitCollector results)
+  public void search(Weight weight, Filter filter, final HitCollector results)
     throws IOException {
     for (int i = 0; i < searchables.length; i++) {
 
       final int start = starts[i];
 
-      searchables[i].search(query, filter, new HitCollector() {
+      searchables[i].search(weight, filter, new HitCollector() {
           public void collect(int doc, float score) {
             results.collect(doc + start, score);
           }

src/java/org/apache/lucene/search/RemoteSearchable.java

@@ -39,6 +39,8 @@ public class RemoteSearchable
     this.local = local;
   }
   
+  // this implementation should be removed when the deprecated
+  // Searchable#search(Query,Filter,HitCollector) is removed
   public void search(Query query, Filter filter, HitCollector results)
     throws IOException {
     local.search(query, filter, results);
@@ -66,6 +68,8 @@ public class RemoteSearchable
     return local.maxDoc();
   }
 
+  // this implementation should be removed when the deprecated
+  // Searchable#search(Query,Filter,int) is removed
   public TopDocs search(Query query, Filter filter, int n) throws IOException {
     return local.search(query, filter, n);
   }
@@ -74,6 +78,8 @@ public class RemoteSearchable
     return local.search(weight, filter, n);
   }
 
+  // this implementation should be removed when the deprecated
+  // Searchable#search(Query,Filter,int,Sort) is removed
   public TopFieldDocs search (Query query, Filter filter, int n, Sort sort)
     throws IOException {
     return local.search (query, filter, n, sort);
@@ -92,6 +98,8 @@ public class RemoteSearchable
     return local.rewrite(original);
   }
 
+  // this implementation should be removed when the deprecated
+  // Searchable#explain(Query,int) is removed
   public Explanation explain(Query query, int doc) throws IOException {
     return local.explain(query, doc);
   }

src/java/org/apache/lucene/search/Searchable.java

@@ -44,23 +44,20 @@ public interface Searchable extends java.rmi.Remote {
    * Searcher#search(Query)}) is usually more efficient, as it skips
    * non-high-scoring hits.
    *
-   * @param query to match documents
+   * @param weight to match documents
    * @param filter if non-null, a bitset used to eliminate some documents
    * @param results to receive hits
    * @throws BooleanQuery.TooManyClauses
-   *
-   * @deprecated
-   */
-  void search(Query query, Filter filter, HitCollector results)
-    throws IOException;
-
-  /** Expert: Low-level search implementation.
-   * Identical to {@link #search(Query, Filter, HitCollector)}, but takes
-   * a Weight instead of a query.
    */
   void search(Weight weight, Filter filter, HitCollector results)
   throws IOException;
 
+  /** Expert: Low-level search implementation.
+   * @deprecated use {@link Searcher#search(Query, Filter, HitCollector)} instead.
+   */
+  void search(Query query, Filter filter, HitCollector results)
+    throws IOException;
+
   /** Frees resources associated with this Searcher.
    * Be careful not to call this method while you are still using objects
    * like {@link Hits}.
@@ -93,17 +90,14 @@ public interface Searchable extends java.rmi.Remote {
    * <p>Applications should usually call {@link Searcher#search(Query)} or
    * {@link Searcher#search(Query,Filter)} instead.
    * @throws BooleanQuery.TooManyClauses
-   *
-   * @deprecated
-   */
-  TopDocs search(Query query, Filter filter, int n) throws IOException;
-
-  /** Expert: Low-level search implementation.
-   * Identical to {@link #search(Query, Filter, int)}, but takes
-   * a Weight instead of a query.
    */
   TopDocs search(Weight weight, Filter filter, int n) throws IOException;
 
+  /** Expert: Low-level search implementation.
+   * @deprecated use {@link Searcher#search(Query, Filter, int)} instead.
+   */
+  TopDocs search(Query query, Filter filter, int n) throws IOException;
+
   /** Expert: Returns the stored fields of document <code>i</code>.
    * Called by {@link HitCollector} implementations.
    * @see IndexReader#document(int)
@@ -115,22 +109,23 @@ public interface Searchable extends java.rmi.Remote {
    */
   Query rewrite(Query query) throws IOException;
 
-  /** Returns an Explanation that describes how <code>doc</code> scored against
+  /** Expert: low-level implementation method
-   * <code>query</code>.
+   * Returns an Explanation that describes how <code>doc</code> scored against
+   * <code>weight</code>.
    *
    * <p>This is intended to be used in developing Similarity implementations,
    * and, for good performance, should not be displayed with every hit.
    * Computing an explanation is as expensive as executing the query over the
    * entire index.
+   * <p>Applications should call {@link Searcher#explain(Query, int)}.
    * @throws BooleanQuery.TooManyClauses
    */
-  Explanation explain(Query query, int doc) throws IOException;
+  Explanation explain(Weight weight, int doc) throws IOException;
 
   /**
-   * Identical to {@link #search(Query, Filter, HitCollector)}, but takes
+   * @deprecated use {@link Searcher#explain(Query, int)} instead.
-   * a Weight instead of a query.
    */
-  Explanation explain(Weight weight, int doc) throws IOException;
+  Explanation explain(Query query, int doc) throws IOException;
 
   /** Expert: Low-level search implementation with arbitrary sorting.  Finds
    * the top <code>n</code> hits for <code>query</code>, applying
@@ -140,16 +135,13 @@ public interface Searchable extends java.rmi.Remote {
    * <p>Applications should usually call {@link
    * Searcher#search(Query,Filter,Sort)} instead.
    * @throws BooleanQuery.TooManyClauses
-   *
-   * @deprecated
-   */
-  TopFieldDocs search(Query query, Filter filter, int n, Sort sort)
-    throws IOException;
-
-  /** Expert: Low-level search implementation.
-   * Identical to {@link #search(Query, Filter, int, Sort)}, but takes
-   * a Weight instead of a query.
    */
   TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
   throws IOException;
+
+  /** Expert: Low-level search implementation.
+   * @deprecated use {@link Searcher#search(Query, Filter, int, Sort)} instead.
+   */
+  TopFieldDocs search(Query query, Filter filter, int n, Sort sort)
+    throws IOException;
 }

src/java/org/apache/lucene/search/Searcher.java

@@ -58,6 +58,20 @@ public abstract class Searcher implements Searchable {
     return new Hits(this, query, filter, sort);
   }
 
+  /** Expert: Low-level search implementation with arbitrary sorting.  Finds
+   * the top <code>n</code> hits for <code>query</code>, applying
+   * <code>filter</code> if non-null, and sorting the hits by the criteria in
+   * <code>sort</code>.
+   *
+   * <p>Applications should usually call {@link
+   * Searcher#search(Query,Filter,Sort)} instead.
+   * @throws BooleanQuery.TooManyClauses
+   */
+  public TopFieldDocs search(Query query, Filter filter, int n,
+                                      Sort sort) throws IOException {
+    return search(createWeight(query), filter, n, sort);
+  }
+
   /** Lower-level search API.
    *
    * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
@@ -77,6 +91,53 @@ public abstract class Searcher implements Searchable {
     search(query, (Filter)null, results);
   }    
 
+  /** Lower-level search API.
+   *
+   * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
+   * scoring document.
+   * <br>HitCollector-based access to remote indexes is discouraged.
+   *
+   * <p>Applications should only use this if they need <i>all</i> of the
+   * matching documents.  The high-level search API ({@link
+   * Searcher#search(Query)}) is usually more efficient, as it skips
+   * non-high-scoring hits.
+   *
+   * @param query to match documents
+   * @param filter if non-null, a bitset used to eliminate some documents
+   * @param results to receive hits
+   * @throws BooleanQuery.TooManyClauses
+   */
+  public void search(Query query, Filter filter, HitCollector results)
+    throws IOException {
+    search(createWeight(query), filter, results);
+  }
+
+  /** Expert: Low-level search implementation.  Finds the top <code>n</code>
+   * hits for <code>query</code>, applying <code>filter</code> if non-null.
+   *
+   * <p>Called by {@link Hits}.
+   *
+   * <p>Applications should usually call {@link Searcher#search(Query)} or
+   * {@link Searcher#search(Query,Filter)} instead.
+   * @throws BooleanQuery.TooManyClauses
+   */
+  public TopDocs search(Query query, Filter filter, int n)
+    throws IOException {
+    return search(createWeight(query), filter, n);
+  }
+
+  /** Returns an Explanation that describes how <code>doc</code> scored against
+   * <code>query</code>.
+   *
+   * <p>This is intended to be used in developing Similarity implementations,
+   * and, for good performance, should not be displayed with every hit.
+   * Computing an explanation is as expensive as executing the query over the
+   * entire index.
+   */
+  public Explanation explain(Query query, int doc) throws IOException {
+    return explain(createWeight(query), doc);
+  }
+
   /** The Similarity implementation used by this searcher. */
   private Similarity similarity = Similarity.getDefault();
 
@@ -96,6 +157,13 @@ public abstract class Searcher implements Searchable {
     return this.similarity;
   }
 
+  /**
+   * creates a weight for <code>query</code>
+   * @return new weight
+   */
+  protected Weight createWeight(Query query) throws IOException {
+      return query.weight(this);
+  }
 
   // inherit javadoc
   public int[] docFreqs(Term[] terms) throws IOException {
@@ -105,5 +173,4 @@ public abstract class Searcher implements Searchable {
     }
     return result;
   }
-
 }

src/java/org/apache/lucene/search/TopFieldDocs.java

@@ -25,7 +25,7 @@ package org.apache.lucene.search;
  * @author  Tim Jones (Nacimiento Software)
  * @since   lucene 1.4
  * @version $Id$
- * @see Searchable#search(Query,Filter,int,Sort)
+ * @see Searcher#search(Query,Filter,int,Sort)
  */
 public class TopFieldDocs
 extends TopDocs {

src/test/org/apache/lucene/search/TestSort.java

@@ -344,12 +344,8 @@ implements Serializable {
 		HashMap scoresA = getScores (full.search (queryA));
 
 		// we'll test searching locally, remote and multi
-		// note: the multi test depends on each separate index containing
-		// the same documents as our local index, so the computed normalization
-		// will be the same.  so we make a multi searcher over two equal document
-		// sets - not realistic, but necessary for testing.
 		MultiSearcher remote = new MultiSearcher (new Searchable[] { getRemote() });
-		MultiSearcher multi  = new MultiSearcher (new Searchable[] { full, full });
+		MultiSearcher multi  = new MultiSearcher (new Searchable[] { searchX, searchY });
 
 		// change sorting and make sure relevancy stays the same