You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by us...@apache.org on 2012/01/30 23:05:31 UTC
svn commit: r1238034 - in
/lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index:
AtomicReader.java CompositeReader.java DirectoryReader.java IndexReader.java
Author: uschindler
Date: Mon Jan 30 22:05:30 2012
New Revision: 1238034
URL: http://svn.apache.org/viewvc?rev=1238034&view=rev
Log:
LUCENE-2858: Add missing Javadocs for the new base classes. I think it's ready!
Modified:
lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/AtomicReader.java
lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/CompositeReader.java
lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/DirectoryReader.java
lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/IndexReader.java
Modified: lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/AtomicReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/AtomicReader.java?rev=1238034&r1=1238033&r2=1238034&view=diff
==============================================================================
--- lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/AtomicReader.java (original)
+++ lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/AtomicReader.java Mon Jan 30 22:05:30 2012
@@ -25,30 +25,20 @@ import org.apache.lucene.util.Bits;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.ReaderUtil; // for javadocs
-/** IndexReader is an abstract class, providing an interface for accessing an
+/** {@code AtomicReader} is an abstract class, providing an interface for accessing an
index. Search of an index is done entirely through this abstract interface,
- so that any subclass which implements it is searchable.
+ so that any subclass which implements it is searchable. IndexReaders implemented
+ by this subclass do not consist of several sub-readers,
+ they are atomic. They support retrieval of stored fields, doc values, terms,
+ and postings.
- <p> Concrete subclasses of IndexReader are usually constructed with a call to
- one of the static <code>open()</code> methods, e.g. {@link
- #open(Directory)}.
-
- <p> For efficiency, in this API documents are often referred to via
+ <p>For efficiency, in this API documents are often referred to via
<i>document numbers</i>, non-negative integers which each name a unique
- document in the index. These document numbers are ephemeral--they may change
+ document in the index. These document numbers are ephemeral -- they may change
as documents are added to and deleted from an index. Clients should thus not
rely on a given document having the same number between sessions.
<p>
- <b>NOTE</b>: for backwards API compatibility, several methods are not listed
- as abstract, but have no useful implementations in this base class and
- instead always throw UnsupportedOperationException. Subclasses are
- strongly encouraged to override these methods, but in many cases may not
- need to.
- </p>
-
- <p>
-
<a name="thread-safety"></a><p><b>NOTE</b>: {@link
IndexReader} instances are completely thread
safe, meaning multiple threads can call any of its methods,
Modified: lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/CompositeReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/CompositeReader.java?rev=1238034&r1=1238033&r2=1238034&view=diff
==============================================================================
--- lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/CompositeReader.java (original)
+++ lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/CompositeReader.java Mon Jan 30 22:05:30 2012
@@ -20,30 +20,26 @@ package org.apache.lucene.index;
import org.apache.lucene.search.SearcherManager; // javadocs
import org.apache.lucene.store.*;
-/** IndexReader is an abstract class, providing an interface for accessing an
- index. Search of an index is done entirely through this abstract interface,
- so that any subclass which implements it is searchable.
-
+/** Instances of this reader type can only
+ be used to get stored fields from the underlying AtomicReaders,
+ but it is not possible to directly retrieve postings. To do that, get
+ the sub-readers via {@link #getSequentialSubReaders}.
+
+ <p>IndexReader instances for indexes on disk are usually constructed
+ with a call to one of the static <code>DirectoryReader,open()</code> methods,
+ e.g. {@link DirectoryReader#open(Directory)}. {@link DirectoryReader} implements
+ the {@code CompositeReader} interface, it is not possible to directly get postings.
<p> Concrete subclasses of IndexReader are usually constructed with a call to
one of the static <code>open()</code> methods, e.g. {@link
#open(Directory)}.
<p> For efficiency, in this API documents are often referred to via
<i>document numbers</i>, non-negative integers which each name a unique
- document in the index. These document numbers are ephemeral--they may change
+ document in the index. These document numbers are ephemeral -- they may change
as documents are added to and deleted from an index. Clients should thus not
rely on a given document having the same number between sessions.
<p>
- <b>NOTE</b>: for backwards API compatibility, several methods are not listed
- as abstract, but have no useful implementations in this base class and
- instead always throw UnsupportedOperationException. Subclasses are
- strongly encouraged to override these methods, but in many cases may not
- need to.
- </p>
-
- <p>
-
<a name="thread-safety"></a><p><b>NOTE</b>: {@link
IndexReader} instances are completely thread
safe, meaning multiple threads can call any of its methods,
Modified: lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/DirectoryReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/DirectoryReader.java?rev=1238034&r1=1238033&r2=1238034&view=diff
==============================================================================
--- lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/DirectoryReader.java (original)
+++ lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/DirectoryReader.java Mon Jan 30 22:05:30 2012
@@ -31,10 +31,28 @@ import org.apache.lucene.store.Directory
import org.apache.lucene.store.IOContext;
import org.apache.lucene.util.IOUtils;
-/**
- * An IndexReader which reads indexes with multiple segments.
- * To get an instance of this reader use {@link #open(Directory)}.
- */
+/** DirectoryReader is an implementation of {@link CompositeReader}
+ that can read indexes in a {@link Directory}.
+
+ <p>DirectoryReader instances are usually constructed with a call to
+ one of the static <code>open()</code> methods, e.g. {@link
+ #open(Directory)}.
+
+ <p> For efficiency, in this API documents are often referred to via
+ <i>document numbers</i>, non-negative integers which each name a unique
+ document in the index. These document numbers are ephemeral -- they may change
+ as documents are added to and deleted from an index. Clients should thus not
+ rely on a given document having the same number between sessions.
+
+ <p>
+ <a name="thread-safety"></a><p><b>NOTE</b>: {@link
+ IndexReader} instances are completely thread
+ safe, meaning multiple threads can call any of its methods,
+ concurrently. If your application requires external
+ synchronization, you should <b>not</b> synchronize on the
+ <code>IndexReader</code> instance; use your own
+ (non-Lucene) objects instead.
+*/
public final class DirectoryReader extends BaseMultiReader<SegmentReader> {
static int DEFAULT_TERMS_INDEX_DIVISOR = 1;
Modified: lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/IndexReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/IndexReader.java?rev=1238034&r1=1238033&r2=1238034&view=diff
==============================================================================
--- lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/IndexReader.java (original)
+++ lucene/dev/branches/lucene2858/lucene/src/java/org/apache/lucene/index/IndexReader.java Mon Jan 30 22:05:30 2012
@@ -36,26 +36,32 @@ import org.apache.lucene.util.ReaderUtil
index. Search of an index is done entirely through this abstract interface,
so that any subclass which implements it is searchable.
- <p> Concrete subclasses of IndexReader are usually constructed with a call to
- one of the static <code>open()</code> methods, e.g. {@link
- #open(Directory)}.
+ <p>There are two different types of IndexReaders:
+ <ul>
+ <li>{@link AtomicReader}: These indexes do not consist of several sub-readers,
+ they are atomic. They support retrieval of stored fields, doc values, terms,
+ and postings.
+ <li>{@link CompositeReader}: Instances (like {@link DirectoryReader})
+ of this reader can only
+ be used to get stored fields from the underlying AtomicReaders,
+ but it is not possible to directly retrieve postings. To do that, get
+ the sub-readers via {@link CompositeReader#getSequentialSubReaders}.
+ Alternatively, you can mimic an {@link AtomicReader} (with a serious slowdown),
+ by wrapping composite readers with {@link SlowCompositeReaderWrapper}.
+ </ul>
+
+ <p>IndexReader instances for indexes on disk are usually constructed
+ with a call to one of the static <code>DirectoryReader,open()</code> methods,
+ e.g. {@link DirectoryReader#open(Directory)}. {@link DirectoryReader} implements
+ the {@link CompositeReader} interface, it is not possible to directly get postings.
<p> For efficiency, in this API documents are often referred to via
<i>document numbers</i>, non-negative integers which each name a unique
- document in the index. These document numbers are ephemeral--they may change
+ document in the index. These document numbers are ephemeral -- they may change
as documents are added to and deleted from an index. Clients should thus not
rely on a given document having the same number between sessions.
<p>
- <b>NOTE</b>: for backwards API compatibility, several methods are not listed
- as abstract, but have no useful implementations in this base class and
- instead always throw UnsupportedOperationException. Subclasses are
- strongly encouraged to override these methods, but in many cases may not
- need to.
- </p>
-
- <p>
-
<a name="thread-safety"></a><p><b>NOTE</b>: {@link
IndexReader} instances are completely thread
safe, meaning multiple threads can call any of its methods,