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 2011/02/20 14:25:52 UTC
svn commit: r1072591 - in
/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene: analysis/
index/ store/ util/ util/automaton/
Author: rmuir
Date: Sun Feb 20 13:25:51 2011
New Revision: 1072591
URL: http://svn.apache.org/viewvc?rev=1072591&view=rev
Log:
LUCENE-2928: Improve LuceneTestCase javadocs
Modified:
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java
lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockAnalyzer.java Sun Feb 20 13:25:51 2011
@@ -36,6 +36,10 @@ public final class MockAnalyzer extends
private final boolean payload;
private int positionIncrementGap;
+ /**
+ * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean)
+ * MockAnalyzer(runAutomaton, lowerCase, filter, enablePositionIncrements, true}).
+ */
public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, CharacterRunAutomaton filter, boolean enablePositionIncrements) {
this(runAutomaton, lowerCase, filter, enablePositionIncrements, true);
}
@@ -47,7 +51,7 @@ public final class MockAnalyzer extends
* @param lowerCase true if the tokenizer should lowercase terms
* @param filter DFA describing how terms should be filtered (set of stopwords, etc)
* @param enablePositionIncrements true if position increments should reflect filtered terms.
- * @param payload if payloads should be added
+ * @param payload if payloads should be added containing the positions (for testing)
*/
public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, CharacterRunAutomaton filter, boolean enablePositionIncrements, boolean payload) {
this.runAutomaton = runAutomaton;
@@ -58,21 +62,26 @@ public final class MockAnalyzer extends
}
/**
- * Creates a new MockAnalyzer, with no filtering.
- *
- * @param runAutomaton DFA describing how tokenization should happen (e.g. [a-zA-Z]+)
- * @param lowerCase true if the tokenizer should lowercase terms
+ * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean)
+ * MockAnalyzer(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, true}).
*/
public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase) {
this(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, true);
}
+ /**
+ * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean)
+ * MockAnalyzer(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, payload}).
+ */
public MockAnalyzer(CharacterRunAutomaton runAutomaton, boolean lowerCase, boolean payload) {
this(runAutomaton, lowerCase, MockTokenFilter.EMPTY_STOPSET, false, payload);
}
/**
- * Create a Whitespace-lowercasing analyzer with no stopwords removal
+ * Create a Whitespace-lowercasing analyzer with no stopwords removal.
+ * <p>
+ * Calls {@link #MockAnalyzer(CharacterRunAutomaton, boolean, CharacterRunAutomaton, boolean, boolean)
+ * MockAnalyzer(MockTokenizer.WHITESPACE, true, MockTokenFilter.EMPTY_STOPSET, false, true}).
*/
public MockAnalyzer() {
this(MockTokenizer.WHITESPACE, true);
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenFilter.java Sun Feb 20 13:25:51 2011
@@ -60,6 +60,13 @@ public final class MockTokenFilter exten
private final CharTermAttribute termAtt = addAttribute(CharTermAttribute.class);
private final PositionIncrementAttribute posIncrAtt = addAttribute(PositionIncrementAttribute.class);
+ /**
+ * Create a new MockTokenFilter.
+ *
+ * @param input TokenStream to filter
+ * @param filter DFA representing the terms that should be removed.
+ * @param enablePositionIncrements true if the removal should accumulate position increments.
+ */
public MockTokenFilter(TokenStream input, CharacterRunAutomaton filter, boolean enablePositionIncrements) {
super(input);
this.filter = filter;
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/analysis/MockTokenizer.java Sun Feb 20 13:25:51 2011
@@ -20,7 +20,7 @@ package org.apache.lucene.analysis;
import java.io.IOException;
import java.io.Reader;
-import org.apache.lucene.util.Version;
+import org.apache.lucene.util.LuceneTestCase;
import org.apache.lucene.util.automaton.CharacterRunAutomaton;
import org.apache.lucene.util.automaton.RegExp;
@@ -46,14 +46,14 @@ public class MockTokenizer extends CharT
private int state;
public MockTokenizer(AttributeFactory factory, Reader input, CharacterRunAutomaton runAutomaton, boolean lowerCase) {
- super(Version.LUCENE_CURRENT, factory, input);
+ super(LuceneTestCase.TEST_VERSION_CURRENT, factory, input);
this.runAutomaton = runAutomaton;
this.lowerCase = lowerCase;
this.state = runAutomaton.getInitialState();
}
public MockTokenizer(Reader input, CharacterRunAutomaton runAutomaton, boolean lowerCase) {
- super(Version.LUCENE_CURRENT, input);
+ super(LuceneTestCase.TEST_VERSION_CURRENT, input);
this.runAutomaton = runAutomaton;
this.lowerCase = lowerCase;
this.state = runAutomaton.getInitialState();
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java Sun Feb 20 13:25:51 2011
@@ -91,6 +91,10 @@ public class RandomIndexWriter implement
}
}
+ /**
+ * Adds a Document.
+ * @see IndexWriter#addDocument(Document)
+ */
public void addDocument(Document doc) throws IOException {
w.addDocument(doc);
if (docCount++ == flushAt) {
@@ -102,6 +106,10 @@ public class RandomIndexWriter implement
}
}
+ /**
+ * Updates a document.
+ * @see IndexWriter#updateDocument(Term, Document)
+ */
public void updateDocument(Term t, Document doc) throws IOException {
w.updateDocument(t, doc);
if (docCount++ == flushAt) {
@@ -162,6 +170,10 @@ public class RandomIndexWriter implement
}
}
+ /**
+ * Close this writer.
+ * @see IndexWriter#close()
+ */
public void close() throws IOException {
// if someone isn't using getReader() API, we want to be sure to
// maybeOptimize since presumably they might open a reader on the dir.
@@ -171,6 +183,13 @@ public class RandomIndexWriter implement
w.close();
}
+ /**
+ * Forces an optimize.
+ * <p>
+ * NOTE: this should be avoided in tests unless absolutely necessary,
+ * as it will result in less test coverage.
+ * @see IndexWriter#optimize()
+ */
public void optimize() throws IOException {
w.optimize();
}
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java Sun Feb 20 13:25:51 2011
@@ -38,6 +38,18 @@ import org.apache.lucene.util._TestUtil;
/**
* This is a Directory Wrapper that adds methods
* intended to be used only by unit tests.
+ * It also adds a number of features useful for testing:
+ * <ul>
+ * <li> Instances created by {@link LuceneTestCase#newDirectory()} are tracked
+ * to ensure they are closed by the test.
+ * <li> When a MockDirectoryWrapper is closed, it will throw an exception if
+ * it has any open files against it (with a stacktrace indicating where
+ * they were opened from).
+ * <li> When a MockDirectoryWrapper is closed, it runs CheckIndex to test if
+ * the index was corrupted.
+ * <li> MockDirectoryWrapper simulates some "features" of Windows, such as
+ * refusing to write/delete to open files.
+ * </ul>
*/
public class MockDirectoryWrapper extends Directory {
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java Sun Feb 20 13:25:51 2011
@@ -32,9 +32,9 @@ import java.util.Random;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
-// Minimal port of contrib/benchmark's LneDocSource +
-// DocMaker, so tests can enum docs from a line file created
-// by contrib/benchmark's WriteLineDoc task
+/** Minimal port of contrib/benchmark's LneDocSource +
+ * DocMaker, so tests can enum docs from a line file created
+ * by contrib/benchmark's WriteLineDoc task */
public class LineFileDocs implements Closeable {
private BufferedReader reader;
@@ -42,8 +42,8 @@ public class LineFileDocs implements Clo
private final AtomicInteger id = new AtomicInteger();
private final String path;
- // If forever is true, we rewind the file at EOF (repeat
- // the docs over and over)
+ /** If forever is true, we rewind the file at EOF (repeat
+ * the docs over and over) */
public LineFileDocs(Random random, String path) throws IOException {
this.path = path;
open(random);
@@ -138,7 +138,7 @@ public class LineFileDocs implements Clo
private final ThreadLocal<DocState> threadDocs = new ThreadLocal<DocState>();
- // Document instance is re-used per-thread
+ /** Note: Document instance is re-used per-thread */
public Document nextDoc() throws IOException {
String line;
synchronized(this) {
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java Sun Feb 20 13:25:51 2011
@@ -708,7 +708,7 @@ public abstract class LuceneTestCase ext
}
/**
- * Convinience method for logging an iterator.
+ * Convenience method for logging an iterator.
*
* @param label String logged before/after the items in the iterator
* @param iter Each next() is toString()ed and logged on it's own line. If iter is null this is logged differnetly then an empty iterator.
@@ -728,7 +728,7 @@ public abstract class LuceneTestCase ext
}
/**
- * Convinience method for logging an array. Wraps the array in an iterator and delegates
+ * Convenience method for logging an array. Wraps the array in an iterator and delegates
*
* @see #dumpIterator(String,Iterator,PrintStream)
*/
@@ -743,6 +743,7 @@ public abstract class LuceneTestCase ext
return newIndexWriterConfig(random, v, a);
}
+ /** create a new index writer config with random defaults using the specified random */
public static IndexWriterConfig newIndexWriterConfig(Random r, Version v, Analyzer a) {
IndexWriterConfig c = new IndexWriterConfig(v, a);
if (r.nextBoolean()) {
@@ -835,6 +836,10 @@ public abstract class LuceneTestCase ext
return newDirectory(random);
}
+ /**
+ * Returns a new Directory instance, using the specified random.
+ * See {@link #newDirectory()} for more information.
+ */
public static MockDirectoryWrapper newDirectory(Random r) throws IOException {
Directory impl = newDirectoryImpl(r, TEST_DIRECTORY);
MockDirectoryWrapper dir = new MockDirectoryWrapper(r, impl);
@@ -889,6 +894,11 @@ public abstract class LuceneTestCase ext
}
}
+ /**
+ * Returns a new Directory instance, using the specified random
+ * with contents copied from the provided directory. See
+ * {@link #newDirectory()} for more information.
+ */
public static MockDirectoryWrapper newDirectory(Random r, Directory d) throws IOException {
Directory impl = newDirectoryImpl(r, TEST_DIRECTORY);
for (String file : d.listAll()) {
@@ -899,26 +909,45 @@ public abstract class LuceneTestCase ext
return dir;
}
+ /** Returns a new field instance.
+ * See {@link #newField(String, String, Store, Index, TermVector)} for more information */
public static Field newField(String name, String value, Index index) {
return newField(random, name, value, index);
}
+ /** Returns a new field instance.
+ * See {@link #newField(String, String, Store, Index, TermVector)} for more information */
public static Field newField(String name, String value, Store store, Index index) {
return newField(random, name, value, store, index);
}
+ /**
+ * Returns a new Field instance. Use this when the test does not
+ * care about some specific field settings (most tests)
+ * <ul>
+ * <li>If the store value is set to Store.NO, sometimes the field will be randomly stored.
+ * <li>More term vector data than you ask for might be indexed, for example if you choose YES
+ * it might index term vectors with offsets too.
+ * </ul>
+ */
public static Field newField(String name, String value, Store store, Index index, TermVector tv) {
return newField(random, name, value, store, index, tv);
}
+ /** Returns a new field instance, using the specified random.
+ * See {@link #newField(String, String, Store, Index, TermVector)} for more information */
public static Field newField(Random random, String name, String value, Index index) {
return newField(random, name, value, Store.NO, index);
}
+ /** Returns a new field instance, using the specified random.
+ * See {@link #newField(String, String, Store, Index, TermVector)} for more information */
public static Field newField(Random random, String name, String value, Store store, Index index) {
return newField(random, name, value, store, index, TermVector.NO);
}
+ /** Returns a new field instance, using the specified random.
+ * See {@link #newField(String, String, Store, Index, TermVector)} for more information */
public static Field newField(Random random, String name, String value, Store store, Index index, TermVector tv) {
if (!index.isIndexed())
return new Field(name, value, store, index);
@@ -1029,7 +1058,8 @@ public abstract class LuceneTestCase ext
}
}
- /** create a new searcher over the reader */
+ /** create a new searcher over the reader.
+ * This searcher might randomly use threads. */
public static IndexSearcher newSearcher(IndexReader r) throws IOException {
if (random.nextBoolean()) {
return new IndexSearcher(r);
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java Sun Feb 20 13:25:51 2011
@@ -52,6 +52,9 @@ public class _TestUtil {
return new File(LuceneTestCase.TEMP_DIR, desc + "." + new Random().nextLong());
}
+ /**
+ * Deletes a directory and everything underneath it.
+ */
public static void rmDir(File dir) throws IOException {
if (dir.exists()) {
for (File f : dir.listFiles()) {
@@ -155,6 +158,9 @@ public class _TestUtil {
return randomUnicodeString(r, 20);
}
+ /**
+ * Returns a random string up to a certain length.
+ */
public static String randomUnicodeString(Random r, int maxLength) {
final int end = r.nextInt(maxLength);
if (end == 0) {
@@ -280,8 +286,8 @@ public class _TestUtil {
}
}
- // just tries to configure things to keep the open file
- // count lowish
+ /** just tries to configure things to keep the open file
+ * count lowish */
public static void reduceOpenFiles(IndexWriter w) {
// keep number of open files lowish
LogMergePolicy lmp = (LogMergePolicy) w.getConfig().getMergePolicy();
Modified: lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java?rev=1072591&r1=1072590&r2=1072591&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java (original)
+++ lucene/dev/trunk/lucene/src/test-framework/org/apache/lucene/util/automaton/AutomatonTestUtil.java Sun Feb 20 13:25:51 2011
@@ -80,9 +80,9 @@ public class AutomatonTestUtil {
return new String(buffer, 0, end);
}
- // picks a random int code point, avoiding surrogates;
- // throws IllegalArgumentException if this transition only
- // accepts surrogates
+ /** picks a random int code point, avoiding surrogates;
+ * throws IllegalArgumentException if this transition only
+ * accepts surrogates */
private static int getRandomCodePoint(final Random r, final Transition t) {
final int code;
if (t.max < UnicodeUtil.UNI_SUR_HIGH_START ||