* efficient mechanism for writing versus doing numerous small unbuffered
* writes.
*
- * @version 0.0
- *
* @author Aaron M. Renn (arenn@urbanophile.com)
*/
public class BufferedOutputStream extends FilterOutputStream
{
-
-/*************************************************************************/
-
-/*
- * Class Variables
- */
-
-/**
- * This is the default buffer size
- */
-private static final int DEFAULT_BUFFER_SIZE = 512;
-
-/*************************************************************************/
-
-/*
- * Instance Variables
- */
-
-/**
- * This is the internal byte array used for buffering output before
- * writing it.
- */
-protected byte[] buf;
-
-/**
- * This is the number of bytes that are currently in the buffer and
- * are waiting to be written to the underlying stream. It always points to
- * the index into the buffer where the next byte of data will be stored
- */
-protected int count;
-
-/*************************************************************************/
-
-/*
- * Constructors
- */
-
-/**
- * This method initializes a new <code>BufferedOutputStream</code> instance
- * that will write to the specified subordinate <code>OutputStream</code>
- * and which will use a default buffer size of 512 bytes.
- *
- * @param out The underlying <code>OutputStream</code> to write data to
- */
-public
-BufferedOutputStream(OutputStream out)
-{
- this(out, DEFAULT_BUFFER_SIZE);
-}
-
-/*************************************************************************/
-
-/**
- * This method initializes a new <code>BufferedOutputStream</code> instance
- * that will write to the specified subordinate <code>OutputStream</code>
- * and which will use the specified buffer size
- *
- * @param out The underlying <code>OutputStream</code> to write data to
- * @param size The size of the internal buffer
- */
-public
-BufferedOutputStream(OutputStream out, int size)
-{
- super(out);
-
- buf = new byte[size];
-}
-
-/*************************************************************************/
-
-/*
- * Instance Methods
- */
-
-/**
- * This method causes any currently buffered bytes to be immediately
- * written to the underlying output stream.
- *
- * @exception IOException If an error occurs
+ /*
+ * Class Variables
+ */
+
+ /**
+ * This is the default buffer size
+ */
+ private static final int DEFAULT_BUFFER_SIZE = 512;
+
+ /*************************************************************************/
+
+ /*
+ * Instance Variables
+ */
+
+ /**
+ * This is the internal byte array used for buffering output before
+ * writing it.
+ */
+ protected byte[] buf;
+
+ /**
+ * This is the number of bytes that are currently in the buffer and
+ * are waiting to be written to the underlying stream. It always points to
+ * the index into the buffer where the next byte of data will be stored
+ */
+ protected int count;
+
+ /*************************************************************************/
+
+ /*
+ * Constructors
+ */
+
+ /**
+ * This method initializes a new <code>BufferedOutputStream</code> instance
+ * that will write to the specified subordinate <code>OutputStream</code>
+ * and which will use a default buffer size of 512 bytes.
+ *
+ * @param out The underlying <code>OutputStream</code> to write data to
+ */
+ public BufferedOutputStream(OutputStream out)
+ {
+ this(out, DEFAULT_BUFFER_SIZE);
+ }
+
+ /*************************************************************************/
+
+ /**
+ * This method initializes a new <code>BufferedOutputStream</code> instance
+ * that will write to the specified subordinate <code>OutputStream</code>
+ * and which will use the specified buffer size
+ *
+ * @param out The underlying <code>OutputStream</code> to write data to
+ * @param size The size of the internal buffer
+ */
+ public BufferedOutputStream(OutputStream out, int size)
+ {
+ super(out);
+
+ buf = new byte[size];
+ }
+
+ /*************************************************************************/
+
+ /*
+ * Instance Methods
+ */
+
+ /**
+ * This method causes any currently buffered bytes to be immediately
+ * written to the underlying output stream.
+ *
+ * @exception IOException If an error occurs
+ */
+ public synchronized void flush() throws IOException
+ {
+ if (count == 0)
+ return;
+
+ out.write(buf, 0, count);
+ count = 0;
+ out.flush();
+ }
+
+ /*************************************************************************/
+
+ /*
+ * This method flushes any remaining buffered bytes then closes the
+ * underlying output stream. Any further attempts to write to this stream
+ * may throw an exception
+ *
+ public synchronized void close() throws IOException
+ {
+ flush();
+ out.close();
+ }
*/
-public synchronized void
-flush() throws IOException
-{
- if (count == 0)
- return;
-
- out.write(buf, 0, count);
- count = 0;
- out.flush();
-}
-
-/*************************************************************************/
-
-/*
- * This method flushes any remaining buffered bytes then closes the
- * underlying output stream. Any further attempts to write to this stream
- * may throw an exception
- *
-public synchronized void
-close() throws IOException
-{
- flush();
- out.close();
-}
-*/
-
-/*************************************************************************/
-
-/*
- * This method runs when the object is garbage collected. It is
- * responsible for ensuring that all buffered bytes are written and
- * for closing the underlying stream.
- *
- * @exception IOException If an error occurs (ignored by the Java runtime)
- *
-protected void
-finalize() throws IOException
-{
- close();
-}
-*/
-/*************************************************************************/
-
-/**
- * This method writes a single byte of data. This will be written to the
- * buffer instead of the underlying data source. However, if the buffer
- * is filled as a result of this write request, it will be flushed to the
- * underlying output stream.
- *
- * @param b The byte of data to be written, passed as an int
- *
- * @exception IOException If an error occurs
+ /*************************************************************************/
+
+ /*
+ * This method runs when the object is garbage collected. It is
+ * responsible for ensuring that all buffered bytes are written and
+ * for closing the underlying stream.
+ *
+ * @exception IOException If an error occurs (ignored by the Java runtime)
+ *
+ protected void finalize() throws IOException
+ {
+ close();
+ }
*/
-public synchronized void
-write(int b) throws IOException
-{
- if (count == buf.length)
- flush();
-
- buf[count] = (byte)(b & 0xFF);
- ++count;
-}
-
-/*************************************************************************/
-/**
- * This method writes <code>len</code> bytes from the byte array
- * <code>buf</code> starting at position <code>offset</code> in the buffer.
- * These bytes will be written to the internal buffer. However, if this
- * write operation fills the buffer, the buffer will be flushed to the
- * underlying output stream.
- *
- * @param buf The array of bytes to write.
- * @param offset The index into the byte array to start writing from.
- * @param len The number of bytes to write.
- *
- * @exception IOException If an error occurs
- */
-public synchronized void
-write(byte[] buf, int offset, int len) throws IOException
-{
- // Buffer can hold everything. Note that the case where LEN < 0
- // is automatically handled by the downstream write.
- if (len < (this.buf.length - count))
- {
- System.arraycopy(buf, offset, this.buf, count, len);
- count += len;
- }
- else
- {
- // The write was too big. So flush the buffer and write the new
- // bytes directly to the underlying stream, per the JDK 1.2
- // docs.
+ /*************************************************************************/
+
+ /**
+ * This method writes a single byte of data. This will be written to the
+ * buffer instead of the underlying data source. However, if the buffer
+ * is filled as a result of this write request, it will be flushed to the
+ * underlying output stream.
+ *
+ * @param b The byte of data to be written, passed as an int
+ *
+ * @exception IOException If an error occurs
+ */
+ public synchronized void write(int b) throws IOException
+ {
+ if (count == buf.length)
flush();
- out.write (buf, offset, len);
- }
-}
+
+ buf[count] = (byte)(b & 0xFF);
+ ++count;
+ }
+
+ /*************************************************************************/
+
+ /**
+ * This method writes <code>len</code> bytes from the byte array
+ * <code>buf</code> starting at position <code>offset</code> in the buffer.
+ * These bytes will be written to the internal buffer. However, if this
+ * write operation fills the buffer, the buffer will be flushed to the
+ * underlying output stream.
+ *
+ * @param buf The array of bytes to write.
+ * @param offset The index into the byte array to start writing from.
+ * @param len The number of bytes to write.
+ *
+ * @exception IOException If an error occurs
+ */
+ public synchronized void write(byte[] buf, int offset, int len)
+ throws IOException
+ {
+ // Buffer can hold everything. Note that the case where LEN < 0
+ // is automatically handled by the downstream write.
+ if (len < (this.buf.length - count))
+ {
+ System.arraycopy(buf, offset, this.buf, count, len);
+ count += len;
+ }
+ else
+ {
+ // The write was too big. So flush the buffer and write the new
+ // bytes directly to the underlying stream, per the JDK 1.2
+ // docs.
+ flush();
+ out.write (buf, offset, len);
+ }
+ }
} // class BufferedOutputStream
+
/* DataInput.java -- Interface for reading data from a stream
- Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+ Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
* "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status: Believed complete and correct.
- */
+ * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
+ * Status: Believed complete and correct. */
/**
* This interface is implemented by classes that can data from streams
public interface DataInput
{
-/**
- * This method reads a Java boolean value from an input stream. It does
- * so by reading a single byte of data. If that byte is zero, then the
- * value returned is <code>false</code>. If the byte is non-zero, then
- * the value returned is <code>true</code>.
- * <p>
- * This method can read a <code>boolean</code> written by an object
- * implementing the <code>writeBoolean()</code> method in the
- * <code>DataOutput</code> interface.
- *
- * @return The <code>boolean</code> value read
- *
- * @exception EOFException If end of file is reached before reading the boolean
- * @exception IOException If any other error occurs
- */
-boolean
-readBoolean() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java byte value from an input stream. The value
- * is in the range of -128 to 127.
- * <p>
- * This method can read a <code>byte</code> written by an object
- * implementing the
- * <code>writeByte()</code> method in the <code>DataOutput</code> interface.
- * <p>
- * @return The <code>byte</code> value read
- *
- * @exception EOFException If end of file is reached before reading the byte
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-byte
-readByte() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads 8 unsigned bits into a Java <code>int</code> value from
- * the stream. The value returned is in the range of 0 to 255.
- * <p>
- * This method can read an unsigned byte written by an object implementing the
- * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code>
- * interface.
- *
- * @return The unsigned bytes value read as a Java <code>int</code>.
- *
- * @exception EOFException If end of file is reached before reading the value
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-int
-readUnsignedByte() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java <code>char</code> value from an input stream.
- * It operates by reading two bytes from the stream and converting them to
- * a single 16-bit Java <code>char</code>. The two bytes are stored most
- * significant byte first (i.e., "big endian") regardless of the native
- * host byte ordering.
- * <p>
- * As an example, if <code>byte1</code> and <code>byte2</code> represent the
- * first and second byte read from the stream respectively, they will be
- * transformed to a <code>char</code> in the following manner:
- * <p>
- * <code>(char)((byte1 << 8) + byte2)</code>
- * <p>
- * This method can read a <code>char</code> written by an object implementing
- * the
- * <code>writeChar()</code> method in the <code>DataOutput</code> interface.
- *
- * @return The <code>char</code> value read
- *
- * @exception EOFException If end of file is reached before reading the char
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-char
-readChar() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a signed 16-bit value into a Java in from the stream.
- * It operates by reading two bytes from the stream and converting them to
- * a single 16-bit Java <code>short</code>. The two bytes are stored most
- * significant byte first (i.e., "big endian") regardless of the native
- * host byte ordering.
- * <p>
- * As an example, if <code>byte1</code> and <code>byte2</code> represent the
- * first and second byte read from the stream respectively, they will be
- * transformed to a <code>short</code> in the following manner:
- * <p>
- * <code>(short)((byte1 << 8) + byte2)</code>
- * <p>
- * The value returned is in the range of -32768 to 32767.
- * <p>
- * This method can read a <code>short</code> written by an object implementing
- * the <code>writeShort()</code> method in the <code>DataOutput</code>
- * interface.
- *
- * @return The <code>short</code> value read
- *
- * @exception EOFException If end of file is reached before reading the value
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-short
-readShort() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads 16 unsigned bits into a Java int value from the stream.
- * It operates by reading two bytes from the stream and converting them to
- * a single Java <code>int</code>. The two bytes are stored most
- * significant byte first (i.e., "big endian") regardless of the native
- * host byte ordering.
- * <p>
- * As an example, if <code>byte1</code> and <code>byte2</code> represent the
- * first and second byte read from the stream respectively, they will be
- * transformed to an <code>int</code> in the following manner:
- * <p>
- * <code>(int)((byte1 << 8) + byte2)</code>
- * <p>
- * The value returned is in the range of 0 to 65535.
- * <p>
- * This method can read an unsigned short written by an object implementing
- * the <code>writeUnsignedShort()</code> method in the <code>DataOutput</code>
- * interface.
- *
- * @return The unsigned short value read as a Java <code>int</code>.
- *
- * @exception EOFException If end of file is reached before reading the value
- * @exception IOException If any other error occurs
- */
-int
-readUnsignedShort() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java <code>int</code> value from an input stream
- * It operates by reading four bytes from the stream and converting them to
- * a single Java <code>int</code>. The bytes are stored most
- * significant byte first (i.e., "big endian") regardless of the native
- * host byte ordering.
- * <p>
- * As an example, if <code>byte1</code> through <code>byte4</code> represent
- * the first four bytes read from the stream, they will be
- * transformed to an <code>int</code> in the following manner:
- * <p>
- * <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code>
- * <p>
- The value returned is in the range of -2147483648 to 2147483647.
- * <p>
- * This method can read an <code>int</code> written by an object implementing
- * the <code>writeInt()</code> method in the <code>DataOutput</code> interface.
- *
- * @return The <code>int</code> value read
- *
- * @exception EOFException If end of file is reached before reading the int
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-int
-readInt() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java <code>long</code> value from an input stream
- * It operates by reading eight bytes from the stream and converting them to
- * a single Java <code>long</code>. The bytes are stored most
- * significant byte first (i.e., "big endian") regardless of the native
- * host byte ordering.
- * <p>
- * As an example, if <code>byte1</code> through <code>byte8</code> represent
- * the first eight bytes read from the stream, they will be
- * transformed to an <code>long</code> in the following manner:
- * <p>
- * <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) +
- * (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9))
- * </code>
- * <p>
- * The value returned is in the range of -9223372036854775808 to
- * 9223372036854775807.
- * <p>
- * This method can read an <code>long</code> written by an object implementing
- * the <code>writeLong()</code> method in the <code>DataOutput</code>
- * interface.
- *
- * @return The <code>long</code> value read
- *
- * @exception EOFException If end of file is reached before reading the long
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-long
-readLong() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java float value from an input stream. It operates
- * by first reading an <code>int</code> value from the stream by calling the
- * <code>readInt()</code> method in this interface, then converts that
- * <code>int</code> to a <code>float</code> using the
- * <code>intBitsToFloat</code> method in the class
- * <code>java.lang.Float</code>.
- * <p>
- * This method can read a <code>float</code> written by an object implementing
- * the <code>writeFloat()</code> method in the <code>DataOutput</code>
- * interface.
- *
- * @return The <code>float</code> value read
- *
- * @exception EOFException If end of file is reached before reading the float
- * @exception IOException If any other error occurs
- *
- * @see java.lang.Float
- * @see DataOutput
- */
-float
-readFloat() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a Java double value from an input stream. It operates
- * by first reading a <code>long</code> value from the stream by calling the
- * <code>readLong()</code> method in this interface, then converts that
- * <code>long</code> to a <code>double</code> using the
- * <code>longBitsToDouble</code> method in the class
- * <code>java.lang.Double</code>.
- * <p>
- * This method can read a <code>double</code> written by an object
- * implementing the <code>writeDouble()</code> method in the
- * <code>DataOutput</code> interface.
- *
- * @return The <code>double</code> value read
- *
- * @exception EOFException If end of file is reached before reading the double
- * @exception IOException If any other error occurs
- *
- * @see java.lang.Double
- * @see DataOutput
- */
-double
-readDouble() throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads the next line of text data from an input stream.
- * It operates by reading bytes and converting those bytes to <code>char</code>
- * values by treating the byte read as the low eight bits of the
- * <code>char</code> and using 0 as the high eight bits. Because of this,
- * it does not support the full 16-bit Unicode character set.
- * <P>
- * The reading of bytes ends when either the end of file or a line terminator
- * is encountered. The bytes read are then returned as a <code>String</code>.
- * A line terminator is a byte sequence consisting of either
- * <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination
- * charaters are discarded and are not returned as part of the string.
- * <p>
- * This method can read data that was written by an object implementing the
- * <code>writeLine()</code> method in <code>DataOutput</code>.
- *
- * @return The line read as a <code>String</code>
- *
- * @exception IOException If an error occurs
- *
- * @see DataOutput
- */
-String
-readLine() throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads a <code>String</code> from an input stream that is
- * encoded in a modified UTF-8 format. This format has a leading two byte
- * sequence that contains the remaining number of bytes to read. This two byte
- * sequence is read using the <code>readUnsignedShort()</code> method of this
- * interface.
- *
- * After the number of remaining bytes have been determined, these bytes
- * are read an transformed into <code>char</code> values. These
- * <code>char</code> values are encoded in the stream using either a one, two,
- * or three byte format.
- * The particular format in use can be determined by examining the first
- * byte read.
- * <p>
- * If the first byte has a high order bit of 0, then
- * that character consists on only one byte. This character value consists
- * of seven bits that are at positions 0 through 6 of the byte. As an
- * example, if <code>byte1</code> is the byte read from the stream, it would
- * be converted to a <code>char</code> like so:
- * <p>
- * <code>(char)byte1</code>
- * <p>
- * If the first byte has 110 as its high order bits, then the
- * character consists of two bytes. The bits that make up the character
- * value are in positions 0 through 4 of the first byte and bit positions
- * 0 through 5 of the second byte. (The second byte should have
- * 10 as its high order bits). These values are in most significant
- * byte first (i.e., "big endian") order.
- * <p>
- * As an example, if <code>byte1</code> and <code>byte2</code> are the first
- * two bytes read respectively, and the high order bits of them match the
- * patterns which indicate a two byte character encoding, then they would be
- * converted to a Java <code>char</code> like so:
- * <p>
- * <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code>
- * <p>
- * If the first byte has a 1110 as its high order bits, then the
- * character consists of three bytes. The bits that make up the character
- * value are in positions 0 through 3 of the first byte and bit positions
- * 0 through 5 of the other two bytes. (The second and third bytes should
- * have 10 as their high order bits). These values are in most
- * significant byte first (i.e., "big endian") order.
- * <p>
- * As an example, if <code>byte1</code>, <code>byte2</code>, and
- * <code>byte3</code> are the three bytes read, and the high order bits of
- * them match the patterns which indicate a three byte character encoding,
- * then they would be converted to a Java <code>char</code> like so:
- *
- * <code>
- * (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F))
- * </code>
- *
- * Note that all characters are encoded in the method that requires the
- * fewest number of bytes with the exception of the character with the
- * value of <code>\<llll>u0000</code> which is encoded as two bytes. This is
- * a modification of the UTF standard used to prevent C language style
- * <code>NUL</code> values from appearing in the byte stream.
- * <p>
- * This method can read data that was written by an object implementing the
- * <code>writeUTF()</code> method in <code>DataOutput</code>.
- *
- * @returns The <code>String</code> read
- *
- * @exception EOFException If end of file is reached before reading the String
- * @exception UTFDataFormatException If the data is not in UTF-8 format
- * @exception IOException If any other error occurs
- *
- * @see DataOutput
- */
-String
-readUTF() throws EOFException, UTFDataFormatException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads raw bytes into the passed array until the array is
- * full. Note that this method blocks until the data is available and
- * throws an exception if there is not enough data left in the stream to
- * fill the buffer
- *
- * @param buf The buffer into which to read the data
- *
- * @exception EOFException If end of file is reached before filling the buffer
- * @exception IOException If any other error occurs
- */
-void
-readFully(byte[] buf) throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method reads raw bytes into the passed array <code>buf</code> starting
- * <code>offset</code> bytes into the buffer. The number of bytes read will be
- * exactly <code>len</code>. Note that this method blocks until the data is
- * available and * throws an exception if there is not enough data left in
- * the stream to read <code>len</code> bytes.
- *
- * @param buf The buffer into which to read the data
- * @param offset The offset into the buffer to start storing data
- * @param len The number of bytes to read into the buffer
- *
- * @exception EOFException If end of file is reached before filling the buffer
- * @exception IOException If any other error occurs
- */
-void
-readFully(byte[] buf, int offset, int len) throws EOFException, IOException;
-
-/*************************************************************************/
-
-/**
- * This method skips and discards the specified number of bytes in an
- * input stream
- *
- * @param num_bytes The number of bytes to skip
- *
- * @return The number of bytes actually skipped, which will always be
- * <code>num_bytes</code>
- *
- * @exception EOFException If end of file is reached before all bytes can be
- * skipped
- * @exception IOException If any other error occurs
- */
-int
-skipBytes(int n) throws EOFException, IOException;
+ /**
+ * This method reads a Java boolean value from an input stream. It does
+ * so by reading a single byte of data. If that byte is zero, then the
+ * value returned is <code>false</code>. If the byte is non-zero, then
+ * the value returned is <code>true</code>.
+ * <p>
+ * This method can read a <code>boolean</code> written by an object
+ * implementing the <code>writeBoolean()</code> method in the
+ * <code>DataOutput</code> interface.
+ *
+ * @return The <code>boolean</code> value read
+ *
+ * @exception EOFException If end of file is reached before
+ * reading the boolean
+ * @exception IOException If any other error occurs
+ */
+ boolean readBoolean() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java byte value from an input stream. The value
+ * is in the range of -128 to 127.
+ * <p>
+ * This method can read a <code>byte</code> written by an object
+ * implementing the
+ * <code>writeByte()</code> method in the <code>DataOutput</code> interface.
+ * <p>
+ * @return The <code>byte</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the byte
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ byte readByte() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads 8 unsigned bits into a Java <code>int</code> value from
+ * the stream. The value returned is in the range of 0 to 255.
+ * <p>
+ * This method can read an unsigned byte written by an object
+ * implementing the
+ * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code>
+ * interface.
+ *
+ * @return The unsigned bytes value read as a Java <code>int</code>.
+ *
+ * @exception EOFException If end of file is reached before reading the value
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ int readUnsignedByte() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java <code>char</code> value from an input stream.
+ * It operates by reading two bytes from the stream and converting them to
+ * a single 16-bit Java <code>char</code>. The two bytes are stored most
+ * significant byte first (i.e., "big endian") regardless of the native
+ * host byte ordering.
+ * <p>
+ * As an example, if <code>byte1</code> and <code>byte2</code> represent the
+ * first and second byte read from the stream respectively, they will be
+ * transformed to a <code>char</code> in the following manner:
+ * <p>
+ * <code>(char)((byte1 << 8) + byte2)</code>
+ * <p>
+ * This method can read a <code>char</code> written by an object implementing
+ * the
+ * <code>writeChar()</code> method in the <code>DataOutput</code> interface.
+ *
+ * @return The <code>char</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the char
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ char readChar() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a signed 16-bit value into a Java in from the stream.
+ * It operates by reading two bytes from the stream and converting them to
+ * a single 16-bit Java <code>short</code>. The two bytes are stored most
+ * significant byte first (i.e., "big endian") regardless of the native
+ * host byte ordering.
+ * <p>
+ * As an example, if <code>byte1</code> and <code>byte2</code> represent the
+ * first and second byte read from the stream respectively, they will be
+ * transformed to a <code>short</code> in the following manner:
+ * <p>
+ * <code>(short)((byte1 << 8) + byte2)</code>
+ * <p>
+ * The value returned is in the range of -32768 to 32767.
+ * <p>
+ * This method can read a <code>short</code> written by an object
+ * implementing
+ * the <code>writeShort()</code> method in the <code>DataOutput</code>
+ * interface.
+ *
+ * @return The <code>short</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the value
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ short readShort() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads 16 unsigned bits into a Java int value from the stream.
+ * It operates by reading two bytes from the stream and converting them to
+ * a single Java <code>int</code>. The two bytes are stored most
+ * significant byte first (i.e., "big endian") regardless of the native
+ * host byte ordering.
+ * <p>
+ * As an example, if <code>byte1</code> and <code>byte2</code> represent the
+ * first and second byte read from the stream respectively, they will be
+ * transformed to an <code>int</code> in the following manner:
+ * <p>
+ * <code>(int)((byte1 << 8) + byte2)</code>
+ * <p>
+ * The value returned is in the range of 0 to 65535.
+ * <p>
+ * This method can read an unsigned short written by an object implementing
+ * the <code>writeUnsignedShort()</code> method in the
+ * <code>DataOutput</code>
+ * interface.
+ *
+ * @return The unsigned short value read as a Java <code>int</code>.
+ *
+ * @exception EOFException If end of file is reached before reading
+ * the value
+ * @exception IOException If any other error occurs
+ */
+ int readUnsignedShort() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java <code>int</code> value from an input stream
+ * It operates by reading four bytes from the stream and converting them to
+ * a single Java <code>int</code>. The bytes are stored most
+ * significant byte first (i.e., "big endian") regardless of the native
+ * host byte ordering.
+ * <p>
+ * As an example, if <code>byte1</code> through <code>byte4</code> represent
+ * the first four bytes read from the stream, they will be
+ * transformed to an <code>int</code> in the following manner:
+ * <p>
+ * <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code>
+ * <p>
+ * The value returned is in the range of -2147483648 to 2147483647.
+ * <p>
+ * This method can read an <code>int</code> written by an object
+ * implementing the <code>writeInt()</code> method in the
+ * <code>DataOutput</code> interface.
+ *
+ * @return The <code>int</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the int
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ int readInt() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java <code>long</code> value from an input stream
+ * It operates by reading eight bytes from the stream and converting them to
+ * a single Java <code>long</code>. The bytes are stored most
+ * significant byte first (i.e., "big endian") regardless of the native
+ * host byte ordering.
+ * <p>
+ * As an example, if <code>byte1</code> through <code>byte8</code> represent
+ * the first eight bytes read from the stream, they will be
+ * transformed to an <code>long</code> in the following manner:
+ * <p>
+ * <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) +
+ * (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9))
+ * </code>
+ * <p>
+ * The value returned is in the range of -9223372036854775808 to
+ * 9223372036854775807.
+ * <p>
+ * This method can read an <code>long</code> written by an object
+ * implementing the <code>writeLong()</code> method in the
+ * <code>DataOutput</code> interface.
+ *
+ * @return The <code>long</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the long
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ long readLong() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java float value from an input stream. It operates
+ * by first reading an <code>int</code> value from the stream by calling the
+ * <code>readInt()</code> method in this interface, then converts that
+ * <code>int</code> to a <code>float</code> using the
+ * <code>intBitsToFloat</code> method in the class
+ * <code>java.lang.Float</code>.
+ * <p>
+ * This method can read a <code>float</code> written by an object
+ * implementing
+ * the <code>writeFloat()</code> method in the <code>DataOutput</code>
+ * interface.
+ *
+ * @return The <code>float</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the
+ * float
+ * @exception IOException If any other error occurs
+ *
+ * @see java.lang.Float
+ * @see DataOutput
+ */
+ float readFloat() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a Java double value from an input stream. It operates
+ * by first reading a <code>long</code> value from the stream by calling the
+ * <code>readLong()</code> method in this interface, then converts that
+ * <code>long</code> to a <code>double</code> using the
+ * <code>longBitsToDouble</code> method in the class
+ * <code>java.lang.Double</code>.
+ * <p>
+ * This method can read a <code>double</code> written by an object
+ * implementing the <code>writeDouble()</code> method in the
+ * <code>DataOutput</code> interface.
+ *
+ * @return The <code>double</code> value read
+ *
+ * @exception EOFException If end of file is reached before reading the
+ * double
+ * @exception IOException If any other error occurs
+ *
+ * @see java.lang.Double
+ * @see DataOutput
+ */
+ double readDouble() throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads the next line of text data from an input stream.
+ * It operates by reading bytes and converting those bytes to
+ * <code>char</code>
+ * values by treating the byte read as the low eight bits of the
+ * <code>char</code> and using 0 as the high eight bits. Because of this,
+ * it does not support the full 16-bit Unicode character set.
+ * <P>
+ * The reading of bytes ends when either the end of file or a line terminator
+ * is encountered. The bytes read are then returned as a
+ * <code>String</code>.
+ * A line terminator is a byte sequence consisting of either
+ * <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination
+ * charaters are discarded and are not returned as part of the string.
+ * <p>
+ * This method can read data that was written by an object implementing the
+ * <code>writeLine()</code> method in <code>DataOutput</code>.
+ *
+ * @return The line read as a <code>String</code>
+ *
+ * @exception IOException If an error occurs
+ *
+ * @see DataOutput
+ */
+ String readLine() throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads a <code>String</code> from an input stream that is
+ * encoded in a modified UTF-8 format. This format has a leading two byte
+ * sequence that contains the remaining number of bytes to read.
+ * This two byte
+ * sequence is read using the <code>readUnsignedShort()</code> method of this
+ * interface.
+ *
+ * After the number of remaining bytes have been determined, these bytes
+ * are read an transformed into <code>char</code> values. These
+ * <code>char</code> values are encoded in the stream using either a one,
+ * two, or three byte format.
+ * The particular format in use can be determined by examining the first
+ * byte read.
+ * <p>
+ * If the first byte has a high order bit of 0, then
+ * that character consists on only one byte. This character value consists
+ * of seven bits that are at positions 0 through 6 of the byte. As an
+ * example, if <code>byte1</code> is the byte read from the stream, it would
+ * be converted to a <code>char</code> like so:
+ * <p>
+ * <code>(char)byte1</code>
+ * <p>
+ * If the first byte has 110 as its high order bits, then the
+ * character consists of two bytes. The bits that make up the character
+ * value are in positions 0 through 4 of the first byte and bit positions
+ * 0 through 5 of the second byte. (The second byte should have
+ * 10 as its high order bits). These values are in most significant
+ * byte first (i.e., "big endian") order.
+ * <p>
+ * As an example, if <code>byte1</code> and <code>byte2</code> are the first
+ * two bytes read respectively, and the high order bits of them match the
+ * patterns which indicate a two byte character encoding, then they would be
+ * converted to a Java <code>char</code> like so:
+ * <p>
+ * <code>(char)(((byte1 & 0x1F) << 6) + (byte2 & 0x3F))</code>
+ * <p>
+ * If the first byte has a 1110 as its high order bits, then the
+ * character consists of three bytes. The bits that make up the character
+ * value are in positions 0 through 3 of the first byte and bit positions
+ * 0 through 5 of the other two bytes. (The second and third bytes should
+ * have 10 as their high order bits). These values are in most
+ * significant byte first (i.e., "big endian") order.
+ * <p>
+ * As an example, if <code>byte1</code>, <code>byte2</code>, and
+ * <code>byte3</code> are the three bytes read, and the high order bits of
+ * them match the patterns which indicate a three byte character encoding,
+ * then they would be converted to a Java <code>char</code> like so:
+ *
+ * <code>
+ * (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F))
+ * </code>
+ *
+ * Note that all characters are encoded in the method that requires the
+ * fewest number of bytes with the exception of the character with the
+ * value of <code>\<llll>u0000</code> which is encoded as two bytes.
+ * This is a modification of the UTF standard used to prevent C language
+ * style <code>NUL</code> values from appearing in the byte stream.
+ * <p>
+ * This method can read data that was written by an object implementing the
+ * <code>writeUTF()</code> method in <code>DataOutput</code>.
+ *
+ * @returns The <code>String</code> read
+ *
+ * @exception EOFException If end of file is reached before reading the
+ * String
+ * @exception UTFDataFormatException If the data is not in UTF-8 format
+ * @exception IOException If any other error occurs
+ *
+ * @see DataOutput
+ */
+ String readUTF() throws EOFException, UTFDataFormatException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads raw bytes into the passed array until the array is
+ * full. Note that this method blocks until the data is available and
+ * throws an exception if there is not enough data left in the stream to
+ * fill the buffer
+ *
+ * @param buf The buffer into which to read the data
+ *
+ * @exception EOFException If end of file is reached before filling the
+ * buffer
+ * @exception IOException If any other error occurs
+ */
+ void readFully(byte[] buf) throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method reads raw bytes into the passed array <code>buf</code>
+ * starting
+ * <code>offset</code> bytes into the buffer. The number of bytes read
+ * will be
+ * exactly <code>len</code>. Note that this method blocks until the data is
+ * available and * throws an exception if there is not enough data left in
+ * the stream to read <code>len</code> bytes.
+ *
+ * @param buf The buffer into which to read the data
+ * @param offset The offset into the buffer to start storing data
+ * @param len The number of bytes to read into the buffer
+ *
+ * @exception EOFException If end of file is reached before filling the
+ * buffer
+ * @exception IOException If any other error occurs
+ */
+ void readFully(byte[] buf, int offset, int len)
+ throws EOFException, IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method skips and discards the specified number of bytes in an
+ * input stream
+ *
+ * @param num_bytes The number of bytes to skip
+ *
+ * @return The number of bytes actually skipped, which will always be
+ * <code>num_bytes</code>
+ *
+ * @exception EOFException If end of file is reached before all bytes can be
+ * skipped
+ * @exception IOException If any other error occurs
+ */
+ int skipBytes(int n) throws EOFException, IOException;
} // interface DataInput
public interface DataOutput
{
-/**
- * This method writes a Java boolean value to an output stream
- *
- * @param value The boolean value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeBoolean(boolean value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java byte value to an output stream
- *
- * @param value The int value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeByte(int value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java char value to an output stream
- *
- * @param value The char value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeChar(int value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java int value to an output stream as a 16 bit value
- *
- * @param value The int value to write as a 16-bit value
- *
- * @exception IOException If an error occurs
- */
-void
-writeShort(int value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java int value to an output stream
- *
- * @param value The int value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeInt(int value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java long value to an output stream
- *
- * @param value The long value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeLong(long value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java float value to an output stream
- *
- * @param value The float value to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeFloat(float value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a Java double value to an output stream
- *
- * @param value The double value to write
- *
- * @exception IOException If any other error occurs
- */
-void
-writeDouble(double value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a String to an output stream as an array of bytes
- *
- * @param value The String to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeBytes(String value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a String to an output stream as an array of char's
- *
- * @param value The String to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeChars(String value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes a String to an output stream encoded in
- * UTF-8 format.
- *
- * @param value The String to write
- *
- * @exception IOException If an error occurs
- */
-void
-writeUTF(String value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes an 8-bit value (passed into the method as a Java
- * int) to an output stream.
- *
- * @param value The byte to write to the output stream
- *
- * @exception IOException If an error occurs
- */
-void
-write(int value) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes the raw byte array passed in to the output stream.
- *
- * @param buf The byte array to write
- *
- * @exception IOException If an error occurs
- */
-void
-write(byte[] buf) throws IOException;
-
-/*************************************************************************/
-
-/**
- * This method writes raw bytes from the passed array <code>buf</code> starting
- * <code>offset</code> bytes into the buffer. The number of bytes written will be
- * exactly <code>len</code>.
- *
- * @param buf The buffer from which to write the data
- * @param offset The offset into the buffer to start writing data from
- * @param len The number of bytes to write from the buffer to the output stream
- *
- * @exception IOException If any other error occurs
- */
-void
-write(byte[] buf, int offset, int len) throws IOException;
+ /**
+ * This method writes a Java boolean value to an output stream
+ *
+ * @param value The boolean value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeBoolean(boolean value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java byte value to an output stream
+ *
+ * @param value The int value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeByte(int value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java char value to an output stream
+ *
+ * @param value The char value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeChar(int value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java int value to an output stream as a 16 bit value
+ *
+ * @param value The int value to write as a 16-bit value
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeShort(int value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java int value to an output stream
+ *
+ * @param value The int value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeInt(int value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java long value to an output stream
+ *
+ * @param value The long value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeLong(long value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java float value to an output stream
+ *
+ * @param value The float value to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeFloat(float value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a Java double value to an output stream
+ *
+ * @param value The double value to write
+ *
+ * @exception IOException If any other error occurs
+ */
+ void writeDouble(double value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a String to an output stream as an array of bytes
+ *
+ * @param value The String to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeBytes(String value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a String to an output stream as an array of char's
+ *
+ * @param value The String to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeChars(String value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes a String to an output stream encoded in
+ * UTF-8 format.
+ *
+ * @param value The String to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void writeUTF(String value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes an 8-bit value (passed into the method as a Java
+ * int) to an output stream.
+ *
+ * @param value The byte to write to the output stream
+ *
+ * @exception IOException If an error occurs
+ */
+ void write(int value) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes the raw byte array passed in to the output stream.
+ *
+ * @param buf The byte array to write
+ *
+ * @exception IOException If an error occurs
+ */
+ void write(byte[] buf) throws IOException;
+
+ /*************************************************************************/
+
+ /**
+ * This method writes raw bytes from the passed array <code>buf</code>
+ * starting
+ * <code>offset</code> bytes into the buffer. The number of bytes
+ * written will be * exactly <code>len</code>.
+ *
+ * @param buf The buffer from which to write the data
+ * @param offset The offset into the buffer to start writing data from
+ * @param len The number of bytes to write from the buffer to the output
+ * stream
+ *
+ * @exception IOException If any other error occurs
+ */
+ void write(byte[] buf, int offset, int len) throws IOException;
} // interface DataOutput
+
git://gcc.gnu.org / gcc.git / commitdiff