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 15:19:04 UTC
svn commit: r1072601 - in /lucene/dev/branches/branch_3x: ./ lucene/
lucene/src/test-framework/org/apache/lucene/index/
lucene/src/test-framework/org/apache/lucene/store/
lucene/src/test-framework/org/apache/lucene/util/ solr/
Author: rmuir
Date: Sun Feb 20 14:19:03 2011
New Revision: 1072601
URL: http://svn.apache.org/viewvc?rev=1072601&view=rev
Log:
LUCENE-2928: Improve LuceneTestCase javadocs
Modified:
lucene/dev/branches/branch_3x/ (props changed)
lucene/dev/branches/branch_3x/lucene/ (props changed)
lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java
lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java
lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java
lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java
lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java
lucene/dev/branches/branch_3x/solr/ (props changed)
Modified: lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java?rev=1072601&r1=1072600&r2=1072601&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java (original)
+++ lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/index/RandomIndexWriter.java Sun Feb 20 14:19:03 2011
@@ -101,6 +101,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) {
@@ -152,6 +156,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.
@@ -161,6 +169,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/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java?rev=1072601&r1=1072600&r2=1072601&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java (original)
+++ lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/store/MockDirectoryWrapper.java Sun Feb 20 14:19:03 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/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java?rev=1072601&r1=1072600&r2=1072601&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java (original)
+++ lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LineFileDocs.java Sun Feb 20 14:19:03 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/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java?rev=1072601&r1=1072600&r2=1072601&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java (original)
+++ lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/LuceneTestCase.java Sun Feb 20 14:19:03 2011
@@ -576,7 +576,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.
@@ -596,7 +596,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)
*/
@@ -611,6 +611,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()) {
@@ -698,6 +699,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);
@@ -752,6 +757,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()) {
@@ -762,26 +772,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);
@@ -892,7 +921,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/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java?rev=1072601&r1=1072600&r2=1072601&view=diff
==============================================================================
--- lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java (original)
+++ lucene/dev/branches/branch_3x/lucene/src/test-framework/org/apache/lucene/util/_TestUtil.java Sun Feb 20 14:19:03 2011
@@ -49,6 +49,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()) {
@@ -175,6 +178,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) {
@@ -282,8 +288,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.getMergePolicy();