lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dmitry Serebrennikov <dmit...@earthlink.net>
Subject Corrected comments for Input/Output Stream
Date Sat, 13 Oct 2001 05:41:37 GMT
Here are the corrected comments per Doug's remarks.

===================================================================
RCS file: 
/home/cvspublic/jakarta-lucene/src/java/org/apache/lucene/store/InputStream.java,v
retrieving revision 1.1.1.1
diff -u -w -r1.1.1.1 InputStream.java
--- java/org/apache/lucene/store/InputStream.java       2001/09/18 
16:29:59     1.1.1.1
+++ java/org/apache/lucene/store/InputStream.java       2001/10/13 05:35:24
@@ -60,8 +60,6 @@
   Abstract class for input from a file in a Directory.
   @author Doug Cutting
 */
-
-/** A random-access input stream */
 abstract public class InputStream implements Cloneable {
   final static int BUFFER_SIZE = OutputStream.BUFFER_SIZE;

@@ -81,6 +79,7 @@
     return buffer[bufferPosition++];
   }

+  /** InputStream-like methods @see java.io.InputStream */
   public final void readBytes(byte[] b, int offset, int len)
        throws IOException {
     if (len < BUFFER_SIZE) {
@@ -97,11 +96,23 @@
     }
   }

+  /** Read an integer from the stream. The integer must have been written
+   *  by a call to OutputStream.writeInt. It is stored as four bytes, 
from most to least
+   *  significant.
+   */
   public final int readInt() throws IOException {
     return ((readByte() & 0xFF) << 24) | ((readByte() & 0xFF) << 16)
          | ((readByte() & 0xFF) <<  8) |  (readByte() & 0xFF);
   }

+  /** Read a compressed (or Variable length) integer from the stream. The
+   *  integer must have been written by a call to OutputStream.writeVInt.
+   *  It is stored as a series of bytes, from least significant to the most
+   *  significant. Each byte contains 7 bits of data and the 8th (0x80) bit
+   *  that indicates that there are more bytes to be read for this integer.
+   *  With this format, smaller integers occupy only one byte,
+   *  larger ones - two bytes, and so on up to 5 bytes.
+   */
   public final int readVInt() throws IOException {
     byte b = readByte();
     int i = b & 0x7F;
@@ -112,10 +123,18 @@
     return i;
   }

+  /** Read a long from the stream. The long must have been written by a 
call to
+   *  OutputStream.writeLong. It is stored as 8 bytes, from most 
significant to the least
+   *  significant.
+   */
   public final long readLong() throws IOException {
     return (((long)readInt()) << 32) | (readInt() & 0xFFFFFFFFL);
   }

+  /** Read a compressed (or Variable length) long from the stream. The 
long must
+   *  have been written by a call to OutputStream.writeVLong. It is stored
+   *  similarly to the VInt, but may occupy 1 to 9 bytes.
+   */
   public final long readVLong() throws IOException {
     byte b = readByte();
     long i = b & 0x7F;
@@ -126,6 +145,10 @@
     return i;
   }

+  /** Read a string from the stream. The string must have been written 
by a call
+   *  to OutputStream.writeString. It is stored as a VInt (see readVInt)
+   *  indicating the string size, followed by that many chars (see 
readChars).
+   */
   public final String readString() throws IOException {
     int length = readVInt();
     if (chars == null || length > chars.length)
@@ -134,6 +157,13 @@
     return new String(chars, 0, length);
   }

+  /** Read an array of characters, placing them into the provided buffer.
+   *  The read characters are placed into array starting with the index 
<i>start</i>
+   *  and continuing for <i>length</i> characters. The characters must 
have been
+   *  written with a call to OutputStream.writeChards. Each character 
is stored
+   *  using one, two, or three bytes, depending on the value of the 
character.
+   *  This represents a standard encoding of Unicode characters known 
as UTF-8.
+   */
   public final void readChars(char[] buffer, int start, int length)
        throws IOException {
     final int end = start + length;
@@ -179,6 +209,7 @@
     return bufferStart + bufferPosition;
   }

+  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
   public final void seek(long pos) throws IOException {
     if (pos >= bufferStart && pos < (bufferStart + bufferLength))
       bufferPosition = (int)(pos - bufferStart);  // seek within buffer
@@ -191,10 +222,16 @@
   }
   abstract protected void seekInternal(long pos) throws IOException;

+  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
   public final long length() {
     return length;
   }

+  /** Create a clone of this stream. The clone provides access to the same
+   *  undelying descriptor as the original file, however it maintains 
its own
+   *  buffer and file position so it can be used concurrently with the 
original
+   *  file and other clones.
+   */
   public Object clone() {
     InputStream clone = null;
     try {
Index: java/org/apache/lucene/store/OutputStream.java
===================================================================
RCS file: 
/home/cvspublic/jakarta-lucene/src/java/org/apache/lucene/store/OutputStream.java,v
retrieving revision 1.1.1.1
diff -u -w -r1.1.1.1 OutputStream.java
--- java/org/apache/lucene/store/OutputStream.java      2001/09/18 
16:29:59     1.1.1.1
+++ java/org/apache/lucene/store/OutputStream.java      2001/10/13 05:35:24
@@ -60,8 +60,6 @@
   Abstract class for output from a file in a Directory.
   @author Doug Cutting
 */
-
-/** A random-access output stream */
 abstract public class OutputStream {
   final static int BUFFER_SIZE = 1024;

@@ -76,11 +74,15 @@
     buffer[bufferPosition++] = b;
   }

+  /** OutputStream-like methods @see java.io.InputStream */
   public final void writeBytes(byte[] b, int length) throws IOException {
     for (int i = 0; i < length; i++)
       writeByte(b[i]);
   }

+  /** Write an integer into the stream. The integer can be read by calling
+   *  InputStream.readInt. It is stored using four bytes.
+   */
   public final void writeInt(int i) throws IOException {
     writeByte((byte)(i >> 24));
     writeByte((byte)(i >> 16));
@@ -88,6 +90,11 @@
     writeByte((byte) i);
   }

+  /** Write a compressed (or Variable length) integer into the stream.
+   *  The integer can be read by calling InputStream.readVInt.
+   *  It is stored using from one to five bytes, depending on the value 
of the
+   *  integer.
+   */
   public final void writeVInt(int i) throws IOException {
     while ((i & ~0x7F) != 0) {
       writeByte((byte)((i & 0x7f) | 0x80));
@@ -96,11 +103,18 @@
     writeByte((byte)i);
   }

+  /** Write a long into the stream. The long can be read by calling 
InputStream.readLong.
+   *  It is stored using 8 bytes.
+   */
   public final void writeLong(long i) throws IOException {
     writeInt((int) (i >> 32));
     writeInt((int) i);
   }

+  /** Write a compressed (or Variable length) long into the stream. The 
long can
+   *  be read by calling InputStream.readVLong. It is stored using from 
one to
+   *  nine bytes depending on the value of the long.
+   */
   public final void writeVLong(long i) throws IOException {
     while ((i & ~0x7F) != 0) {
       writeByte((byte)((i & 0x7f) | 0x80));
@@ -109,12 +123,21 @@
     writeByte((byte)i);
   }

+  /** Write a string into the stream. The string can be read by calling
+   *  InputStream.readString. It is stored as a VInt representing the 
number of
+   *  characters, followed by that many characters (see writeChars).
+   */
   public final void writeString(String s) throws IOException {
     int length = s.length();
     writeVInt(length);
     writeChars(s, 0, length);
   }

+  /** Write an array of characters into the stream. The array can be 
read by
+   *  calling InputStream.readChars. Each character is stored using 
from one to
+   *  three bytes depending on the value of the character.
+   *  This represents a standard encoding of Unicode characters known 
as UTF-8.
+   */
   public final void writeChars(String s, int start, int length)
        throws IOException {
     final int end = start + length;
@@ -141,6 +164,7 @@

   abstract protected void flushBuffer(byte[] b, int len) throws 
IOException;

+  /** Flush and close the stream. */
   public void close() throws IOException {
     flush();
   }
@@ -150,11 +174,13 @@
     return bufferStart + bufferPosition;
   }

+  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
   public void seek(long pos) throws IOException {
     flush();
     bufferStart = pos;
   }

+  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
   abstract public long length() throws IOException;




Mime
View raw message