From f702e9596d047f69a99b22d1d1e66af8fd27d200 Mon Sep 17 00:00:00 2001 From: Michael Busch Date: Wed, 7 Oct 2009 18:32:47 +0000 Subject: [PATCH] LUCENE-1856: Remove classes Hit, HitIterator, Hits and some javadoc references git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@822825 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/lucene/document/AbstractField.java | 2 +- .../org/apache/lucene/document/Fieldable.java | 2 +- src/java/org/apache/lucene/search/Hit.java | 132 --------- .../org/apache/lucene/search/HitIterator.java | 79 ----- src/java/org/apache/lucene/search/Hits.java | 276 ------------------ .../apache/lucene/search/IndexSearcher.java | 3 - .../org/apache/lucene/search/Searchable.java | 2 +- .../org/apache/lucene/search/TopDocs.java | 1 - 8 files changed, 3 insertions(+), 494 deletions(-) delete mode 100644 src/java/org/apache/lucene/search/Hit.java delete mode 100644 src/java/org/apache/lucene/search/HitIterator.java delete mode 100644 src/java/org/apache/lucene/search/Hits.java diff --git a/src/java/org/apache/lucene/document/AbstractField.java b/src/java/org/apache/lucene/document/AbstractField.java index 15b5d95dd3b..3f49ddb2866 100755 --- a/src/java/org/apache/lucene/document/AbstractField.java +++ b/src/java/org/apache/lucene/document/AbstractField.java @@ -130,7 +130,7 @@ public abstract class AbstractField implements Fieldable { * *

Note: this value is not stored directly with the document in the index. * Documents returned from {@link org.apache.lucene.index.IndexReader#document(int)} and - * {@link org.apache.lucene.search.Hits#doc(int)} may thus not have the same value present as when + * {@link org.apache.lucene.search.Searcher#doc(int)} may thus not have the same value present as when * this field was indexed. * * @see #setBoost(float) diff --git a/src/java/org/apache/lucene/document/Fieldable.java b/src/java/org/apache/lucene/document/Fieldable.java index b8770a03a9a..7e67fffab94 100755 --- a/src/java/org/apache/lucene/document/Fieldable.java +++ b/src/java/org/apache/lucene/document/Fieldable.java @@ -62,7 +62,7 @@ public interface Fieldable extends Serializable { * *

Note: this value is not stored directly with the document in the index. * Documents returned from {@link org.apache.lucene.index.IndexReader#document(int)} and - * {@link org.apache.lucene.search.Hits#doc(int)} may thus not have the same value present as when + * {@link org.apache.lucene.search.Searcher#doc(int)} may thus not have the same value present as when * this field was indexed. * * @see #setBoost(float) diff --git a/src/java/org/apache/lucene/search/Hit.java b/src/java/org/apache/lucene/search/Hit.java deleted file mode 100644 index 53da4ea32a8..00000000000 --- a/src/java/org/apache/lucene/search/Hit.java +++ /dev/null @@ -1,132 +0,0 @@ -/** - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package org.apache.lucene.search; - -import java.io.IOException; - -import org.apache.lucene.document.Document; -import org.apache.lucene.index.CorruptIndexException; - -/** - * Wrapper used by {@link HitIterator} to provide a lazily loaded hit - * from {@link Hits}. - * - * @deprecated Use {@link TopScoreDocCollector} and {@link TopDocs} instead. Hits will be removed in Lucene 3.0. - */ -public class Hit implements java.io.Serializable { - - private Document doc = null; - - private boolean resolved = false; - - private Hits hits = null; - private int hitNumber; - - /** - * Constructed from {@link HitIterator} - * @param hits Hits returned from a search - * @param hitNumber Hit index in Hits - */ - Hit(Hits hits, int hitNumber) { - this.hits = hits; - this.hitNumber = hitNumber; - } - - /** - * Returns document for this hit. - * - * @see Hits#doc(int) - * @throws CorruptIndexException if the index is corrupt - * @throws IOException if there is a low-level IO error - */ - public Document getDocument() throws CorruptIndexException, IOException { - if (!resolved) fetchTheHit(); - return doc; - } - - /** - * Returns score for this hit. - * - * @see Hits#score(int) - */ - public float getScore() throws IOException { - return hits.score(hitNumber); - } - - /** - * Returns id for this hit. - * - * @see Hits#id(int) - */ - public int getId() throws IOException { - return hits.id(hitNumber); - } - - private void fetchTheHit() throws CorruptIndexException, IOException { - doc = hits.doc(hitNumber); - resolved = true; - } - - // provide some of the Document style interface (the simple stuff) - - /** - * Returns the boost factor for this hit on any field of the underlying document. - * - * @see Document#getBoost() - * @throws CorruptIndexException if the index is corrupt - * @throws IOException if there is a low-level IO error - */ - public float getBoost() throws CorruptIndexException, IOException { - return getDocument().getBoost(); - } - - /** - * Returns the string value of the field with the given name if any exist in - * this document, or null. If multiple fields exist with this name, this - * method returns the first value added. If only binary fields with this name - * exist, returns null. - * - * @see Document#get(String) - * @throws CorruptIndexException if the index is corrupt - * @throws IOException if there is a low-level IO error - */ - public String get(String name) throws CorruptIndexException, IOException { - return getDocument().get(name); - } - - /** - * Prints the parameters to be used to discover the promised result. - */ - public String toString() { - StringBuilder buffer = new StringBuilder(); - buffer.append("Hit<"); - buffer.append(hits.toString()); - buffer.append(" ["); - buffer.append(hitNumber); - buffer.append("] "); - if (resolved) { - buffer.append("resolved"); - } else { - buffer.append("unresolved"); - } - buffer.append(">"); - return buffer.toString(); - } - - -} diff --git a/src/java/org/apache/lucene/search/HitIterator.java b/src/java/org/apache/lucene/search/HitIterator.java deleted file mode 100644 index 9fb8b4b65c1..00000000000 --- a/src/java/org/apache/lucene/search/HitIterator.java +++ /dev/null @@ -1,79 +0,0 @@ -/** - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package org.apache.lucene.search; - -import java.util.Iterator; -import java.util.NoSuchElementException; - -/** - * An iterator over {@link Hits} that provides lazy fetching of each document. - * {@link Hits#iterator()} returns an instance of this class. Calls to {@link #next()} - * return a {@link Hit} instance. - * - * @deprecated Use {@link TopScoreDocCollector} and {@link TopDocs} instead. Hits will be removed in Lucene 3.0. - */ -public class HitIterator implements Iterator { - private Hits hits; - private int hitNumber = 0; - - /** - * Constructed from {@link Hits#iterator()}. - */ - HitIterator(Hits hits) { - this.hits = hits; - } - - /** - * @return true if current hit is less than the total number of {@link Hits}. - */ - public boolean hasNext() { - return hitNumber < hits.length(); - } - - /** - * Returns a {@link Hit} instance representing the next hit in {@link Hits}. - * - * @return Next {@link Hit}. - */ - public Object next() { - if (hitNumber == hits.length()) - throw new NoSuchElementException(); - - Object next = new Hit(hits, hitNumber); - hitNumber++; - return next; - } - - /** - * Unsupported operation. - * - * @throws UnsupportedOperationException - */ - public void remove() { - throw new UnsupportedOperationException(); - } - - /** - * Returns the total number of hits. - */ - public int length() { - return hits.length(); - } -} - - diff --git a/src/java/org/apache/lucene/search/Hits.java b/src/java/org/apache/lucene/search/Hits.java deleted file mode 100644 index dd23904285c..00000000000 --- a/src/java/org/apache/lucene/search/Hits.java +++ /dev/null @@ -1,276 +0,0 @@ -package org.apache.lucene.search; - -/** - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import java.io.IOException; -import java.util.ConcurrentModificationException; -import java.util.Iterator; -import java.util.Vector; - -import org.apache.lucene.document.Document; -import org.apache.lucene.index.CorruptIndexException; - -/** A ranked list of documents, used to hold search results. - *

- * Caution: Iterate only over the hits needed. Iterating over all - * hits is generally not desirable and may be the source of - * performance issues. If you need to iterate over many or all hits, consider - * using the search method that takes a {@link HitCollector}. - *

- *

Note: Deleting matching documents concurrently with traversing - * the hits, might, when deleting hits that were not yet retrieved, decrease - * {@link #length()}. In such case, - * {@link java.util.ConcurrentModificationException ConcurrentModificationException} - * is thrown when accessing hit n ≥ current_{@link #length()} - * (but n < {@link #length()}_at_start). - * - * @deprecated - * see {@link TopScoreDocCollector} and {@link TopDocs} :
- * 

- *   TopScoreDocCollector collector = new TopScoreDocCollector(hitsPerPage);
- *   searcher.search(query, collector);
- *   ScoreDoc[] hits = collector.topDocs().scoreDocs;
- *   for (int i = 0; i < hits.length; i++) {
- *     int docId = hits[i].doc;
- *     Document d = searcher.doc(docId);
- *     // do something with current hit
- *     ...
- *
- */ -public final class Hits { - private Weight weight; - private Searcher searcher; - private Filter filter = null; - private Sort sort = null; - - private int length; // the total number of hits - private Vector hitDocs = new Vector(); // cache of hits retrieved - - private HitDoc first; // head of LRU cache - private HitDoc last; // tail of LRU cache - private int numDocs = 0; // number cached - private int maxDocs = 200; // max to cache - - private int nDeletions; // # deleted docs in the index. - private int lengthAtStart; // this is the number apps usually count on (although deletions can bring it down). - private int nDeletedHits = 0; // # of already collected hits that were meanwhile deleted. - - boolean debugCheckedForDeletions = false; // for test purposes. - - Hits(Searcher s, Query q, Filter f) throws IOException { - weight = q.weight(s); - searcher = s; - filter = f; - nDeletions = countDeletions(s); - getMoreDocs(50); // retrieve 100 initially - lengthAtStart = length; - } - - Hits(Searcher s, Query q, Filter f, Sort o) throws IOException { - weight = q.weight(s); - searcher = s; - filter = f; - sort = o; - nDeletions = countDeletions(s); - getMoreDocs(50); // retrieve 100 initially - lengthAtStart = length; - } - - // count # deletions, return -1 if unknown. - private int countDeletions(Searcher s) throws IOException { - int cnt = -1; - if (s instanceof IndexSearcher) { - cnt = s.maxDoc() - ((IndexSearcher) s).getIndexReader().numDocs(); - } - return cnt; - } - - /** - * Tries to add new documents to hitDocs. - * Ensures that the hit numbered min has been retrieved. - */ - private final void getMoreDocs(int min) throws IOException { - if (hitDocs.size() > min) { - min = hitDocs.size(); - } - - int n = min * 2; // double # retrieved - TopDocs topDocs = (sort == null) ? searcher.search(weight, filter, n) : searcher.search(weight, filter, n, sort); - - length = topDocs.totalHits; - ScoreDoc[] scoreDocs = topDocs.scoreDocs; - - float scoreNorm = 1.0f; - - if (length > 0 && topDocs.getMaxScore() > 1.0f) { - scoreNorm = 1.0f / topDocs.getMaxScore(); - } - - int start = hitDocs.size() - nDeletedHits; - - // any new deletions? - int nDels2 = countDeletions(searcher); - debugCheckedForDeletions = false; - if (nDeletions < 0 || nDels2 > nDeletions) { - // either we cannot count deletions, or some "previously valid hits" might have been deleted, so find exact start point - nDeletedHits = 0; - debugCheckedForDeletions = true; - int i2 = 0; - for (int i1=0; i1th document in this set. - *

Documents are cached, so that repeated requests for the same element may - * return the same Document object. - * @throws CorruptIndexException if the index is corrupt - * @throws IOException if there is a low-level IO error - */ - public final Document doc(int n) throws CorruptIndexException, IOException { - HitDoc hitDoc = hitDoc(n); - - // Update LRU cache of documents - remove(hitDoc); // remove from list, if there - addToFront(hitDoc); // add to front of list - if (numDocs > maxDocs) { // if cache is full - HitDoc oldLast = last; - remove(last); // flush last - oldLast.doc = null; // let doc get gc'd - } - - if (hitDoc.doc == null) { - hitDoc.doc = searcher.doc(hitDoc.id); // cache miss: read document - } - - return hitDoc.doc; - } - - /** Returns the score for the nth document in this set. */ - public final float score(int n) throws IOException { - return hitDoc(n).score; - } - - /** Returns the id for the nth document in this set. - * Note that ids may change when the index changes, so you cannot - * rely on the id to be stable. - */ - public final int id(int n) throws IOException { - return hitDoc(n).id; - } - - /** - * Returns a {@link HitIterator} to navigate the Hits. Each item returned - * from {@link Iterator#next()} is a {@link Hit}. - *

- * Caution: Iterate only over the hits needed. Iterating over all - * hits is generally not desirable and may be the source of - * performance issues. If you need to iterate over many or all hits, consider - * using a search method that takes a {@link HitCollector}. - *

- */ - public Iterator iterator() { - return new HitIterator(this); - } - - private final HitDoc hitDoc(int n) throws IOException { - if (n >= lengthAtStart) { - throw new IndexOutOfBoundsException("Not a valid hit number: " + n); - } - - if (n >= hitDocs.size()) { - getMoreDocs(n); - } - - if (n >= length) { - throw new ConcurrentModificationException("Not a valid hit number: " + n); - } - - return (HitDoc) hitDocs.elementAt(n); - } - - private final void addToFront(HitDoc hitDoc) { // insert at front of cache - if (first == null) { - last = hitDoc; - } else { - first.prev = hitDoc; - } - - hitDoc.next = first; - first = hitDoc; - hitDoc.prev = null; - - numDocs++; - } - - private final void remove(HitDoc hitDoc) { // remove from cache - if (hitDoc.doc == null) { // it's not in the list - return; // abort - } - - if (hitDoc.next == null) { - last = hitDoc.prev; - } else { - hitDoc.next.prev = hitDoc.prev; - } - - if (hitDoc.prev == null) { - first = hitDoc.next; - } else { - hitDoc.prev.next = hitDoc.next; - } - - numDocs--; - } -} - -final class HitDoc { - float score; - int id; - Document doc = null; - - HitDoc next; // in doubly-linked cache - HitDoc prev; // in doubly-linked cache - - HitDoc(float s, int i) { - score = s; - id = i; - } -} diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java index c1c5aa374f7..3d0428e8d40 100644 --- a/src/java/org/apache/lucene/search/IndexSearcher.java +++ b/src/java/org/apache/lucene/search/IndexSearcher.java @@ -36,9 +36,6 @@ import org.apache.lucene.util.ReaderUtil; * or {@link #search(Query,Filter,int)} methods. For performance reasons it is * recommended to open only one IndexSearcher and use it for all of your searches. * - *

Note that you can only access the deprecated {@link Hits} from an IndexSearcher as long as it is - * not yet closed, otherwise an IOException will be thrown. - * *

NOTE: {@link * IndexSearcher} instances are completely * thread safe, meaning multiple threads can call any of its diff --git a/src/java/org/apache/lucene/search/Searchable.java b/src/java/org/apache/lucene/search/Searchable.java index 3f984f37df9..1f5173201ce 100644 --- a/src/java/org/apache/lucene/search/Searchable.java +++ b/src/java/org/apache/lucene/search/Searchable.java @@ -87,7 +87,7 @@ public interface Searchable { /** Frees resources associated with this Searcher. * Be careful not to call this method while you are still using objects - * like {@link Hits}. + * that reference this Searchable. */ void close() throws IOException; diff --git a/src/java/org/apache/lucene/search/TopDocs.java b/src/java/org/apache/lucene/search/TopDocs.java index d1c1f03a47f..7e53662c1d1 100644 --- a/src/java/org/apache/lucene/search/TopDocs.java +++ b/src/java/org/apache/lucene/search/TopDocs.java @@ -21,7 +21,6 @@ package org.apache.lucene.search; * @see Searcher#search(Query,Filter,int) */ public class TopDocs implements java.io.Serializable { /** Expert: The total number of hits for the query. - * @see Hits#length() */ public int totalHits; /** Expert: The top hits for the query. */