Mailing List Archive

cutting 2002/07/31 10:47:14

Modified: . default.properties
src/java/org/apache/lucene/store Directory.java
FSDirectory.java InputStream.java OutputStream.java
RAMDirectory.java package.html
Log:
Improved javadoc comments.

Revision Changes Path
1.9 +1 -1 jakarta-lucene/default.properties

Index: default.properties
===================================================================
RCS file: /home/cvs/jakarta-lucene/default.properties,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- default.properties 17 Jun 2002 15:34:27 -0000 1.8
+++ default.properties 31 Jul 2002 17:47:14 -0000 1.9
@@ -29,7 +29,7 @@
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




1.3 +13 -16 jakarta-lucene/src/java/org/apache/lucene/store/Directory.java

Index: Directory.java
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/Directory.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Directory.java 27 Sep 2001 16:27:01 -0000 1.2
+++ Directory.java 31 Jul 2002 17:47:14 -0000 1.3
@@ -56,22 +56,19 @@

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()



1.10 +10 -11 jakarta-lucene/src/java/org/apache/lucene/store/FSDirectory.java

Index: FSDirectory.java
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/FSDirectory.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- FSDirectory.java 26 Jun 2002 17:30:11 -0000 1.9
+++ FSDirectory.java 31 Jul 2002 17:47:14 -0000 1.10
@@ -63,9 +63,9 @@
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 @@
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



1.2 +67 -9 jakarta-lucene/src/java/org/apache/lucene/store/InputStream.java

Index: InputStream.java
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/InputStream.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- InputStream.java 18 Sep 2001 16:29:59 -0000 1.1
+++ InputStream.java 31 Jul 2002 17:47:14 -0000 1.2
@@ -56,12 +56,11 @@

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 @@

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 @@
}
}

+ /** 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 @@
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 @@
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 @@
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 @@
}


- 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 @@
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 @@
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 {



1.2 +53 -8 jakarta-lucene/src/java/org/apache/lucene/store/OutputStream.java

Index: OutputStream.java
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/OutputStream.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- OutputStream.java 18 Sep 2001 16:29:59 -0000 1.1
+++ OutputStream.java 31 Jul 2002 17:47:14 -0000 1.2
@@ -56,12 +56,11 @@

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 @@
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 @@
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 @@
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 @@
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 @@
}
}

+ /** 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;





1.4 +2 -0 jakarta-lucene/src/java/org/apache/lucene/store/RAMDirectory.java

Index: RAMDirectory.java
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/RAMDirectory.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- RAMDirectory.java 31 Oct 2001 00:12:30 -0000 1.3
+++ RAMDirectory.java 31 Jul 2002 17:47:14 -0000 1.4
@@ -63,9 +63,11 @@
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() {
}




1.2 +1 -1 jakarta-lucene/src/java/org/apache/lucene/store/package.html

Index: package.html
===================================================================
RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 18 Sep 2001 16:29:59 -0000 1.1
+++ package.html 31 Jul 2002 17:47:14 -0000 1.2
@@ -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>




--
To unsubscribe, e-mail: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>