diff options
Diffstat (limited to 'libjava/java/io')
26 files changed, 729 insertions, 969 deletions
diff --git a/libjava/java/io/BufferedOutputStream.java b/libjava/java/io/BufferedOutputStream.java index c2f9f6ba955..137dec5496c 100644 --- a/libjava/java/io/BufferedOutputStream.java +++ b/libjava/java/io/BufferedOutputStream.java @@ -50,62 +50,44 @@ package java.io; */ 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 default buffer size */ + private static final int DEFAULT_BUFFER_SIZE = 512; /** - * This is the internal byte array used for buffering output before - * writing it. - */ + * 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 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; /** - * 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 - */ + * 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 - */ + * 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); @@ -113,18 +95,12 @@ public class BufferedOutputStream extends FilterOutputStream 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 - */ + * 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) @@ -135,13 +111,11 @@ public class BufferedOutputStream extends FilterOutputStream 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 - * + /** + * 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(); @@ -149,33 +123,29 @@ public class BufferedOutputStream extends FilterOutputStream } */ - /*************************************************************************/ - - /* - * 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) - * + /** + * 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 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) @@ -185,21 +155,19 @@ public class BufferedOutputStream extends FilterOutputStream ++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 - */ + * 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 { diff --git a/libjava/java/io/BufferedReader.java b/libjava/java/io/BufferedReader.java index a40015b32d6..df53765d0b0 100644 --- a/libjava/java/io/BufferedReader.java +++ b/libjava/java/io/BufferedReader.java @@ -44,19 +44,19 @@ package java.io; */ /** - * This subclass of <code>FilterReader</code> buffers input from an - * underlying implementation to provide a possibly more efficient read - * mechanism. It maintains the buffer and buffer state in instance - * variables that are available to subclasses. The default buffer size - * of 512 chars can be overridden by the creator of the stream. - * <p> - * This class also implements mark/reset functionality. It is capable - * of remembering any number of input chars, to the limits of - * system memory or the size of <code>Integer.MAX_VALUE</code> - * - * @author Per Bothner <bothner@cygnus.com> - * @author Aaron M. Renn <arenn@urbanophile.com> - */ + * This subclass of <code>FilterReader</code> buffers input from an + * underlying implementation to provide a possibly more efficient read + * mechanism. It maintains the buffer and buffer state in instance + * variables that are available to subclasses. The default buffer size + * of 512 chars can be overridden by the creator of the stream. + * <p> + * This class also implements mark/reset functionality. It is capable + * of remembering any number of input chars, to the limits of + * system memory or the size of <code>Integer.MAX_VALUE</code> + * + * @author Per Bothner <bothner@cygnus.com> + * @author Aaron M. Renn <arenn@urbanophile.com> + */ public class BufferedReader extends Reader { Reader in; @@ -99,13 +99,13 @@ public class BufferedReader extends Reader } /** - * Create a new <code>BufferedReader</code> that will read from the - * specified subordinate stream with a buffer size that is specified by the - * caller. - * - * @param in The subordinate stream to read from - * @param bufsize The buffer size to use - */ + * Create a new <code>BufferedReader</code> that will read from the + * specified subordinate stream with a buffer size that is specified by the + * caller. + * + * @param in The subordinate stream to read from + * @param bufsize The buffer size to use + */ public BufferedReader(Reader in, int size) { super(in.lock); @@ -114,10 +114,10 @@ public class BufferedReader extends Reader } /** - * This method closes the stream - * - * @exception IOException If an error occurs - */ + * This method closes the stream + * + * @exception IOException If an error occurs + */ public void close() throws IOException { synchronized (lock) @@ -130,36 +130,36 @@ public class BufferedReader extends Reader } /** - * Returns <code>true</code> to indicate that this class supports mark/reset - * functionality. - * - * @return <code>true</code> - */ + * Returns <code>true</code> to indicate that this class supports mark/reset + * functionality. + * + * @return <code>true</code> + */ public boolean markSupported() { return true; } /** - * Mark a position in the input to which the stream can be - * "reset" by calling the <code>reset()</code> method. The parameter - * <code>readlimit</code> is the number of chars that can be read from the - * stream after setting the mark before the mark becomes invalid. For - * example, if <code>mark()</code> is called with a read limit of 10, then - * when 11 chars of data are read from the stream before the - * <code>reset()</code> method is called, then the mark is invalid and the - * stream object instance is not required to remember the mark. - * <p> - * Note that the number of chars that can be remembered by this method - * can be greater than the size of the internal read buffer. It is also - * not dependent on the subordinate stream supporting mark/reset - * functionality. - * - * @param readlimit The number of chars that can be read before the mark - * becomes invalid - * - * @exception IOException If an error occurs - */ + * Mark a position in the input to which the stream can be + * "reset" by calling the <code>reset()</code> method. The parameter + * <code>readlimit</code> is the number of chars that can be read from the + * stream after setting the mark before the mark becomes invalid. For + * example, if <code>mark()</code> is called with a read limit of 10, then + * when 11 chars of data are read from the stream before the + * <code>reset()</code> method is called, then the mark is invalid and the + * stream object instance is not required to remember the mark. + * <p> + * Note that the number of chars that can be remembered by this method + * can be greater than the size of the internal read buffer. It is also + * not dependent on the subordinate stream supporting mark/reset + * functionality. + * + * @param readlimit The number of chars that can be read before the mark + * becomes invalid + * + * @exception IOException If an error occurs + */ public void mark(int readLimit) throws IOException { synchronized (lock) @@ -207,16 +207,16 @@ public class BufferedReader extends Reader } /** - * Reset the stream to the point where the <code>mark()</code> method - * was called. Any chars that were read after the mark point was set will - * be re-read during subsequent reads. - * <p> - * This method will throw an IOException if the number of chars read from - * the stream since the call to <code>mark()</code> exceeds the mark limit - * passed when establishing the mark. - * - * @exception IOException If an error occurs; - */ + * Reset the stream to the point where the <code>mark()</code> method + * was called. Any chars that were read after the mark point was set will + * be re-read during subsequent reads. + * <p> + * This method will throw an IOException if the number of chars read from + * the stream since the call to <code>mark()</code> exceeds the mark limit + * passed when establishing the mark. + * + * @exception IOException If an error occurs; + */ public void reset() throws IOException { synchronized (lock) @@ -239,15 +239,15 @@ public class BufferedReader extends Reader } /** - * This method determines whether or not a stream is ready to be read. If - * This method returns <code>false</code> then this stream could (but is - * not guaranteed to) block on the next read attempt. - * - * @return <code>true</code> if this stream is ready to be read, - * <code>false</code> otherwise - * - * @exception IOException If an error occurs - */ + * This method determines whether or not a stream is ready to be read. If + * This method returns <code>false</code> then this stream could (but is + * not guaranteed to) block on the next read attempt. + * + * @return <code>true</code> if this stream is ready to be read, + * <code>false</code> otherwise + * + * @exception IOException If an error occurs + */ public boolean ready() throws IOException { synchronized (lock) @@ -258,24 +258,24 @@ public class BufferedReader extends Reader } /** - * This method read chars from a stream and stores them into a caller - * supplied buffer. It starts storing the data at index - * <code>offset</code> into - * the buffer and attempts to read <code>len</code> chars. This method can - * return before reading the number of chars requested. The actual number - * of chars read is returned as an int. A -1 is returned to indicate the - * end of the stream. - * <p> - * This method will block until some data can be read. - * - * @param buf The array into which the chars read should be stored - * @param offset The offset into the array to start storing chars - * @param count The requested number of chars to read - * - * @return The actual number of chars read, or -1 if end of stream. - * - * @exception IOException If an error occurs. - */ + * This method read chars from a stream and stores them into a caller + * supplied buffer. It starts storing the data at index + * <code>offset</code> into + * the buffer and attempts to read <code>len</code> chars. This method can + * return before reading the number of chars requested. The actual number + * of chars read is returned as an int. A -1 is returned to indicate the + * end of the stream. + * <p> + * This method will block until some data can be read. + * + * @param buf The array into which the chars read should be stored + * @param offset The offset into the array to start storing chars + * @param count The requested number of chars to read + * + * @return The actual number of chars read, or -1 if end of stream. + * + * @exception IOException If an error occurs. + */ public int read(char[] buf, int offset, int count) throws IOException { synchronized (lock) @@ -396,16 +396,16 @@ public class BufferedReader extends Reader } /** - * This method reads a single line of text from the input stream, returning - * it as a <code>String</code>. A line is terminated by "\n", a "\r", or - * an "\r\n" sequence. The system dependent line separator is not used. - * The line termination characters are not returned in the resulting - * <code>String</code>. - * - * @return The line of text read, or <code>null</code> if end of stream. - * - * @exception IOException If an error occurs - */ + * This method reads a single line of text from the input stream, returning + * it as a <code>String</code>. A line is terminated by "\n", a "\r", or + * an "\r\n" sequence. The system dependent line separator is not used. + * The line termination characters are not returned in the resulting + * <code>String</code>. + * + * @return The line of text read, or <code>null</code> if end of stream. + * + * @exception IOException If an error occurs + */ public String readLine() throws IOException { checkStatus(); @@ -470,20 +470,20 @@ public class BufferedReader extends Reader } /** - * This method skips the specified number of chars in the stream. It - * returns the actual number of chars skipped, which may be less than the - * requested amount. - * <p> - * This method first discards chars in the buffer, then calls the - * <code>skip</code> method on the underlying stream to skip the - * remaining chars. - * - * @param num_chars The requested number of chars to skip - * - * @return The actual number of chars skipped. - * - * @exception IOException If an error occurs - */ + * This method skips the specified number of chars in the stream. It + * returns the actual number of chars skipped, which may be less than the + * requested amount. + * <p> + * This method first discards chars in the buffer, then calls the + * <code>skip</code> method on the underlying stream to skip the + * remaining chars. + * + * @param num_chars The requested number of chars to skip + * + * @return The actual number of chars skipped. + * + * @exception IOException If an error occurs + */ public long skip(long count) throws IOException { synchronized (lock) diff --git a/libjava/java/io/ByteArrayOutputStream.java b/libjava/java/io/ByteArrayOutputStream.java index bb5b869a391..3e3e0c20018 100644 --- a/libjava/java/io/ByteArrayOutputStream.java +++ b/libjava/java/io/ByteArrayOutputStream.java @@ -118,7 +118,7 @@ public class ByteArrayOutputStream extends OutputStream * * @return The number of bytes in the internal buffer * - * @see reset + * @see #reset() */ public int size () { diff --git a/libjava/java/io/CharArrayWriter.java b/libjava/java/io/CharArrayWriter.java index 6f749b4833c..e9413f04072 100644 --- a/libjava/java/io/CharArrayWriter.java +++ b/libjava/java/io/CharArrayWriter.java @@ -130,7 +130,7 @@ public class CharArrayWriter extends Writer * * @return The number of chars in the internal buffer * - * @see reset + * @see #reset() */ public int size () { diff --git a/libjava/java/io/DataInput.java b/libjava/java/io/DataInput.java index d9763e29d2c..bf7c478272e 100644 --- a/libjava/java/io/DataInput.java +++ b/libjava/java/io/DataInput.java @@ -44,431 +44,403 @@ package java.io; * Status: Believed complete and correct. */ /** - * This interface is implemented by classes that can data from streams - * into Java primitive types. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - * @author Warren Levy <warrenl@cygnus.com> - */ + * This interface is implemented by classes that can data from streams + * into Java primitive types. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy <warrenl@cygnus.com> + */ 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 diff --git a/libjava/java/io/DataOutput.java b/libjava/java/io/DataOutput.java index 4721f526ac7..5c626f5e467 100644 --- a/libjava/java/io/DataOutput.java +++ b/libjava/java/io/DataOutput.java @@ -44,173 +44,147 @@ package java.io; */ /** - * This interface is implemented by classes that can wrte data to streams - * from Java primitive types. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - * @author Tom Tromey <tromey@cygnus.com> - */ + * This interface is implemented by classes that can wrte data to streams + * from Java primitive types. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey <tromey@cygnus.com> + */ 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 - */ + * 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 diff --git a/libjava/java/io/DataOutputStream.java b/libjava/java/io/DataOutputStream.java index 055f1424714..61a00f5b4d6 100644 --- a/libjava/java/io/DataOutputStream.java +++ b/libjava/java/io/DataOutputStream.java @@ -1,5 +1,5 @@ /* DataOutputStream.java -- Writes primitive Java datatypes to streams - Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc. + Copyright (C) 1998, 2001, 2003 Free Software Foundation, Inc. This file is part of GNU Classpath. diff --git a/libjava/java/io/Externalizable.java b/libjava/java/io/Externalizable.java index f6406b0335a..d0d0d4c392e 100644 --- a/libjava/java/io/Externalizable.java +++ b/libjava/java/io/Externalizable.java @@ -39,74 +39,72 @@ exception statement from your version. */ package java.io; /** - * This interface provides a way that classes can completely control how - * the data of their object instances are written and read to and from - * streams. It has two methods which are used to write the data to a stream - * and to read the data from a stream. The read method must read the data - * in exactly the way it was written by the write method. - * <p> - * Note that classes which implement this interface must take into account - * that all superclass data must also be written to the stream as well. - * The class implementing this interface must figure out how to make that - * happen. - * <p> - * This interface can be used to provide object persistence. When an - * object is to be stored externally, the <code>writeExternal</code> method is - * called to save state. When the object is restored, an instance is - * created using the default no-argument constructor and the - * <code>readExternal</code> method is used to restore the state. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - */ + * This interface provides a way that classes can completely control how + * the data of their object instances are written and read to and from + * streams. It has two methods which are used to write the data to a stream + * and to read the data from a stream. The read method must read the data + * in exactly the way it was written by the write method. + * <p> + * Note that classes which implement this interface must take into account + * that all superclass data must also be written to the stream as well. + * The class implementing this interface must figure out how to make that + * happen. + * <p> + * This interface can be used to provide object persistence. When an + * object is to be stored externally, the <code>writeExternal</code> method is + * called to save state. When the object is restored, an instance is + * created using the default no-argument constructor and the + * <code>readExternal</code> method is used to restore the state. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + */ public interface Externalizable extends Serializable { static final long serialVersionUID = -282491828744381764L; /** - * This method restores an object's state by reading in the instance data - * for the object from the passed in stream. Note that this stream is not - * a subclass of <code>InputStream</code>, but rather is a class that - * implements - * the <code>ObjectInput</code> interface. That interface provides a - * mechanism for - * reading in Java data types from a stream. - * <p> - * Note that this method must be compatible with <code>writeExternal</code>. - * It must read back the exact same types that were written by that - * method in the exact order they were written. - * <p> - * If this method needs to read back an object instance, then the class - * for that object must be found and loaded. If that operation fails, - * then this method throws a <code>ClassNotFoundException</code> - * - * @param in An <code>ObjectInput</code> instance for reading in the object - * state - * - * @exception ClassNotFoundException If the class of an object being - * restored cannot be found - * @exception IOException If any other error occurs - */ + * This method restores an object's state by reading in the instance data + * for the object from the passed in stream. Note that this stream is not + * a subclass of <code>InputStream</code>, but rather is a class that + * implements + * the <code>ObjectInput</code> interface. That interface provides a + * mechanism for + * reading in Java data types from a stream. + * <p> + * Note that this method must be compatible with <code>writeExternal</code>. + * It must read back the exact same types that were written by that + * method in the exact order they were written. + * <p> + * If this method needs to read back an object instance, then the class + * for that object must be found and loaded. If that operation fails, + * then this method throws a <code>ClassNotFoundException</code> + * + * @param in An <code>ObjectInput</code> instance for reading in the object + * state + * + * @exception ClassNotFoundException If the class of an object being + * restored cannot be found + * @exception IOException If any other error occurs + */ public abstract void readExternal(ObjectInput in) throws ClassNotFoundException, IOException; - /*************************************************************************/ - /** - * This method is responsible for writing the instance data of an object - * to the passed in stream. Note that this stream is not a subclass of - * <code>OutputStream</code>, but rather is a class that implements the - * <code>ObjectOutput</code> interface. That interface provides a - * number of methods - * for writing Java data values to a stream. - * <p> - * Not that the implementation of this method must be coordinated with - * the implementation of <code>readExternal</code>. - * - * @param out An <code>ObjectOutput</code> instance for writing the - * object state - * - * @exception IOException If an error occurs - */ + * This method is responsible for writing the instance data of an object + * to the passed in stream. Note that this stream is not a subclass of + * <code>OutputStream</code>, but rather is a class that implements the + * <code>ObjectOutput</code> interface. That interface provides a + * number of methods + * for writing Java data values to a stream. + * <p> + * Not that the implementation of this method must be coordinated with + * the implementation of <code>readExternal</code>. + * + * @param out An <code>ObjectOutput</code> instance for writing the + * object state + * + * @exception IOException If an error occurs + */ public abstract void writeExternal(ObjectOutput out) throws IOException; } // interface Externalizable diff --git a/libjava/java/io/FileFilter.java b/libjava/java/io/FileFilter.java index 4cfdb01d6f4..68950d3b6c9 100644 --- a/libjava/java/io/FileFilter.java +++ b/libjava/java/io/FileFilter.java @@ -39,27 +39,27 @@ exception statement from your version. */ package java.io; /** - * This interface has one method which is used for filtering pathnames - * returned in a pathname listing. It is currently used by the - * <code>File.listFiles()</code> method. - * <p> - * The method in this interface determines if a particular pathname should - * or should not be included in the pathname listing. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - */ + * This interface has one method which is used for filtering pathnames + * returned in a pathname listing. It is currently used by the + * <code>File.listFiles()</code> method. + * <p> + * The method in this interface determines if a particular pathname should + * or should not be included in the pathname listing. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + */ public interface FileFilter { /** - * This method determines whether or not a given pathname should be included - * in a pathname listing. - * - * @param pathname The pathname to test - * - * @return <code>true</code> if the path should be included in the list, - * <code>false</code> otherwise. - */ + * This method determines whether or not a given pathname should be included + * in a pathname listing. + * + * @param pathname The pathname to test + * + * @return <code>true</code> if the path should be included in the list, + * <code>false</code> otherwise. + */ public abstract boolean accept(File pathname); } // interface FileFilter diff --git a/libjava/java/io/FileInputStream.java b/libjava/java/io/FileInputStream.java index dcda9d81e64..ae738af72a7 100644 --- a/libjava/java/io/FileInputStream.java +++ b/libjava/java/io/FileInputStream.java @@ -1,5 +1,5 @@ /* FileInputStream.java -- An input stream that reads from disk files. - Copyright (C) 1998, 1999, 2001, 2002, 2003 Free Software Foundation, Inc. + Copyright (C) 1998, 2002, 2003 Free Software Foundation, Inc. This file is part of GNU Classpath. diff --git a/libjava/java/io/FileOutputStream.java b/libjava/java/io/FileOutputStream.java index eaf4d9beaa2..e8a4f08e1ff 100644 --- a/libjava/java/io/FileOutputStream.java +++ b/libjava/java/io/FileOutputStream.java @@ -1,5 +1,5 @@ /* FileOutputStream.java -- Writes to a file on disk. - Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc. + Copyright (C) 1998, 2001, 2003 Free Software Foundation, Inc. This file is part of GNU Classpath. diff --git a/libjava/java/io/FilePermission.java b/libjava/java/io/FilePermission.java index 95aa4207785..a86c7c9ff99 100644 --- a/libjava/java/io/FilePermission.java +++ b/libjava/java/io/FilePermission.java @@ -93,7 +93,7 @@ public final class FilePermission extends Permission implements Serializable ** permission represents. ** @param actionsString a comma-separated list of the actions this ** permission represents. - ** @XXX what to do when the file string is malformed? + ** FIXME: what to do when the file string is malformed? **/ public FilePermission(String pathExpression, String actionsString) { diff --git a/libjava/java/io/FileWriter.java b/libjava/java/io/FileWriter.java index b7f8579f22f..44db08c535c 100644 --- a/libjava/java/io/FileWriter.java +++ b/libjava/java/io/FileWriter.java @@ -54,8 +54,6 @@ package java.io; public class FileWriter extends OutputStreamWriter { - /*************************************************************************/ - /* * Constructors */ @@ -75,8 +73,6 @@ public class FileWriter extends OutputStreamWriter super(new FileOutputStream(file)); } - /*************************************************************************/ - /** * This method initializes a new <code>FileWriter</code> object to write * to the specified <code>File</code> object. @@ -94,8 +90,6 @@ public class FileWriter extends OutputStreamWriter super(new FileOutputStream(file, append)); } - /*************************************************************************/ - /** * This method initializes a new <code>FileWriter</code> object to write * to the specified <code>FileDescriptor</code> object. @@ -110,8 +104,6 @@ public class FileWriter extends OutputStreamWriter super(new FileOutputStream(fd)); } - /*************************************************************************/ - /** * This method intializes a new <code>FileWriter</code> object to * write to the @@ -128,8 +120,6 @@ public class FileWriter extends OutputStreamWriter super(new FileOutputStream(name)); } - /*************************************************************************/ - /** * This method intializes a new <code>FileWriter</code> object to * write to the diff --git a/libjava/java/io/FilenameFilter.java b/libjava/java/io/FilenameFilter.java index df0509adadd..9e95b1e4987 100644 --- a/libjava/java/io/FilenameFilter.java +++ b/libjava/java/io/FilenameFilter.java @@ -44,29 +44,29 @@ package java.io; */ /** - * This interface has one method which is used for filtering filenames - * returned in a directory listing. It is currently used by the - * <code>File.list()</code> method and by the filename dialog in AWT. - * <p> - * The method in this interface determines if a particular file should - * or should not be included in the file listing. - * - * @author Aaron M. Renn (arenn@urbanophile.com) - * @author Tom Tromey <tromey@cygnus.com> - */ + * This interface has one method which is used for filtering filenames + * returned in a directory listing. It is currently used by the + * <code>File.list()</code> method and by the filename dialog in AWT. + * <p> + * The method in this interface determines if a particular file should + * or should not be included in the file listing. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey <tromey@cygnus.com> + */ public interface FilenameFilter { /** - * This method determines whether or not a given file should be included - * in a directory listing. - * - * @param dir The <code>File</code> instance for the directory being read - * @param name The name of the file to test - * - * @return <code>true</code> if the file should be included in the list, - * <code>false</code> otherwise. - */ + * This method determines whether or not a given file should be included + * in a directory listing. + * + * @param dir The <code>File</code> instance for the directory being read + * @param name The name of the file to test + * + * @return <code>true</code> if the file should be included in the list, + * <code>false</code> otherwise. + */ boolean accept(File dir, String name); } // interface FilenameFilter diff --git a/libjava/java/io/FilterInputStream.java b/libjava/java/io/FilterInputStream.java index 80cbd927375..fe45d33e368 100644 --- a/libjava/java/io/FilterInputStream.java +++ b/libjava/java/io/FilterInputStream.java @@ -69,25 +69,12 @@ package java.io; */ public class FilterInputStream extends InputStream { - - /*************************************************************************/ - - /* - * Instance Variables - */ - /** * This is the subordinate <code>InputStream</code> to which method calls * are redirected */ protected InputStream in; - /*************************************************************************/ - - /* - * Constructors - */ - /** * Create a <code>FilterInputStream</code> with the specified subordinate * <code>InputStream</code>. @@ -99,12 +86,6 @@ public class FilterInputStream extends InputStream this.in = in; } - /*************************************************************************/ - - /* - * Instance Methods - */ - /** * Calls the <code>in.mark(int)</code> method. * @@ -115,8 +96,6 @@ public class FilterInputStream extends InputStream in.mark(readlimit); } - /*************************************************************************/ - /** * Calls the <code>in.markSupported()</code> method. * @@ -128,8 +107,6 @@ public class FilterInputStream extends InputStream return(in.markSupported()); } - /*************************************************************************/ - /** * Calls the <code>in.reset()</code> method. * @@ -140,8 +117,6 @@ public class FilterInputStream extends InputStream in.reset(); } - /*************************************************************************/ - /** * Calls the <code>in.available()</code> method. * @@ -154,8 +129,6 @@ public class FilterInputStream extends InputStream return(in.available()); } - /*************************************************************************/ - /** * Calls the <code>in.skip(long)</code> method * @@ -170,8 +143,6 @@ public class FilterInputStream extends InputStream return(in.skip(num_bytes)); } - /*************************************************************************/ - /** * Calls the <code>in.read()</code> method * @@ -184,8 +155,6 @@ public class FilterInputStream extends InputStream return(in.read()); } - /*************************************************************************/ - /** * Calls the <code>read(byte[], int, int)</code> overloaded method. * Note that @@ -204,8 +173,6 @@ public class FilterInputStream extends InputStream return(read(buf, 0, buf.length)); } - /*************************************************************************/ - /** * Calls the <code>in.read(byte[], int, int)</code> method. * @@ -222,8 +189,6 @@ public class FilterInputStream extends InputStream return(in.read(buf, offset, len)); } - /*************************************************************************/ - /** * This method closes the input stream by closing the input stream that * this object is filtering. Future attempts to access this stream may diff --git a/libjava/java/io/FilterOutputStream.java b/libjava/java/io/FilterOutputStream.java index 01204b46109..2144213f0e1 100644 --- a/libjava/java/io/FilterOutputStream.java +++ b/libjava/java/io/FilterOutputStream.java @@ -56,25 +56,12 @@ package java.io; */ public class FilterOutputStream extends OutputStream { - - /*************************************************************************/ - - /* - * Instance Variables - */ - /** * This is the subordinate <code>OutputStream</code> that this class * redirects its method calls to. */ protected OutputStream out; - /*************************************************************************/ - - /* - * Constructors - */ - /** * This method initializes an instance of <code>FilterOutputStream</code> * to write to the specified subordinate <code>OutputStream</code>. @@ -86,12 +73,6 @@ public class FilterOutputStream extends OutputStream this.out = out; } - /*************************************************************************/ - - /* - * Instance Methods - */ - /** * This method closes the underlying <code>OutputStream</code>. Any * further attempts to write to this stream may throw an exception. @@ -104,8 +85,6 @@ public class FilterOutputStream extends OutputStream out.close(); } - /*************************************************************************/ - /** * This method attempt to flush all buffered output to be written to the * underlying output sink. @@ -117,8 +96,6 @@ public class FilterOutputStream extends OutputStream out.flush(); } - /*************************************************************************/ - /** * This method writes a single byte of output to the underlying * <code>OutputStream</code>. @@ -132,8 +109,6 @@ public class FilterOutputStream extends OutputStream out.write(b); } - /*************************************************************************/ - /** * This method writes all the bytes in the specified array to the underlying * <code>OutputStream</code>. It does this by calling the three parameter @@ -151,8 +126,6 @@ public class FilterOutputStream extends OutputStream write(buf, 0, buf.length); } - /*************************************************************************/ - /** * This method calls the <code>write(int)</code> method <code>len</code> * times for all bytes from the array <code>buf</code> starting at index diff --git a/libjava/java/io/FilterReader.java b/libjava/java/io/FilterReader.java index 22bf6e61897..caf102b082a 100644 --- a/libjava/java/io/FilterReader.java +++ b/libjava/java/io/FilterReader.java @@ -63,22 +63,12 @@ package java.io; */ public abstract class FilterReader extends Reader { - /* - * Instance Variables - */ - /** * This is the subordinate <code>Reader</code> to which method calls * are redirected */ protected Reader in; - /*************************************************************************/ - - /* - * Constructors - */ - /** * Create a <code>FilterReader</code> with the specified subordinate * <code>Reader</code>. @@ -93,12 +83,6 @@ public abstract class FilterReader extends Reader this.in = in; } - /*************************************************************************/ - - /* - * Instance Methods - */ - /** * Calls the <code>in.mark(int)</code> method. * @@ -111,8 +95,6 @@ public abstract class FilterReader extends Reader in.mark(readlimit); } - /*************************************************************************/ - /** * Calls the <code>in.markSupported()</code> method. * @@ -124,8 +106,6 @@ public abstract class FilterReader extends Reader return(in.markSupported()); } - /*************************************************************************/ - /** * Calls the <code>in.reset()</code> method. * @@ -136,8 +116,6 @@ public abstract class FilterReader extends Reader in.reset(); } - /*************************************************************************/ - /** * Calls the <code>in.read()</code> method. * @@ -150,8 +128,6 @@ public abstract class FilterReader extends Reader return(in.ready()); } - /*************************************************************************/ - /** * Calls the <code>in.skip(long)</code> method * @@ -166,8 +142,6 @@ public abstract class FilterReader extends Reader return(in.skip(num_chars)); } - /*************************************************************************/ - /** * Calls the <code>in.read()</code> method * @@ -180,8 +154,6 @@ public abstract class FilterReader extends Reader return(in.read()); } - /*************************************************************************/ - /** * Calls the <code>in.read(char[], int, int)</code> method. * @@ -198,8 +170,6 @@ public abstract class FilterReader extends Reader return(in.read(buf, offset, len)); } - /*************************************************************************/ - /** * This method closes the stream by calling the <code>close()</code> method * of the underlying stream. diff --git a/libjava/java/io/FilterWriter.java b/libjava/java/io/FilterWriter.java index f476dfee3f5..87bae4f0bd8 100644 --- a/libjava/java/io/FilterWriter.java +++ b/libjava/java/io/FilterWriter.java @@ -56,22 +56,12 @@ package java.io; */ public abstract class FilterWriter extends Writer { - /* - * Instance Variables - */ - /** * This is the subordinate <code>Writer</code> that this class * redirects its method calls to. */ protected Writer out; - /*************************************************************************/ - - /* - * Constructors - */ - /** * This method initializes an instance of <code>FilterWriter</code> * to write to the specified subordinate <code>Writer</code>. @@ -86,12 +76,6 @@ public abstract class FilterWriter extends Writer this.out = out; } - /*************************************************************************/ - - /* - * Instance Methods - */ - /** * This method closes the underlying <code>Writer</code>. Any * further attempts to write to this stream may throw an exception. @@ -103,8 +87,6 @@ public abstract class FilterWriter extends Writer out.close(); } - /*************************************************************************/ - /** * This method attempt to flush all buffered output to be written to the * underlying output sink. @@ -116,8 +98,6 @@ public abstract class FilterWriter extends Writer out.flush(); } - /*************************************************************************/ - /** * This method writes a single char of output to the underlying * <code>Writer</code>. @@ -131,8 +111,6 @@ public abstract class FilterWriter extends Writer out.write(b); } - /*************************************************************************/ - /** * This method writes <code>len</code> chars from the array <code>buf</code> * starting at index <code>offset</code> to the underlying @@ -149,8 +127,6 @@ public abstract class FilterWriter extends Writer out.write(buf, offset, len); } - /*************************************************************************/ - /** * This method writes <code>len</code> chars from the <code>String</code> * starting at position <code>offset</code>. diff --git a/libjava/java/io/LineNumberInputStream.java b/libjava/java/io/LineNumberInputStream.java index 4a4d68a3d70..ee0ce2c799e 100644 --- a/libjava/java/io/LineNumberInputStream.java +++ b/libjava/java/io/LineNumberInputStream.java @@ -57,7 +57,7 @@ package java.io; * stream, it has the same mark/reset functionality as the underlying * stream. The <code>mark()</code> and <code>reset()</code> methods * in this class handle line numbers correctly. Calling - * @code{reset()} resets the line number to the point at which + * <code>reset()</code> resets the line number to the point at which * <code>mark()</code> was called if the subordinate stream supports * that functionality. * <p> @@ -119,7 +119,7 @@ public class LineNumberInputStream extends FilterInputStream /** * This method returns the current line number * - * @returns The current line number + * @return The current line number */ public int getLineNumber() { diff --git a/libjava/java/io/ObjectInput.java b/libjava/java/io/ObjectInput.java index 678a31edc48..831203a14a4 100644 --- a/libjava/java/io/ObjectInput.java +++ b/libjava/java/io/ObjectInput.java @@ -58,8 +58,6 @@ public interface ObjectInput extends DataInput */ public abstract int available() throws IOException; - /*************************************************************************/ - /** * This method reading a byte of data from a stream. It returns that byte * as an int. This method blocks if no data is available to be read. @@ -70,8 +68,6 @@ public interface ObjectInput extends DataInput */ public abstract int read() throws IOException; - /*************************************************************************/ - /** * This method reads raw bytes and stores them them a byte array buffer. * Note that this method will block if no data is available. However, @@ -86,8 +82,6 @@ public interface ObjectInput extends DataInput */ public abstract int read(byte[] buf) throws IOException; - /*************************************************************************/ - /** * This method reads raw bytes and stores them in a byte array buffer * <code>buf</code> starting at position <code>offset</code> into the @@ -107,8 +101,6 @@ public interface ObjectInput extends DataInput */ public abstract int read(byte[] buf, int offset, int len) throws IOException; - /*************************************************************************/ - /** * Reads an object instance and returns it. If the class for the object * being read cannot be found, then a ClassNotFoundException will @@ -123,8 +115,6 @@ public interface ObjectInput extends DataInput public abstract Object readObject() throws ClassNotFoundException, IOException; - /*************************************************************************/ - /** * This method causes the specified number of bytes to be read and * discarded. It is possible that fewer than the requested number of bytes @@ -138,8 +128,6 @@ public interface ObjectInput extends DataInput */ public abstract long skip(long num_bytes) throws IOException; - /*************************************************************************/ - /** * This method closes the input source * diff --git a/libjava/java/io/ObjectOutput.java b/libjava/java/io/ObjectOutput.java index 1397027d402..f9e923b19b9 100644 --- a/libjava/java/io/ObjectOutput.java +++ b/libjava/java/io/ObjectOutput.java @@ -58,8 +58,6 @@ public interface ObjectOutput extends DataOutput */ public abstract void write(int b) throws IOException; - /*************************************************************************/ - /** * This method writes all the bytes in the specified byte array to the * output stream. @@ -70,8 +68,6 @@ public interface ObjectOutput extends DataOutput */ public abstract void write(byte[] buf) throws IOException; - /*************************************************************************/ - /** * This method writes <code>len</code> bytes from the specified array * starting at index <code>offset</code> into that array. @@ -85,8 +81,6 @@ public interface ObjectOutput extends DataOutput public abstract void write(byte[] buf, int offset, int len) throws IOException; - /*************************************************************************/ - /** * This method writes a object instance to a stream. The format of the * data written is determined by the actual implementation of this method @@ -97,8 +91,6 @@ public interface ObjectOutput extends DataOutput */ public abstract void writeObject(Object obj) throws IOException; - /*************************************************************************/ - /** * This method causes any buffered data to be flushed out to the underlying * stream @@ -107,8 +99,6 @@ public interface ObjectOutput extends DataOutput */ public abstract void flush() throws IOException; - /*************************************************************************/ - /** * This method closes the underlying stream. * diff --git a/libjava/java/io/ObjectStreamClass.java b/libjava/java/io/ObjectStreamClass.java index 19a69ec47bc..ab233f166d0 100644 --- a/libjava/java/io/ObjectStreamClass.java +++ b/libjava/java/io/ObjectStreamClass.java @@ -166,14 +166,14 @@ public class ObjectStreamClass implements Serializable /** - Returns a textual representation of this - <code>ObjectStreamClass</code> object including the name of the - class it represents as well as that class's serial version - stream-unique identifier. - - @see getSerialVersionUID () - @see getName () - */ + * Returns a textual representation of this + * <code>ObjectStreamClass</code> object including the name of the + * class it represents as well as that class's serial version + * stream-unique identifier. + * + * @see #getSerialVersionUID() + * @see #getName() + */ public String toString () { return "java.io.ObjectStreamClass< " + name + ", " + uid + " >"; diff --git a/libjava/java/io/PrintStream.java b/libjava/java/io/PrintStream.java index aa846dcbb9f..3101bb5dea2 100644 --- a/libjava/java/io/PrintStream.java +++ b/libjava/java/io/PrintStream.java @@ -1,5 +1,5 @@ /* PrintStream.java -- OutputStream for printing output - Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc. + Copyright (C) 1998,2003 Free Software Foundation, Inc. This file is part of GNU Classpath. diff --git a/libjava/java/io/PushbackReader.java b/libjava/java/io/PushbackReader.java index 4a353190d81..4b442e52c6f 100644 --- a/libjava/java/io/PushbackReader.java +++ b/libjava/java/io/PushbackReader.java @@ -77,7 +77,7 @@ public class PushbackReader extends FilterReader * specified subordinate <code>Reader</code> with a default pushback buffer * size of 1. * - * @code in The subordinate stream to read from + * @param in The subordinate stream to read from */ public PushbackReader(Reader in) { diff --git a/libjava/java/io/SerializablePermission.java b/libjava/java/io/SerializablePermission.java index 85b9cdf2445..d27dcf42667 100644 --- a/libjava/java/io/SerializablePermission.java +++ b/libjava/java/io/SerializablePermission.java @@ -67,8 +67,6 @@ public final class SerializablePermission extends BasicPermission private static final String[] legal_names = { "enableSubclassImplementation", "enableSubstitution" }; - /*************************************************************************/ - /* * Constructors */ @@ -88,8 +86,6 @@ public final class SerializablePermission extends BasicPermission this(name, null); } - /*************************************************************************/ - /** * This method initializes a new instance of * <code>SerializablePermission</code> diff --git a/libjava/java/io/StreamTokenizer.java b/libjava/java/io/StreamTokenizer.java index 5b3533b633d..94341fa7620 100644 --- a/libjava/java/io/StreamTokenizer.java +++ b/libjava/java/io/StreamTokenizer.java @@ -580,7 +580,7 @@ public class StreamTokenizer * quote, and comment) from all characters. It is equivalent to calling * <code>ordinaryChars(0x00, 0xFF)</code>. * - * @see ordinaryChars + * @see #ordinaryChars(int, int) */ public void resetSyntax() { |
