You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by rm...@apache.org on 2012/08/27 22:36:18 UTC
svn commit: r1377836 - in
/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene:
analysis/Analyzer.java analysis/CachingTokenFilter.java codecs/Codec.java
codecs/PostingsFormat.java
Author: rmuir
Date: Mon Aug 27 20:36:18 2012
New Revision: 1377836
URL: http://svn.apache.org/viewvc?rev=1377836&view=rev
Log:
improve these javadocs
Modified:
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java?rev=1377836&r1=1377835&r2=1377836&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java Mon Aug 27 20:36:18 2012
@@ -71,10 +71,22 @@ public abstract class Analyzer {
private final ReuseStrategy reuseStrategy;
+ /**
+ * Create a new Analyzer, reusing the same set of components per-thread
+ * across calls to {@link #tokenStream(String, Reader)}.
+ */
public Analyzer() {
this(new GlobalReuseStrategy());
}
+ /**
+ * Expert: create a new Analyzer with a custom {@link ReuseStrategy}.
+ * <p>
+ * NOTE: if you just want to reuse on a per-field basis, its easier to
+ * use a subclass of {@link AnalyzerWrapper} such as
+ * <a href="{@docRoot}/../analyzers-common/org/apache/lucene/analysis/miscellaneous/PerFieldAnalyzerWrapper.html">
+ * PerFieldAnalyerWrapper</a> instead.
+ */
public Analyzer(ReuseStrategy reuseStrategy) {
this.reuseStrategy = reuseStrategy;
}
@@ -171,7 +183,14 @@ public abstract class Analyzer {
* {@link Analyzer#tokenStream(String, Reader)}.
*/
public static class TokenStreamComponents {
+ /**
+ * Original source of the tokens.
+ */
protected final Tokenizer source;
+ /**
+ * Sink tokenstream, such as the outer tokenfilter decorating
+ * the chain. This can be the source if there are no filters.
+ */
protected final TokenStream sink;
/**
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java?rev=1377836&r1=1377835&r2=1377836&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java Mon Aug 27 20:36:18 2012
@@ -38,6 +38,11 @@ public final class CachingTokenFilter ex
private Iterator<AttributeSource.State> iterator = null;
private AttributeSource.State finalState;
+ /**
+ * Create a new CachingTokenFilter around <code>input</code>,
+ * caching its token attributes, which can be replayed again
+ * after a call to {@link #reset()}.
+ */
public CachingTokenFilter(TokenStream input) {
super(input);
}
@@ -67,6 +72,13 @@ public final class CachingTokenFilter ex
}
}
+ /**
+ * Rewinds the iterator to the beginning of the cached list.
+ * <p>
+ * Note that this does not call reset() on the wrapped tokenstream ever, even
+ * the first time. You should reset() the inner tokenstream before wrapping
+ * it with CachingTokenFilter.
+ */
@Override
public void reset() {
if(cache != null) {
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/Codec.java?rev=1377836&r1=1377835&r2=1377836&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/Codec.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/Codec.java Mon Aug 27 20:36:18 2012
@@ -41,6 +41,14 @@ public abstract class Codec implements N
private final String name;
+ /**
+ * Creates a new codec.
+ * <p>
+ * The provided name will be written into the index segment: in order to
+ * for the segment to be read this class should be registered with Java's
+ * SPI mechanism (registered in META-INF/ of your jar file, etc).
+ * @param name must be all ascii alphanumeric, and less than 128 characters in length.
+ */
public Codec(String name) {
NamedSPILoader.checkServiceName(name);
this.name = name;
@@ -118,6 +126,10 @@ public abstract class Codec implements N
defaultCodec = codec;
}
+ /**
+ * returns the codec's name. Subclasses can override to provide
+ * more detail (such as parameters).
+ */
@Override
public String toString() {
return name;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java?rev=1377836&r1=1377835&r2=1377836&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java Mon Aug 27 20:36:18 2012
@@ -18,14 +18,24 @@ package org.apache.lucene.codecs;
*/
import java.io.IOException;
+import java.util.ServiceLoader;
import java.util.Set;
+import org.apache.lucene.codecs.perfield.PerFieldPostingsFormat; // javadocs
import org.apache.lucene.index.SegmentWriteState;
import org.apache.lucene.index.SegmentReadState;
import org.apache.lucene.util.NamedSPILoader;
/**
* Encodes/decodes terms, postings, and proximity data.
+ * <p>
+ * Note, when extending this class, the name ({@link #getName}) may
+ * written into the index in certain configurations. In order for the segment
+ * to be read, the name must resolve to your implementation via {@link #forName(String)}.
+ * This method uses Java's
+ * {@link ServiceLoader Service Provider Interface} to resolve codec names.
+ * <p>
+ * @see ServiceLoader
* @lucene.experimental */
public abstract class PostingsFormat implements NamedSPILoader.NamedSPI {
@@ -38,11 +48,21 @@ public abstract class PostingsFormat imp
*/
private final String name;
+ /**
+ * Creates a new postings format.
+ * <p>
+ * The provided name will be written into the index segment in some configurations
+ * (such as when using {@link PerFieldPostingsFormat}): in such configurations,
+ * for the segment to be read this class should be registered with Java's
+ * SPI mechanism (registered in META-INF/ of your jar file, etc).
+ * @param name must be all ascii alphanumeric, and less than 128 characters in length.
+ */
protected PostingsFormat(String name) {
NamedSPILoader.checkServiceName(name);
this.name = name;
}
+ /** Returns this posting format's name */
@Override
public final String getName() {
return name;