Yes, this is better: +1 Otis
--- Doug Cutting <[EMAIL PROTECTED]> wrote: > [EMAIL PROTECTED] wrote: > > 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
