http://issues.apache.org/bugzilla/show_bug.cgi?id=31841
[EMAIL PROTECTED] changed:
What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |RESOLVED Resolution| |FIXED
When we deprecate things we should ensure:
1. That, if they're removed, everything else should keep working.
2. That they should indicate what should be used instead.
In Searchable.java we now have methods whose javadoc refers to deprecated methods, which will be a problem if those deprecated methods are removed. These deprecated search methods also do not indicate what folks should call instead. In each case applications should call a corresponding Searcher method. But these Searcher methods do not yet exist, instead we only have implementations of the deprecated interface methods on Searcher subclasses. So we need abstract methods on Searcher. These methods should never be called on RemoteSearchable, since it should always be passed a Weight, and never a Query, and thus the RemoteSearchable implementations should be removed when the deprecated interface methods are removed.
I've attached a patch that implements this.
Objections?
Doug
Index: src/java/org/apache/lucene/search/RemoteSearchable.java
===================================================================
--- src/java/org/apache/lucene/search/RemoteSearchable.java (revision 162053)
+++ src/java/org/apache/lucene/search/RemoteSearchable.java (working copy)
@@ -39,6 +39,8 @@
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 @@
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 @@
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);
Index: src/java/org/apache/lucene/search/Searcher.java
===================================================================
--- src/java/org/apache/lucene/search/Searcher.java (revision 162053)
+++ src/java/org/apache/lucene/search/Searcher.java (working copy)
@@ -58,6 +58,18 @@
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 [EMAIL PROTECTED]
+ * Searcher#search(Query,Filter,Sort)} instead.
+ * @throws BooleanQuery.TooManyClauses
+ */
+ public abstract TopFieldDocs search(Query query, Filter filter, int n,
+ Sort sort) throws IOException;
+
/** Lower-level search API.
*
* <p>[EMAIL PROTECTED] HitCollector#collect(int,float)} is called for every non-zero
@@ -77,6 +89,37 @@
search(query, (Filter)null, results);
}
+ /** Lower-level search API.
+ *
+ * <p>[EMAIL PROTECTED] 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 ([EMAIL PROTECTED]
+ * 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 abstract void search(Query query, Filter filter, HitCollector results)
+ throws IOException;
+
+ /** 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 [EMAIL PROTECTED] Hits}.
+ *
+ * <p>Applications should usually call [EMAIL PROTECTED] Searcher#search(Query)} or
+ * [EMAIL PROTECTED] Searcher#search(Query,Filter)} instead.
+ * @throws BooleanQuery.TooManyClauses
+ */
+ public abstract TopDocs search(Query query, Filter filter, int n)
+ throws IOException;
+
/** The Similarity implementation used by this searcher. */
private Similarity similarity = Similarity.getDefault();
Index: src/java/org/apache/lucene/search/Searchable.java
===================================================================
--- src/java/org/apache/lucene/search/Searchable.java (revision 162053)
+++ src/java/org/apache/lucene/search/Searchable.java (working copy)
@@ -49,14 +49,14 @@
* @param results to receive hits
* @throws BooleanQuery.TooManyClauses
*
- * @deprecated
+ * @deprecated use [EMAIL PROTECTED] Searcher#search(Query, Filter, HitCollector)}.
*/
void search(Query query, Filter filter, HitCollector results)
throws IOException;
/** Expert: Low-level search implementation.
- * Identical to [EMAIL PROTECTED] #search(Query, Filter, HitCollector)}, but takes
- * a Weight instead of a query.
+ * Applications should use [EMAIL PROTECTED] Searcher#search(Query,
+ * Filter, HitCollector)} intstead.
*/
void search(Weight weight, Filter filter, HitCollector results)
throws IOException;
@@ -94,13 +94,13 @@
* [EMAIL PROTECTED] Searcher#search(Query,Filter)} instead.
* @throws BooleanQuery.TooManyClauses
*
- * @deprecated
+ * @deprecated use [EMAIL PROTECTED] Searcher#search(Query, Filter, int)}.
*/
TopDocs search(Query query, Filter filter, int n) throws IOException;
/** Expert: Low-level search implementation.
- * Identical to [EMAIL PROTECTED] #search(Query, Filter, int)}, but takes
- * a Weight instead of a query.
+ * Applications should use [EMAIL PROTECTED] Searcher#search(Query,
+ * Filter, int)} intstead.
*/
TopDocs search(Weight weight, Filter filter, int n) throws IOException;
@@ -141,14 +141,13 @@
* Searcher#search(Query,Filter,Sort)} instead.
* @throws BooleanQuery.TooManyClauses
*
- * @deprecated
+ * @deprecated use [EMAIL PROTECTED] Searcher#search(Query, Filter, int, Sort)}.
*/
TopFieldDocs search(Query query, Filter filter, int n, Sort sort)
throws IOException;
/** Expert: Low-level search implementation.
- * Identical to [EMAIL PROTECTED] #search(Query, Filter, int, Sort)}, but takes
- * a Weight instead of a query.
+ * Applications should use [EMAIL PROTECTED] Searcher#search(Query, Filter, int, Sort)}.
*/
TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
throws IOException;--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
