Java's i/o APIs not used directly, but rather all i/o is + * through this API. This permits things such as:
If the system property 'disableLuceneLocks' has the String value of
+ * "true", lock creation will be disabled.
*
* @see Directory
* @author Doug Cutting
@@ -217,14 +217,13 @@ final public class FSDirectory extends Directory {
return new FSInputStream(new File(directory, name));
}
- /**
- * Constructs a {@link Lock} with the specified name.
- * If JDK 1.1 is used the lock file is not really made.
- * If system property disableLuceneLocks has the value of 'true'
- * the lock will not be created. Assigning this property any other value
- * will not prevent creation of locks.
- *
- * This is useful for using Lucene on read-only medium, such as CD-ROM.
+ /** Constructs a {@link Lock} with the specified name. Locks are implemented
+ * with {@link File#createNewFile() }.
+ *
+ *
In JDK 1.1 or if system property disableLuceneLocks is the
+ * string "true", locks are disabled. Assigning this property any other
+ * string will not prevent creation of lock files. This is useful for
+ * using Lucene on read-only medium, such as CD-ROM.
*
* @param name the name of the lock file
* @return an instance of Lock holding the lock
diff --git a/src/java/org/apache/lucene/store/InputStream.java b/src/java/org/apache/lucene/store/InputStream.java
index 3c5d452529d..0f971d06788 100644
--- a/src/java/org/apache/lucene/store/InputStream.java
+++ b/src/java/org/apache/lucene/store/InputStream.java
@@ -56,12 +56,11 @@ package org.apache.lucene.store;
import java.io.IOException;
-/**
- Abstract class for input from a file in a Directory.
- @author Doug Cutting
-*/
-
-/** A random-access input stream */
+/** Abstract base class for input from a file in a {@link Directory}. A
+ * random-access input stream. Used for all Lucene index input operations.
+ * @see Directory
+ * @see OutputStream
+ */
abstract public class InputStream implements Cloneable {
final static int BUFFER_SIZE = OutputStream.BUFFER_SIZE;
@@ -74,13 +73,21 @@ abstract public class InputStream implements Cloneable {
protected long length; // set by subclasses
- /** InputStream-like methods @see java.io.InputStream */
+ /** Reads and returns a single byte.
+ * @see OutputStream#writeByte(byte)
+ */
public final byte readByte() throws IOException {
if (bufferPosition >= bufferLength)
refill();
return buffer[bufferPosition++];
}
+ /** Reads a specified number of bytes into an array at the specified offset.
+ * @param b the array to read bytes into
+ * @param offset the offset in the array to start storing bytes
+ * @param len the number of bytes to read
+ * @see OutputStream#writeBytes(byte[],int)
+ */
public final void readBytes(byte[] b, int offset, int len)
throws IOException {
if (len < BUFFER_SIZE) {
@@ -97,11 +104,19 @@ abstract public class InputStream implements Cloneable {
}
}
+ /** Reads four bytes and returns an int.
+ * @see OutputStream#writeInt(int)
+ */
public final int readInt() throws IOException {
return ((readByte() & 0xFF) << 24) | ((readByte() & 0xFF) << 16)
| ((readByte() & 0xFF) << 8) | (readByte() & 0xFF);
}
+ /** Reads an int stored in variable-length format. Reads between one and
+ * five bytes. Smaller values take fewer bytes. Negative numbers are not
+ * supported.
+ * @see OutputStream#writeVInt(int)
+ */
public final int readVInt() throws IOException {
byte b = readByte();
int i = b & 0x7F;
@@ -112,10 +127,16 @@ abstract public class InputStream implements Cloneable {
return i;
}
+ /** Reads eight bytes and returns a long.
+ * @see OutputStream#writeLong(long)
+ */
public final long readLong() throws IOException {
return (((long)readInt()) << 32) | (readInt() & 0xFFFFFFFFL);
}
+ /** Reads a long stored in variable-length format. Reads between one and
+ * nine bytes. Smaller values take fewer bytes. Negative numbers are not
+ * supported. */
public final long readVLong() throws IOException {
byte b = readByte();
long i = b & 0x7F;
@@ -126,6 +147,9 @@ abstract public class InputStream implements Cloneable {
return i;
}
+ /** Reads a string.
+ * @see OutputStream#writeString(String)
+ */
public final String readString() throws IOException {
int length = readVInt();
if (chars == null || length > chars.length)
@@ -134,6 +158,12 @@ abstract public class InputStream implements Cloneable {
return new String(chars, 0, length);
}
+ /** Reads UTF-8 encoded characters into an array.
+ * @param buffer the array to read characters into
+ * @param start the offset in the array to start storing characters
+ * @param length the number of characters to read
+ * @see OutputStream#writeChars(String,int,int)
+ */
public final void readChars(char[] buffer, int start, int length)
throws IOException {
final int end = start + length;
@@ -152,7 +182,7 @@ abstract public class InputStream implements Cloneable {
}
- protected final void refill() throws IOException {
+ private void refill() throws IOException {
long start = bufferStart + bufferPosition;
long end = start + BUFFER_SIZE;
if (end > length) // don't read past EOF
@@ -169,16 +199,29 @@ abstract public class InputStream implements Cloneable {
bufferPosition = 0;
}
+ /** Expert: implements buffer refill. Reads bytes from the current position
+ * in the input.
+ * @param b the array to read bytes into
+ * @param offset the offset in the array to start storing bytes
+ * @param length the number of bytes to read
+ */
abstract protected void readInternal(byte[] b, int offset, int length)
throws IOException;
+ /** Closes the stream to futher operations. */
abstract public void close() throws IOException;
- /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
+ /** Returns the current position in this file, where the next read will
+ * occur.
+ * @see #seek(long)
+ */
public final long getFilePointer() {
return bufferStart + bufferPosition;
}
+ /** Sets current position in this file, where the next read will occur.
+ * @see #getFilePointer()
+ */
public final void seek(long pos) throws IOException {
if (pos >= bufferStart && pos < (bufferStart + bufferLength))
bufferPosition = (int)(pos - bufferStart); // seek within buffer
@@ -189,12 +232,27 @@ abstract public class InputStream implements Cloneable {
seekInternal(pos);
}
}
+
+ /** Expert: implements seek. Sets current position in this file, where the
+ * next {@link #readInternal(byte[],int,int)} will occur.
+ * @see #readInternal(byte[],int,int)
+ */
abstract protected void seekInternal(long pos) throws IOException;
+ /** The number of bytes in the file. */
public final long length() {
return length;
}
+ /** Returns a clone of this stream.
+ *
+ *
Clones of a stream access the same data, and are positioned at the same + * point as the stream they were cloned from. + * + *
Expert: Subclasses must ensure that clones may be positioned at + * different points in the input from each other and from the stream they + * were cloned from. + */ public Object clone() { InputStream clone = null; try { diff --git a/src/java/org/apache/lucene/store/OutputStream.java b/src/java/org/apache/lucene/store/OutputStream.java index 177a3f456b7..0f6772241c9 100644 --- a/src/java/org/apache/lucene/store/OutputStream.java +++ b/src/java/org/apache/lucene/store/OutputStream.java @@ -56,12 +56,11 @@ package org.apache.lucene.store; import java.io.IOException; -/** - Abstract class for output from a file in a Directory. - @author Doug Cutting -*/ - -/** A random-access output stream */ +/** Abstract class for output to a file in a Directory. A random-access output + * stream. Used for all Lucene index output operations. + * @see Directory + * @see InputStream + */ abstract public class OutputStream { final static int BUFFER_SIZE = 1024; @@ -69,18 +68,28 @@ abstract public class OutputStream { private long bufferStart = 0; // position in file of buffer private int bufferPosition = 0; // position in buffer - /** OutputStream-like methods @see java.io.InputStream */ + /** Writes a single byte. + * @see InputStream#readByte() + */ public final void writeByte(byte b) throws IOException { if (bufferPosition >= BUFFER_SIZE) flush(); buffer[bufferPosition++] = b; } + /** Writes an array of bytes. + * @param b the bytes to write + * @param length the number of bytes to write + * @see InputStream#readBytes(byte[],int,int) + */ public final void writeBytes(byte[] b, int length) throws IOException { for (int i = 0; i < length; i++) writeByte(b[i]); } + /** Writes an int as four bytes. + * @see InputStream#readInt() + */ public final void writeInt(int i) throws IOException { writeByte((byte)(i >> 24)); writeByte((byte)(i >> 16)); @@ -88,6 +97,11 @@ abstract public class OutputStream { writeByte((byte) i); } + /** Writes an int in a variable-length format. Writes between one and + * five bytes. Smaller values take fewer bytes. Negative numbers are not + * supported. + * @see InputStream#readVInt() + */ public final void writeVInt(int i) throws IOException { while ((i & ~0x7F) != 0) { writeByte((byte)((i & 0x7f) | 0x80)); @@ -96,11 +110,19 @@ abstract public class OutputStream { writeByte((byte)i); } + /** Writes a long as eight bytes. + * @see InputStream#readLong() + */ public final void writeLong(long i) throws IOException { writeInt((int) (i >> 32)); writeInt((int) i); } + /** Writes an long in a variable-length format. Writes between one and five + * bytes. Smaller values take fewer bytes. Negative numbers are not + * supported. + * @see InputStream#readVLong() + */ public final void writeVLong(long i) throws IOException { while ((i & ~0x7F) != 0) { writeByte((byte)((i & 0x7f) | 0x80)); @@ -109,12 +131,21 @@ abstract public class OutputStream { writeByte((byte)i); } + /** Writes a string. + * @see InputStream#readString() + */ public final void writeString(String s) throws IOException { int length = s.length(); writeVInt(length); writeChars(s, 0, length); } + /** Writes a sequence of UTF-8 encoded characters from a string. + * @param s the source of the characters + * @param start the first character in the sequence + * @param length the number of characters in the sequence + * @see InputStream#readChars(char[],int,int) + */ public final void writeChars(String s, int start, int length) throws IOException { final int end = start + length; @@ -133,28 +164,42 @@ abstract public class OutputStream { } } + /** Forces any buffered output to be written. */ protected final void flush() throws IOException { flushBuffer(buffer, bufferPosition); bufferStart += bufferPosition; bufferPosition = 0; } + /** Expert: implements buffer write. Writes bytes at the current position in + * the output. + * @param b the bytes to write + * @param len the number of bytes to write + */ abstract protected void flushBuffer(byte[] b, int len) throws IOException; + /** Closes this stream to further operations. */ public void close() throws IOException { flush(); } - /** RandomAccessFile-like methods @see java.io.RandomAccessFile */ + /** Returns the current position in this file, where the next write will + * occur. + * @see #seek(long) + */ public final long getFilePointer() throws IOException { return bufferStart + bufferPosition; } + /** Sets current position in this file, where the next write will occur. + * @see #getFilePointer() + */ public void seek(long pos) throws IOException { flush(); bufferStart = pos; } + /** The number of bytes in the file. */ abstract public long length() throws IOException; diff --git a/src/java/org/apache/lucene/store/RAMDirectory.java b/src/java/org/apache/lucene/store/RAMDirectory.java index 629621a9152..da780bffe26 100644 --- a/src/java/org/apache/lucene/store/RAMDirectory.java +++ b/src/java/org/apache/lucene/store/RAMDirectory.java @@ -63,9 +63,11 @@ import org.apache.lucene.store.Directory; import org.apache.lucene.store.InputStream; import org.apache.lucene.store.OutputStream; +/** A memory-resident {@link Directory} implementation. */ final public class RAMDirectory extends Directory { Hashtable files = new Hashtable(); + /** Constructs an empty {@link Directory}. */ public RAMDirectory() { } diff --git a/src/java/org/apache/lucene/store/package.html b/src/java/org/apache/lucene/store/package.html index 06f213f5682..b4275857dde 100644 --- a/src/java/org/apache/lucene/store/package.html +++ b/src/java/org/apache/lucene/store/package.html @@ -5,6 +5,6 @@
-Binary i/o API, for storing index data. +Binary i/o API, used for all index data.