From 005fe165dc4b81ad4a222a2da573dcff11a63724 Mon Sep 17 00:00:00 2001 From: Robert Muir Date: Tue, 28 Aug 2012 15:44:31 +0000 Subject: [PATCH] javadocs git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1378183 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/lucene/index/DirectoryReader.java | 1 + .../org/apache/lucene/index/FieldInfo.java | 22 +++++++------- .../org/apache/lucene/index/FieldInfos.java | 19 +++++------- .../lucene/index/FilterAtomicReader.java | 26 ++++++++++++++++ .../lucene/index/FilteredTermsEnum.java | 15 +++++++++- .../apache/lucene/index/IndexFileNames.java | 4 +++ .../org/apache/lucene/index/IndexReader.java | 3 +- .../org/apache/lucene/index/IndexWriter.java | 11 +++++++ .../org/apache/lucene/index/MultiFields.java | 30 +++++++++++++++++++ .../lucene/index/SegmentInfoPerCommit.java | 17 +++++++++++ .../apache/lucene/index/SegmentReader.java | 16 +++++----- .../java/org/apache/lucene/index/Term.java | 4 --- .../org/apache/lucene/index/TermsEnum.java | 15 ++++++---- .../java/org/apache/lucene/util/IOUtils.java | 11 ++++++- 14 files changed, 152 insertions(+), 42 deletions(-) diff --git a/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java b/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java index beea8ae320a..b4c08fff6ee 100644 --- a/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java +++ b/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java @@ -51,6 +51,7 @@ import org.apache.lucene.store.Directory; public abstract class DirectoryReader extends BaseCompositeReader { public static final int DEFAULT_TERMS_INDEX_DIVISOR = 1; + /** The index directory. */ protected final Directory directory; /** Returns a IndexReader reading the index in the given diff --git a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java index 8161d8a7dcb..7e6247b189e 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java +++ b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java @@ -31,7 +31,9 @@ import org.apache.lucene.index.DocValues.Type; **/ public final class FieldInfo { + /** Field's name */ public final String name; + /** Internal field number */ public final int number; private boolean indexed; @@ -164,27 +166,27 @@ public final class FieldInfo { assert checkConsistency(); } - /** @return IndexOptions for the field, or null if the field is not indexed */ + /** Returns IndexOptions for the field, or null if the field is not indexed */ public IndexOptions getIndexOptions() { return indexOptions; } /** - * @return true if this field has any docValues. + * Returns true if this field has any docValues. */ public boolean hasDocValues() { return docValueType != null; } /** - * @return {@link DocValues.Type} of the docValues. this may be null if the field has no docvalues. + * Returns {@link DocValues.Type} of the docValues. this may be null if the field has no docvalues. */ public DocValues.Type getDocValuesType() { return docValueType; } /** - * @return {@link DocValues.Type} of the norm. this may be null if the field has no norms. + * Returns {@link DocValues.Type} of the norm. this may be null if the field has no norms. */ public DocValues.Type getNormType() { return normType; @@ -208,35 +210,35 @@ public final class FieldInfo { } /** - * @return true if norms are explicitly omitted for this field + * Returns true if norms are explicitly omitted for this field */ public boolean omitsNorms() { return omitNorms; } /** - * @return true if this field actually has any norms. + * Returns true if this field actually has any norms. */ public boolean hasNorms() { return normType != null; } /** - * @return true if this field is indexed. + * Returns true if this field is indexed. */ public boolean isIndexed() { return indexed; } /** - * @return true if any payloads exist for this field. + * Returns true if any payloads exist for this field. */ public boolean hasPayloads() { return storePayloads; } /** - * @return true if any term vectors exist for this field. + * Returns true if any term vectors exist for this field. */ public boolean hasVectors() { return storeTermVector; @@ -271,7 +273,7 @@ public final class FieldInfo { } /** - * @return internal codec attributes map. May be null if no mappings exist. + * Returns internal codec attributes map. May be null if no mappings exist. */ public Map attributes() { return attributes; diff --git a/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java b/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java index 4a603ca1740..33243a83c75 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java +++ b/lucene/core/src/java/org/apache/lucene/index/FieldInfos.java @@ -44,6 +44,9 @@ public class FieldInfos implements Iterable { private final HashMap byName = new HashMap(); private final Collection values; // for an unmodifiable iterator + /** + * Constructs a new FieldInfos from an array of FieldInfo objects + */ public FieldInfos(FieldInfo[] infos) { boolean hasVectors = false; boolean hasProx = false; @@ -98,30 +101,22 @@ public class FieldInfos implements Iterable { return hasOffsets; } - /** - * @return true if at least one field has any vectors - */ + /** Returns true if any fields have vectors */ public boolean hasVectors() { return hasVectors; } - /** - * @return true if at least one field has any norms - */ + /** Returns true if any fields have norms */ public boolean hasNorms() { return hasNorms; } - /** - * @return true if at least one field has doc values - */ + /** Returns true if any fields have DocValues */ public boolean hasDocValues() { return hasDocValues; } - /** - * @return number of fields - */ + /** Returns the number of fields */ public int size() { assert byNumber.size() == byName.size(); return byNumber.size(); diff --git a/lucene/core/src/java/org/apache/lucene/index/FilterAtomicReader.java b/lucene/core/src/java/org/apache/lucene/index/FilterAtomicReader.java index c2cb3a6eb9b..54edfc7d92b 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FilterAtomicReader.java +++ b/lucene/core/src/java/org/apache/lucene/index/FilterAtomicReader.java @@ -40,8 +40,13 @@ public class FilterAtomicReader extends AtomicReader { /** Base class for filtering {@link Fields} * implementations. */ public static class FilterFields extends Fields { + /** The underlying Fields instance. */ protected final Fields in; + /** + * Creates a new FilterFields. + * @param in the underlying Fields instance. + */ public FilterFields(Fields in) { this.in = in; } @@ -65,8 +70,13 @@ public class FilterAtomicReader extends AtomicReader { /** Base class for filtering {@link Terms} * implementations. */ public static class FilterTerms extends Terms { + /** The underlying Terms instance. */ protected final Terms in; + /** + * Creates a new FilterTerms + * @param in the underlying Terms instance. + */ public FilterTerms(Terms in) { this.in = in; } @@ -124,8 +134,13 @@ public class FilterAtomicReader extends AtomicReader { /** Base class for filtering {@link TermsEnum} implementations. */ public static class FilterTermsEnum extends TermsEnum { + /** The underlying TermsEnum instance. */ protected final TermsEnum in; + /** + * Creates a new FilterTermsEnum + * @param in the underlying TermsEnum instance. + */ public FilterTermsEnum(TermsEnum in) { this.in = in; } @Override @@ -201,8 +216,13 @@ public class FilterAtomicReader extends AtomicReader { /** Base class for filtering {@link DocsEnum} implementations. */ public static class FilterDocsEnum extends DocsEnum { + /** The underlying DocsEnum instance. */ protected final DocsEnum in; + /** + * Create a new FilterDocsEnum + * @param in the underlying DocsEnum instance. + */ public FilterDocsEnum(DocsEnum in) { this.in = in; } @@ -235,8 +255,13 @@ public class FilterAtomicReader extends AtomicReader { /** Base class for filtering {@link DocsAndPositionsEnum} implementations. */ public static class FilterDocsAndPositionsEnum extends DocsAndPositionsEnum { + /** The underlying DocsAndPositionsEnum instance. */ protected final DocsAndPositionsEnum in; + /** + * Create a new FilterDocsAndPositionsEnum + * @param in the underlying DocsAndPositionsEnum instance. + */ public FilterDocsAndPositionsEnum(DocsAndPositionsEnum in) { this.in = in; } @@ -287,6 +312,7 @@ public class FilterAtomicReader extends AtomicReader { } } + /** The underlying AtomicReader. */ protected final AtomicReader in; /** diff --git a/lucene/core/src/java/org/apache/lucene/index/FilteredTermsEnum.java b/lucene/core/src/java/org/apache/lucene/index/FilteredTermsEnum.java index a47c7ab68ad..0e51884dfc9 100644 --- a/lucene/core/src/java/org/apache/lucene/index/FilteredTermsEnum.java +++ b/lucene/core/src/java/org/apache/lucene/index/FilteredTermsEnum.java @@ -48,7 +48,20 @@ public abstract class FilteredTermsEnum extends TermsEnum { * the enum should call {@link #nextSeekTerm} and step forward. * @see #accept(BytesRef) */ - protected static enum AcceptStatus {YES, YES_AND_SEEK, NO, NO_AND_SEEK, END}; + protected static enum AcceptStatus { + /** Accept the term and position the enum at the next term. */ + YES, + /** Accept the term and advance ({@link FilteredTermsEnum#nextSeekTerm(BytesRef)}) + * to the next term. */ + YES_AND_SEEK, + /** Reject the term and position the enum at the next term. */ + NO, + /** Reject the term and advance ({@link FilteredTermsEnum#nextSeekTerm(BytesRef)}) + * to the next term. */ + NO_AND_SEEK, + /** Reject the term and stop enumerating. */ + END + }; /** Return if term is accepted, not accepted or the iteration should ended * (and possibly seek). diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexFileNames.java b/lucene/core/src/java/org/apache/lucene/index/IndexFileNames.java index 2201d67cf1a..b74b18c5948 100644 --- a/lucene/core/src/java/org/apache/lucene/index/IndexFileNames.java +++ b/lucene/core/src/java/org/apache/lucene/index/IndexFileNames.java @@ -187,6 +187,10 @@ public final class IndexFileNames { return filename; } + /** + * Removes the extension (anything after the first '.'), + * otherwise returns the original filename. + */ public static String stripExtension(String filename) { int idx = filename.indexOf('.'); if (idx != -1) { diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexReader.java b/lucene/core/src/java/org/apache/lucene/index/IndexReader.java index 9a41845202f..86c0e029f6b 100644 --- a/lucene/core/src/java/org/apache/lucene/index/IndexReader.java +++ b/lucene/core/src/java/org/apache/lucene/index/IndexReader.java @@ -243,7 +243,8 @@ public abstract class IndexReader implements Closeable { } /** - * @throws AlreadyClosedException if this IndexReader is closed + * Throws AlreadyClosedException if this IndexReader or any + * of its child readers is closed, otherwise returns. */ protected final void ensureOpen() throws AlreadyClosedException { if (refCount.get() <= 0) { diff --git a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java index bbfa46c1aef..8df850bc579 100644 --- a/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java +++ b/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java @@ -549,6 +549,14 @@ public class IndexWriter implements Closeable, TwoPhaseCommit { } } + /** + * Used internally to throw an {@link + * AlreadyClosedException} if this IndexWriter has been + * closed. + *

+ * Calls {@link #ensureOpen(boolean) ensureOpen(true)}. + * @throws AlreadyClosedException if this IndexWriter is closed + */ protected final void ensureOpen() throws AlreadyClosedException { ensureOpen(true); } @@ -1030,6 +1038,9 @@ public class IndexWriter implements Closeable, TwoPhaseCommit { return count; } + /** + * Returns true if this index has deletions (including buffered deletions). + */ public synchronized boolean hasDeletions() { ensureOpen(); if (bufferedDeletesStream.any()) { diff --git a/lucene/core/src/java/org/apache/lucene/index/MultiFields.java b/lucene/core/src/java/org/apache/lucene/index/MultiFields.java index 0e44b58623b..dd8fa967fcf 100644 --- a/lucene/core/src/java/org/apache/lucene/index/MultiFields.java +++ b/lucene/core/src/java/org/apache/lucene/index/MultiFields.java @@ -89,6 +89,15 @@ public final class MultiFields extends Fields { } } + /** Returns a single {@link Bits} instance for this + * reader, merging live Documents on the + * fly. This method will return null if the reader + * has no deletions. + * + *

NOTE: this is a very slow way to access live docs. + * For example, each Bits access will require a binary search. + * It's better to get the sub-readers and iterate through them + * yourself. */ public static Bits getLiveDocs(IndexReader reader) { if (reader.hasDeletions()) { final List leaves = reader.leaves(); @@ -176,6 +185,11 @@ public final class MultiFields extends Fields { return null; } + /** + * Expert: construct a new MultiFields instance directly. + * @lucene.internal + */ + // TODO: why is this public? public MultiFields(Fields[] subs, ReaderSlice[] subSlices) { this.subs = subs; this.subSlices = subSlices; @@ -229,6 +243,14 @@ public final class MultiFields extends Fields { return -1; } + /** Returns the total number of occurrences of this term + * across all documents (the sum of the freq() for each + * doc that has this term). This will be -1 if the + * codec doesn't support this measure. Note that, like + * other term measures, this measure does not take + * deleted documents into account. + * @see TermsEnum#totalTermFreq() + */ public static long totalTermFreq(IndexReader r, String field, BytesRef text) throws IOException { final Terms terms = getTerms(r, field); if (terms != null) { @@ -256,6 +278,14 @@ public final class MultiFields extends Fields { return builder.finish(); } + /** Call this to get the (merged) FieldInfos representing the + * set of indexed fields only for a composite reader. + *

+ * NOTE: the returned field numbers will likely not + * correspond to the actual field numbers in the underlying + * readers, and codec metadata ({@link FieldInfo#getAttribute(String)} + * will be unavailable. + */ public static Collection getIndexedFields(IndexReader reader) { final Collection fields = new HashSet(); for(final FieldInfo fieldInfo : getMergedFieldInfos(reader)) { diff --git a/lucene/core/src/java/org/apache/lucene/index/SegmentInfoPerCommit.java b/lucene/core/src/java/org/apache/lucene/index/SegmentInfoPerCommit.java index 60c2bcf4d94..26959dc8bea 100644 --- a/lucene/core/src/java/org/apache/lucene/index/SegmentInfoPerCommit.java +++ b/lucene/core/src/java/org/apache/lucene/index/SegmentInfoPerCommit.java @@ -97,15 +97,25 @@ public class SegmentInfoPerCommit { sizeInBytes = -1; } + /** + * Sets the generation number of the live docs file. + * @see #getDelGen() + */ public void setDelGen(long delGen) { this.delGen = delGen; sizeInBytes = -1; } + /** Returns true if there are any deletions for the + * segment at this commit. */ public boolean hasDeletions() { return delGen != -1; } + /** + * Returns the next available generation number + * of the live docs file. + */ public long getNextDelGen() { if (delGen == -1) { return 1; @@ -114,10 +124,17 @@ public class SegmentInfoPerCommit { } } + /** + * Returns generation number of the live docs file + * or -1 if there are no deletes yet. + */ public long getDelGen() { return delGen; } + /** + * Returns the number of deleted docs in the segment. + */ public int getDelCount() { return delCount; } diff --git a/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java b/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java index a6076ca1f01..b8464681b91 100644 --- a/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java +++ b/lucene/core/src/java/org/apache/lucene/index/SegmentReader.java @@ -47,9 +47,11 @@ public final class SegmentReader extends AtomicReader { final SegmentCoreReaders core; /** + * Constructs a new SegmentReader with a new core. * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ + // TODO: why is this public? public SegmentReader(SegmentInfoPerCommit si, int termInfosIndexDivisor, IOContext context) throws IOException { this.si = si; core = new SegmentCoreReaders(this, si.info.dir, si, context, termInfosIndexDivisor); @@ -76,19 +78,19 @@ public final class SegmentReader extends AtomicReader { } } - // Create new SegmentReader sharing core from a previous - // SegmentReader and loading new live docs from a new - // deletes file. Used by openIfChanged. + /** Create new SegmentReader sharing core from a previous + * SegmentReader and loading new live docs from a new + * deletes file. Used by openIfChanged. */ SegmentReader(SegmentInfoPerCommit si, SegmentCoreReaders core, IOContext context) throws IOException { this(si, core, si.info.getCodec().liveDocsFormat().readLiveDocs(si.info.dir, si, context), si.info.getDocCount() - si.getDelCount()); } - // Create new SegmentReader sharing core from a previous - // SegmentReader and using the provided in-memory - // liveDocs. Used by IndexWriter to provide a new NRT - // reader: + /** Create new SegmentReader sharing core from a previous + * SegmentReader and using the provided in-memory + * liveDocs. Used by IndexWriter to provide a new NRT + * reader */ SegmentReader(SegmentInfoPerCommit si, SegmentCoreReaders core, Bits liveDocs, int numDocs) { this.si = si; this.core = core; diff --git a/lucene/core/src/java/org/apache/lucene/index/Term.java b/lucene/core/src/java/org/apache/lucene/index/Term.java index 62cecaba4ed..a2efbcfaac1 100644 --- a/lucene/core/src/java/org/apache/lucene/index/Term.java +++ b/lucene/core/src/java/org/apache/lucene/index/Term.java @@ -132,8 +132,4 @@ public final class Term implements Comparable { @Override public final String toString() { return field + ":" + bytes.utf8ToString(); } - - public Term deepCopyOf() { - return new Term(field, BytesRef.deepCopyOf(bytes)); - } } diff --git a/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java b/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java index 787ce0253bb..d151dfd0430 100644 --- a/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java +++ b/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java @@ -51,12 +51,15 @@ public abstract class TermsEnum implements BytesRefIterator { return atts; } - /** Represents returned result from {@link #seekCeil}. - * If status is FOUND, then the precise term was found. - * If status is NOT_FOUND, then a different term was - * found. If the status is END, the end of the iteration - * was hit. */ - public static enum SeekStatus {END, FOUND, NOT_FOUND}; + /** Represents returned result from {@link #seekCeil}. */ + public static enum SeekStatus { + /** The term was not found, and the end of iteration was hit. */ + END, + /** The precise term was found. */ + FOUND, + /** A different term was found after the requested term */ + NOT_FOUND + }; /** Attempts to seek to the exact term, returning * true if the term is found. If this returns false, the diff --git a/lucene/core/src/java/org/apache/lucene/util/IOUtils.java b/lucene/core/src/java/org/apache/lucene/util/IOUtils.java index 3c3e32de7d3..5770b80e683 100644 --- a/lucene/core/src/java/org/apache/lucene/util/IOUtils.java +++ b/lucene/core/src/java/org/apache/lucene/util/IOUtils.java @@ -98,7 +98,9 @@ public final class IOUtils { } } - /** @see #closeWhileHandlingException(Exception, Closeable...) */ + /** + * Closes all given Closeables, suppressing all thrown exceptions. + * @see #closeWhileHandlingException(Exception, Closeable...) */ public static void closeWhileHandlingException(E priorException, Iterable objects) throws E, IOException { Throwable th = null; @@ -160,6 +162,7 @@ public final class IOUtils { } /** + * Closes all given Closeables. * @see #close(Closeable...) */ public static void close(Iterable objects) throws IOException { @@ -205,6 +208,7 @@ public final class IOUtils { } /** + * Closes all given Closeables, suppressing all thrown exceptions. * @see #closeWhileHandlingException(Closeable...) */ public static void closeWhileHandlingException(Iterable objects) { @@ -322,6 +326,11 @@ public final class IOUtils { } } + /** + * Deletes all given files, suppressing all thrown IOExceptions. + *

+ * Note that the files should not be null. + */ public static void deleteFilesIgnoringExceptions(Directory dir, String... files) { for (String name : files) { try {