You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Dmitry Serebrennikov <dm...@earthlink.net> on 2001/10/13 07:53:43 UTC
Re: Corrected (again) comments for Input/Output Stream
Sorry about the spam. Please disregard the previous post - this one is
correct.
===================================================================
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:47:57
@@ -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,24 @@
}
}
+ /** 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. Note that
negative numbers
+ * are always stored using the maximum number of bytes.
+ */
public final int readVInt() throws IOException {
byte b = readByte();
int i = b & 0x7F;
@@ -112,10 +124,20 @@
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 10 bytes. Note that
negative numbers
+ * are always stored using the maximum number of bytes.
+ *
+ */
public final long readVLong() throws IOException {
byte b = readByte();
long i = b & 0x7F;
@@ -126,6 +148,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 +160,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 +212,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 +225,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:47:57
@@ -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,12 @@
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 1 to 5 bytes, depending on the value of the
+ * integer. Note that negative numbers
+ * are always stored using the maximum number of bytes.
+ */
public final void writeVInt(int i) throws IOException {
while ((i & ~0x7F) != 0) {
writeByte((byte)((i & 0x7f) | 0x80));
@@ -96,11 +104,19 @@
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
1 to
+ * 10 bytes depending on the value of the long. Note that negative
numbers
+ * are always stored using the maximum number of bytes.
+ */
public final void writeVLong(long i) throws IOException {
while ((i & ~0x7F) != 0) {
writeByte((byte)((i & 0x7f) | 0x80));
@@ -109,12 +125,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 +166,7 @@
abstract protected void flushBuffer(byte[] b, int len) throws
IOException;
+ /** Flush and close the stream. */
public void close() throws IOException {
flush();
}
@@ -150,11 +176,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;