From 5fbe9f817996a8d3bafa83a3a99bbae0d444def2 Mon Sep 17 00:00:00 2001
From: Doug Cutting <cutting@apache.org>
Date: Wed, 31 Jul 2002 17:47:14 +0000
Subject: [PATCH] Improved javadoc comments.
git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@149828 13f79535-47bb-0310-9956-ffa450edef68
---
default.properties | 2 +-
.../org/apache/lucene/store/Directory.java | 29 ++++---
.../org/apache/lucene/store/FSDirectory.java | 21 +++--
.../org/apache/lucene/store/InputStream.java | 76 ++++++++++++++++---
.../org/apache/lucene/store/OutputStream.java | 61 +++++++++++++--
.../org/apache/lucene/store/RAMDirectory.java | 2 +
src/java/org/apache/lucene/store/package.html | 2 +-
7 files changed, 147 insertions(+), 46 deletions(-)
diff --git a/default.properties b/default.properties
index 95d11a3c41c..a7f267290e8 100644
--- a/default.properties
+++ b/default.properties
@@ -29,7 +29,7 @@ dist-src.dir = ${final.name}-src
packages=org.apache.lucene.*
# javadoc link
-javadoc.link=http://java.sun.com/products/jdk/1.3/docs/api/
+javadoc.link=http://java.sun.com/j2se/1.4/docs/api/
build.compiler.pedantic=false
diff --git a/src/java/org/apache/lucene/store/Directory.java b/src/java/org/apache/lucene/store/Directory.java
index 2aaacbfa83d..c96586293d9 100644
--- a/src/java/org/apache/lucene/store/Directory.java
+++ b/src/java/org/apache/lucene/store/Directory.java
@@ -56,22 +56,19 @@ package org.apache.lucene.store;
import java.io.IOException;
-/*
- Java's filesystem API is not used directly, but rather through these
- classes. This permits:
- . implementation of RAM-based indices, useful for summarization, etc.;
- . implementation of an index as a single file.
-
-*/
-
-/**
- A Directory is a flat list of files. Files may be written once,
- when they are created. Once a file is created it may only be opened for
- read, or deleted. Random access is permitted when reading and writing.
-
- @author Doug Cutting
-*/
-
+/** A Directory is a flat list of files. Files may be written once, when they
+ * are created. Once a file is created it may only be opened for read, or
+ * deleted. Random access is permitted both when reading and writing.
+ *
+ * <p> Java's i/o APIs not used directly, but rather all i/o is
+ * through this API. This permits things such as: <ul>
+ * <li> implementation of RAM-based indices;
+ * <li> implementation indices stored in a database, via JDBC;
+ * <li> implementation of an index as a single file;
+ * </ul>
+ *
+ * @author Doug Cutting
+ */
abstract public class Directory {
/** Returns an array of strings, one for each file in the directory. */
abstract public String[] list()
diff --git a/src/java/org/apache/lucene/store/FSDirectory.java b/src/java/org/apache/lucene/store/FSDirectory.java
index 124936e7005..b2c0a23658f 100644
--- a/src/java/org/apache/lucene/store/FSDirectory.java
+++ b/src/java/org/apache/lucene/store/FSDirectory.java
@@ -63,9 +63,9 @@ import java.util.Hashtable;
import org.apache.lucene.util.Constants;
/**
- * Straightforward implementation of Directory as a directory of files.
- * If the system property 'disableLuceneLocks' has the String value of "true",
- * lock creation will be disabled.
+ * Straightforward implementation of {@link Directory} as a directory of files.
+ * <p>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 <I>disableLuceneLocks</I> has the value of 'true'
- * the lock will not be created. Assigning this property any other value
- * will <B>not</B> prevent creation of locks.
- * <BR>
- * 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() }.
+ *
+ * <p>In JDK 1.1 or if system property <I>disableLuceneLocks</I> is the
+ * string "true", locks are disabled. Assigning this property any other
+ * string will <B>not</B> 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 <code>Lock</code> 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.
+ *
+ * <p>Clones of a stream access the same data, and are positioned at the same
+ * point as the stream they were cloned from.
+ *
+ * <p>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 @@
<meta name="Author" content="Doug Cutting">
</head>
<body>
-Binary i/o API, for storing index data.
+Binary i/o API, used for all index data.
</body>
</html>