You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/01 10:09:01 UTC
svn commit: r770573 [2/10] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java Fri May 1 08:08:59 2009
@@ -20,14 +20,17 @@
import org.apache.harmony.luni.util.Msg;
/**
- * CharArrayWriter is used as a character output stream on a character array.
- * The buffer used to store the written characters will grow as needed to
- * accommodate more characters as they are written.
+ * A specialized {@link Writer} for class for writing content to an (internal)
+ * char array. As bytes are written to this writer, the char array may be
+ * expanded to hold more characters. When the writing is considered to be
+ * finished, a copy of the char array can be requested from the class.
+ *
+ * @see CharArrayReader
*/
public class CharArrayWriter extends Writer {
/**
- * Buffer for characters
+ * The buffer for characters.
*/
protected char[] buf;
@@ -38,8 +41,8 @@
/**
* Constructs a new CharArrayWriter which has a buffer allocated with the
- * default size of 32 characters. The buffer is also the <code>lock</code>
- * used to synchronize access to this Writer.
+ * default size of 32 characters. This buffer is also used as the
+ * {@code lock} to synchronize access to this writer.
*/
public CharArrayWriter() {
super();
@@ -49,11 +52,13 @@
/**
* Constructs a new CharArrayWriter which has a buffer allocated with the
- * size of <code>initialSize</code> characters. The buffer is also the
- * <code>lock</code> used to synchronize access to this Writer.
+ * size of {@code initialSize} characters. The buffer is also used as the
+ * {@code lock} to synchronize access to this writer.
*
* @param initialSize
* the initial size of this CharArrayWriters buffer.
+ * @throws IllegalArgumentException
+ * if {@code initialSize < 0}.
*/
public CharArrayWriter(int initialSize) {
super();
@@ -65,8 +70,7 @@
}
/**
- * Close this Writer. This is the concrete implementation required. This
- * particular implementation does nothing.
+ * Closes this writer. The implementation in CharArrayWriter does nothing.
*/
@Override
public void close() {
@@ -86,8 +90,7 @@
}
/**
- * Flush this Writer. This is the concrete implementation required. This
- * particular implementation does nothing.
+ * Flushes this writer. The implementation in CharArrayWriter does nothing.
*/
@Override
public void flush() {
@@ -95,9 +98,9 @@
}
/**
- * Reset this Writer. The current write position is reset to the beginning
+ * Resets this writer. The current write position is reset to the beginning
* of the buffer. All written characters are lost and the size of this
- * writer is now 0.
+ * writer is set to 0.
*/
public void reset() {
synchronized (lock) {
@@ -106,10 +109,11 @@
}
/**
- * Answer the size of this Writer in characters. This number changes if this
- * Writer is reset or as more characters are written to it.
+ * Returns the size of this writer, that is the number of characters it
+ * stores. This number changes if this writer is reset or when more
+ * characters are written to it.
*
- * @return int this CharArrayWriters current size in characters.
+ * @return this CharArrayWriter's current size in characters.
*/
public int size() {
synchronized (lock) {
@@ -118,11 +122,11 @@
}
/**
- * Answer the contents of the receiver as a char array. The array returned
- * is a copy and any modifications made to this Writer after are not
- * reflected in the result.
+ * Returns the contents of the receiver as a char array. The array returned
+ * is a copy and any modifications made to this writer after calling this
+ * method are not reflected in the result.
*
- * @return char[] this CharArrayWriters contents as a new char array.
+ * @return this CharArrayWriter's contents as a new char array.
*/
public char[] toCharArray() {
synchronized (lock) {
@@ -133,11 +137,11 @@
}
/**
- * Answer the contents of this CharArrayWriter as a String. The String
- * returned is a copy and any modifications made to this Writer after are
- * not reflected in the result.
+ * Returns the contents of this CharArrayWriter as a string. The string
+ * returned is a copy and any modifications made to this writer after
+ * calling this method are not reflected in the result.
*
- * @return String this CharArrayWriters contents as a new String.
+ * @return this CharArrayWriters contents as a new string.
*/
@Override
public String toString() {
@@ -147,15 +151,18 @@
}
/**
- * Writes <code>count</code> characters starting at <code>offset</code>
- * in <code>buf</code> to this CharArrayWriter.
+ * Writes {@code count} characters starting at {@code offset} in {@code c}
+ * to this writer.
*
* @param c
* the non-null array containing characters to write.
* @param offset
- * offset in buf to retrieve characters
+ * the index of the first character in {@code buf} to write.
* @param len
- * maximum number of characters to write
+ * maximum number of characters to write.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code len < 0}, or if
+ * {@code offset + len} is bigger than the size of {@code c}.
*/
@Override
public void write(char[] c, int offset, int len) {
@@ -172,12 +179,12 @@
}
/**
- * Writes the specified character <code>oneChar</code> to this
- * CharArrayWriter. This implementation writes the low order two bytes to
- * the Stream.
+ * Writes the specified character {@code oneChar} to this writer.
+ * This implementation writes the two low order bytes of the integer
+ * {@code oneChar} to the buffer.
*
* @param oneChar
- * The character to write
+ * the character to write.
*/
@Override
public void write(int oneChar) {
@@ -188,16 +195,21 @@
}
/**
- * Writes <code>count</code> number of characters starting at
- * <code>offset</code> from the String <code>str</code> to this
- * CharArrayWriter.
+ * Writes {@code count} number of characters starting at {@code offset} from
+ * the string {@code str} to this CharArrayWriter.
*
* @param str
- * the non-null String containing the characters to write.
+ * the non-null string containing the characters to write.
* @param offset
- * the starting point to retrieve characters.
+ * the index of the first character in {@code str} to write.
* @param len
* the number of characters to retrieve and write.
+ * @throws NullPointerException
+ * if {@code str} is null.
+ * @throws StringIndexOutOfBoundsException
+ * if {@code offset < 0} or {@code len < 0}, or if
+ * {@code offset + len} is bigger than the length of
+ * {@code str}.
*/
@Override
public void write(String str, int offset, int len) {
@@ -219,13 +231,14 @@
/**
* Writes the contents of this CharArrayWriter to another Writer. The output
* is all the characters that have been written to the receiver since the
- * last reset or since the creation.
+ * last reset or since it was created.
*
* @param out
* the non-null Writer on which to write the contents.
- *
+ * @throws NullPointerException
+ * if {@code out} is null.
* @throws IOException
- * If an error occurs attempting to write the contents out.
+ * if an error occurs attempting to write out the contents.
*/
public void writeTo(Writer out) throws IOException {
synchronized (lock) {
@@ -234,14 +247,12 @@
}
/**
- * Append a char <code>c</code>to the CharArrayWriter. The
- * CharArrayWriter.append(<code>c</code>) works the same way as
- * CharArrayWriter.write(<code>c</code>).
+ * Appends a char {@code c} to the CharArrayWriter. The method works the
+ * same way as {@code write(c)}.
*
* @param c
- * The character appended to the CharArrayWriter.
- * @return The CharArrayWriter.
- * @see Writer#append(char)
+ * the character appended to the CharArrayWriter.
+ * @return this CharArrayWriter.
*/
@Override
public CharArrayWriter append(char c) {
@@ -250,16 +261,13 @@
}
/**
- * Append a CharSequence <code>csq</code> to the CharArrayWriter. The
- * CharArrayWriter.append(<code>csq</code>) works the same way as
- * CharArrayWriter.write(<code>csq</code>.toString()). If
- * <code>csq</code> is null, then then "null" will be substituted for
- * <code>csq</code>.
+ * Appends a CharSequence {@code csq} to the CharArrayWriter. The method
+ * works the same way as {@code write(csq.toString())}. If {@code csq} is
+ * null, then it will be substituted with the string "null".
*
* @param csq
- * The CharSequence appended to the CharArrayWriter.
- * @return The CharArrayWriter
- * @see Writer#append(CharSequence)
+ * the CharSequence appended to the CharArrayWriter, may be null.
+ * @return this CharArrayWriter.
*/
@Override
public CharArrayWriter append(CharSequence csq) {
@@ -272,27 +280,25 @@
}
/**
- * Append a subsequence of a CharSequence <code>csq</code> to the
- * CharArrayWriter. The first char and the last char of the subsequnce is
- * specified by the parameter <code>start</code> and <code>end</code>.
- * The CharArrayWriter.append(<code>csq</code>) works the same way as
- * CharArrayWriter.write(<code>csq</code>.subSequence(<code>start</code>,<code>end</code>).toString).
- * If <code>csq</code> is null, then "null" will be substituted for
- * <code>csq</code>.
+ * Append a subsequence of a CharSequence {@code csq} to the
+ * CharArrayWriter. The first and last characters of the subsequence are
+ * specified by the parameters {@code start} and {@code end}. The
+ * CharArrayWriter.append({@code csq}) works the same way as
+ * {@code CharArrayWriter.write(csq.subSequence(start, end).toString)}. If
+ * {@code csq} is null, then it will be substituted with the string "null".
*
* @param csq
- * The CharSequence appended to the CharArrayWriter.
+ * the CharSequence appended to the CharArrayWriter, may be null.
* @param start
- * The index of the first char in the CharSequence appended to
- * the CharArrayWriter.
+ * the index of the first character in the CharSequence appended
+ * to the CharArrayWriter.
* @param end
- * The index of the char after the last one in the CharSequence
- * appended to the CharArrayWriter.
- * @return The CharArrayWriter.
+ * the index of the character after the last one in the
+ * CharSequence appended to the CharArrayWriter.
+ * @return this CharArrayWriter.
* @throws IndexOutOfBoundsException
- * If start is less than end, end is greater than the length of
- * the CharSequence, or start or end is negative.
- * @see Writer#append(CharSequence, int, int)
+ * if {@code start < 0}, {@code end < 0}, {@code start > end},
+ * or if {@code end} is greater than the length of {@code csq}.
*/
@Override
public CharArrayWriter append(CharSequence csq, int start, int end) {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java Fri May 1 08:08:59 2009
@@ -18,26 +18,26 @@
package java.io;
/**
- * This is the top level class for character conversion exceptions.
+ * The top level class for character conversion exceptions.
*/
public class CharConversionException extends IOException {
private static final long serialVersionUID = -8680016352018427031L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- *
+ * Constructs a new {@code CharConversionException} with its stack trace
+ * filled in.
*/
public CharConversionException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code CharConversionException} with its stack trace and
+ * detail message filled in.
*
* @param detailMessage
- * The detail message for the exception.
+ * the detail message for this exception.
*/
public CharConversionException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java Fri May 1 08:08:59 2009
@@ -17,17 +17,19 @@
package java.io;
/**
- * Closeable represents the source or destination of some data which can be
- * called its close method to release resources it holds.
+ * Defines an interface for classes that can (or need to) be closed once they
+ * are not used any longer. This usually includes all sorts of
+ * {@link InputStream}s and {@link OutputStream}s. Calling the {@code close}
+ * method releases resources that the object holds.
*/
public interface Closeable {
/**
- * Close the object and release any system resources it holds. If the object
- * has been close, then invoke this method has no effect.
+ * Closes the object and release any system resources it holds. If the
+ * object has already been closed, then invoking this method has no effect.
*
* @throws IOException
- * if any error raises when closing the object.
+ * if any error occurs when closing the object.
*/
public void close() throws IOException;
}
\ No newline at end of file
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java Fri May 1 08:08:59 2009
@@ -18,107 +18,125 @@
package java.io;
/**
- * DataInput is an interface which declares methods for reading in typed data
- * from a Stream. Typically, this stream has been written by a class which
- * implements DataOutput. Types that can be read include byte, 16-bit short,
- * 32-bit int, 32-bit float, 64-bit long, 64-bit double, byte strings, and UTF
- * Strings.
- *
+ * Defines an interface for classes that are able to read typed data from some
+ * source. Typically, this data has been written by a class which implements
+ * {@link DataOutput}. Types that can be read include byte, 16-bit short, 32-bit
+ * int, 32-bit float, 64-bit long, 64-bit double, byte strings, and MUTF-8
+ * strings.
+ *
+ * <h3>MUTF-8 (Modified UTF-8) Encoding</h3>
+ * <p>
+ * When encoding strings as UTF, implementations of {@code DataInput} and
+ * {@code DataOutput} use a slightly modified form of UTF-8, hereafter referred
+ * to as MUTF-8. This form is identical to standard UTF-8, except:
+ * <ul>
+ * <li>Only the one-, two-, and three-byte encodings are used.</li>
+ * <li>Code points in the range <code>U+10000</code> …
+ * <code>U+10ffff</code> are encoded as a surrogate pair, each of which is
+ * represented as a three-byte encoded value.</li>
+ * <li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
+ * </ul>
+ * <p>
+ * Please refer to <a href="http://unicode.org">The Unicode Standard</a> for
+ * further information about character encoding. MUTF-8 is actually closer to
+ * the (relatively less well-known) encoding <a
+ * href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 per se.
+ *
* @see DataInputStream
* @see RandomAccessFile
*/
public interface DataInput {
/**
- * Reads a boolean from this stream.
- *
- * @return the next boolean value from the source stream.
+ * Reads a boolean.
*
+ * @return the next boolean value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeBoolean(boolean)
*/
public abstract boolean readBoolean() throws IOException;
/**
- * Reads an 8-bit byte value from this stream.
- *
- * @return the next byte value from the source stream.
+ * Reads an 8-bit byte value.
*
+ * @return the next byte value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeByte(int)
*/
public abstract byte readByte() throws IOException;
/**
- * Reads a 16-bit character value from this stream.
- *
- * @return the next <code>char</code> value from the source stream.
+ * Reads a 16-bit character value.
*
+ * @return the next char value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeChar(int)
*/
public abstract char readChar() throws IOException;
/**
- * Reads a 64-bit <code>double</code> value from this stream.
- *
- * @return the next <code>double</code> value from the source stream.
+ * Reads a 64-bit double value.
*
+ * @return the next double value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeDouble(double)
*/
public abstract double readDouble() throws IOException;
/**
- * Reads a 32-bit <code>float</code> value from this stream.
- *
- * @return the next <code>float</code> value from the source stream.
+ * Reads a 32-bit float value.
*
+ * @return the next float value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeFloat(float)
*/
public abstract float readFloat() throws IOException;
/**
- * Reads bytes from this stream into the byte array <code>buffer</code>.
- * This method will block until <code>buffer.length</code> number of bytes
- * have been read.
+ * Reads bytes into the byte array {@code buffer}. This method will block
+ * until {@code buffer.length} number of bytes have been read.
*
* @param buffer
- * the buffer to read bytes into
- *
+ * the buffer to read bytes into.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#write(byte[])
* @see DataOutput#write(byte[], int, int)
*/
public abstract void readFully(byte[] buffer) throws IOException;
/**
- * Read bytes from this stream and stores them in byte array
- * <code>buffer</code> starting at offset <code>offset</code>. This
- * method blocks until <code>count</code> number of bytes have been read.
+ * Reads bytes and stores them in the byte array {@code buffer} starting at
+ * offset {@code offset}. This method blocks until {@code count} number of
+ * bytes have been read.
*
* @param buffer
- * the byte array in which to store the read bytes.
+ * the byte array in which to store the bytes read.
* @param offset
- * the offset in <code>buffer</code> to store the read bytes.
+ * the initial position in {@code buffer} to store the bytes
+ * read.
* @param count
- * the maximum number of bytes to store in <code>buffer</code>.
- *
+ * the maximum number of bytes to store in {@code buffer}.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#write(byte[])
* @see DataOutput#write(byte[], int, int)
*/
@@ -126,106 +144,102 @@
throws IOException;
/**
- * Reads a 32-bit integer value from this stream.
- *
- * @return the next <code>int</code> value from the source stream.
+ * Reads a 32-bit integer value.
*
+ * @return the next int value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeInt(int)
*/
public abstract int readInt() throws IOException;
/**
- * Answers a <code>String</code> representing the next line of text
- * available in this BufferedReader. A line is represented by 0 or more
- * characters followed by <code>'\n'</code>, <code>'\r'</code>,
- * <code>"\n\r"</code> or end of stream. The <code>String</code> does
- * not include the newline sequence.
- *
- * @return the contents of the line or null if no characters were read
- * before end of stream.
- *
+ * Returns a string containing the next line of text available from this
+ * stream. A line is made of zero or more characters followed by {@code
+ * '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream. The string
+ * does not include the newline sequence.
+ *
+ * @return the contents of the line or null if no characters have been read
+ * before the end of the stream.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
+ * if an I/O error occurs while reading.
*/
public abstract String readLine() throws IOException;
/**
- * Reads a 64-bit <code>long</code> value from this stream.
- *
- * @return the next <code>long</code> value from the source stream.
+ * Reads a 64-bit long value.
*
+ * @return the next long value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeLong(long)
*/
public abstract long readLong() throws IOException;
/**
- * Reads a 16-bit <code>short</code> value from this stream.
- *
- * @return the next <code>short</code> value from the source stream.
+ * Reads a 16-bit short value.
*
+ * @return the next short value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeShort(int)
*/
public abstract short readShort() throws IOException;
/**
- * Reads an unsigned 8-bit <code>byte</code> value from this stream and
- * returns it as an int.
- *
- * @return the next unsigned byte value from the source stream.
+ * Reads an unsigned 8-bit byte value and returns it as an int.
*
+ * @return the next unsigned byte value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeByte(int)
*/
public abstract int readUnsignedByte() throws IOException;
/**
- * Reads a 16-bit unsigned <code>short</code> value from this stream and
- * returns it as an int.
- *
- * @return the next unsigned <code>short</code> value from the source
- * stream.
+ * Reads a 16-bit unsigned short value and returns it as an int.
*
+ * @return the next unsigned short value.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeShort(int)
*/
public abstract int readUnsignedShort() throws IOException;
/**
- * Reads a UTF format String from this Stream.
- *
- * @return the next UTF String from the source stream.
+ * Reads a string encoded with {@link DataInput modified UTF-8}.
*
+ * @return the next string encoded with {@link DataInput modified UTF-8}.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this stream.
- *
+ * if an I/O error occurs while reading.
* @see DataOutput#writeUTF(java.lang.String)
*/
public abstract String readUTF() throws IOException;
/**
- * Skips <code>count</code> number of bytes in this stream. Subsequent
- * <code>read()</code>'s will not return these bytes unless
- * <code>reset()</code> is used.
+ * Skips {@code count} number of bytes. This method will not throw an
+ * {@link EOFException} if the end of the input is reached before
+ * {@code count} bytes where skipped.
*
* @param count
* the number of bytes to skip.
* @return the number of bytes actually skipped.
- *
* @throws IOException
- * If a problem occurs reading from this stream.
+ * if a problem occurs during skipping.
*/
public abstract int skipBytes(int count) throws IOException;
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java Fri May 1 08:08:59 2009
@@ -21,10 +21,11 @@
import org.apache.harmony.luni.util.Util;
/**
- * DataInputStream is a filter class which can read typed data from a Stream.
+ * Wraps an existing {@link InputStream} and reads typed data from it.
* Typically, this stream has been written by a DataOutputStream. Types that can
* be read include byte, 16-bit short, 32-bit int, 32-bit float, 64-bit long,
- * 64-bit double, byte strings, and UTF Strings.
+ * 64-bit double, byte strings, and strings encoded in
+ * {@link DataInput modified UTF-8}.
*
* @see DataOutputStream
*/
@@ -33,14 +34,13 @@
byte[] buff;
/**
- * Constructs a new DataInputStream on the InputStream <code>in</code>.
- * All reads can now be filtered through this stream. Note that data read by
- * this Stream is not in a human readable format and was most likely created
- * by a DataOutputStream.
+ * Constructs a new DataInputStream on the InputStream {@code in}. All
+ * reads are then filtered through this stream. Note that data read by this
+ * stream is not in a human readable format and was most likely created by a
+ * DataOutputStream.
*
* @param in
- * the target InputStream to filter reads on.
- *
+ * the source InputStream the filter reads from.
* @see DataOutputStream
* @see RandomAccessFile
*/
@@ -50,16 +50,15 @@
}
/**
- * Reads bytes from the source stream into the byte array
- * <code>buffer</code>. The number of bytes actually read is returned.
+ * Reads bytes from this stream into the byte array {@code buffer}. Returns
+ * the number of bytes that have been read.
*
* @param buffer
- * the buffer to read bytes into
- * @return the number of bytes actually read or -1 if end of stream.
- *
+ * the buffer to read bytes into.
+ * @return the number of bytes that have been read or -1 if the end of the
+ * stream has been reached.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#write(byte[])
* @see DataOutput#write(byte[], int, int)
*/
@@ -69,22 +68,22 @@
}
/**
- * Read at most <code>length</code> bytes from this DataInputStream and
- * stores them in byte array <code>buffer</code> starting at
- * <code>offset</code>. Answer the number of bytes actually read or -1 if
- * no bytes were read and end of stream was encountered.
+ * Reads at most {@code length} bytes from this stream and stores them in
+ * the byte array {@code buffer} starting at {@code offset}. Returns the
+ * number of bytes that have been read or -1 if no bytes have been read and
+ * the end of the stream has been reached.
*
* @param buffer
- * the byte array in which to store the read bytes.
+ * the byte array in which to store the bytes read.
* @param offset
- * the offset in <code>buffer</code> to store the read bytes.
+ * the initial position in {@code buffer} to store the bytes
+ * read from this stream.
* @param length
- * the maximum number of bytes to store in <code>buffer</code>.
- * @return the number of bytes actually read or -1 if end of stream.
- *
+ * the maximum number of bytes to store in {@code buffer}.
+ * @return the number of bytes that have been read or -1 if the end of the
+ * stream has been reached.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#write(byte[])
* @see DataOutput#write(byte[], int, int)
*/
@@ -98,10 +97,11 @@
* Reads a boolean from this stream.
*
* @return the next boolean value from the source stream.
- *
+ * @throws EOFException
+ * if the end of the filtered stream is reached before one byte
+ * has been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeBoolean(boolean)
*/
public final boolean readBoolean() throws IOException {
@@ -116,10 +116,11 @@
* Reads an 8-bit byte value from this stream.
*
* @return the next byte value from the source stream.
- *
+ * @throws EOFException
+ * if the end of the filtered stream is reached before one byte
+ * has been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeByte(int)
*/
public final byte readByte() throws IOException {
@@ -133,11 +134,12 @@
/**
* Reads a 16-bit character value from this stream.
*
- * @return the next <code>char</code> value from the source stream.
- *
+ * @return the next char value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before two bytes
+ * have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeChar(int)
*/
private int readToBuff(int count) throws IOException {
@@ -160,13 +162,14 @@
}
/**
- * Reads a 64-bit <code>double</code> value from this stream.
- *
- * @return the next <code>double</code> value from the source stream.
+ * Reads a 64-bit double value from this stream.
*
+ * @return the next double value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before eight
+ * bytes have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeDouble(double)
*/
public final double readDouble() throws IOException {
@@ -174,13 +177,14 @@
}
/**
- * Reads a 32-bit <code>float</code> value from this stream.
- *
- * @return the next <code>float</code> value from the source stream.
+ * Reads a 32-bit float value from this stream.
*
+ * @return the next float value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before four
+ * bytes have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeFloat(float)
*/
public final float readFloat() throws IOException {
@@ -188,16 +192,17 @@
}
/**
- * Reads bytes from this stream into the byte array <code>buffer</code>.
- * This method will block until <code>buffer.length</code> number of bytes
- * have been read.
+ * Reads bytes from this stream into the byte array {@code buffer}. This
+ * method will block until {@code buffer.length} number of bytes have been
+ * read.
*
* @param buffer
- * to read bytes into
- *
+ * to read bytes into.
+ * @throws EOFException
+ * if the end of the source stream is reached before enough
+ * bytes have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#write(byte[])
* @see DataOutput#write(byte[], int, int)
*/
@@ -206,22 +211,28 @@
}
/**
- * Reads bytes from this stream and stores them in the byte array
- * <code>buffer</code> starting at the position <code>offset</code>.
- * This method blocks until <code>count</code> bytes have been read.
+ * Reads bytes from this stream and stores them in the byte array {@code
+ * buffer} starting at the position {@code offset}. This method blocks until
+ * {@code length} bytes have been read. If {@code length} is zero, then this
+ * method returns without reading any bytes.
*
* @param buffer
- * the byte array into which the data is read
+ * the byte array into which the data is read.
* @param offset
- * the offset the operation start at
+ * the offset in {@code buffer} from where to store the bytes
+ * read.
* @param length
- * the maximum number of bytes to read
- *
- * @throws IOException
- * if a problem occurs while reading from this stream
+ * the maximum number of bytes to read.
* @throws EOFException
- * if reaches the end of the stream before enough bytes have
- * been read
+ * if the end of the source stream is reached before enough
+ * bytes have been read.
+ * @throws IndexOutOfBoundsException
+ * if {@code offset < 0} or {@code length < 0}, or if {@code
+ * offset + length} is greater than the size of {@code buffer}.
+ * @throws IOException
+ * if a problem occurs while reading from this stream.
+ * @throws NullPointerException
+ * if {@code buffer} or the source stream are null.
* @see java.io.DataInput#readFully(byte[], int, int)
*/
public final void readFully(byte[] buffer, int offset, int length)
@@ -254,11 +265,12 @@
/**
* Reads a 32-bit integer value from this stream.
*
- * @return the next <code>int</code> value from the source stream.
- *
+ * @return the next int value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before four
+ * bytes have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeInt(int)
*/
public final int readInt() throws IOException {
@@ -270,20 +282,16 @@
}
/**
- * Answers a <code>String</code> representing the next line of text
- * available in this BufferedReader. A line is represented by 0 or more
- * characters followed by <code>'\n'</code>, <code>'\r'</code>,
- * <code>"\n\r"</code> or end of stream. The <code>String</code> does
- * not include the newline sequence.
- *
- * @return the contents of the line or null if no characters were read
- * before end of stream.
+ * Returns a string that contains the next line of text available from the
+ * source stream. A line is represented by zero or more characters followed
+ * by {@code '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream.
+ * The string does not include the newline sequence.
*
+ * @return the contents of the line or {@code null} if no characters were
+ * read before the end of the source stream has been reached.
* @throws IOException
- * If the DataInputStream is already closed or some other IO
- * error occurs.
- *
- * @deprecated Use BufferedReader
+ * if a problem occurs while reading from this stream.
+ * @deprecated Use {@link BufferedReader}
*/
@Deprecated
public final String readLine() throws IOException {
@@ -321,13 +329,14 @@
}
/**
- * Reads a 64-bit <code>long</code> value from this stream.
- *
- * @return the next <code>long</code> value from the source stream.
+ * Reads a 64-bit long value from this stream.
*
+ * @return the next long value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before eight
+ * bytes have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeLong(long)
*/
public final long readLong() throws IOException {
@@ -343,13 +352,14 @@
}
/**
- * Reads a 16-bit <code>short</code> value from this stream.
- *
- * @return the next <code>short</code> value from the source stream.
+ * Reads a 16-bit short value from this stream.
*
+ * @return the next short value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before two bytes
+ * have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeShort(int)
*/
public final short readShort() throws IOException {
@@ -360,14 +370,15 @@
}
/**
- * Reads an unsigned 8-bit <code>byte</code> value from this stream and
- * returns it as an int.
+ * Reads an unsigned 8-bit byte value from this stream and returns it as an
+ * int.
*
* @return the next unsigned byte value from the source stream.
- *
+ * @throws EOFException
+ * if the end of the filtered stream has been reached before one
+ * byte has been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeByte(int)
*/
public final int readUnsignedByte() throws IOException {
@@ -379,15 +390,15 @@
}
/**
- * Reads a 16-bit unsigned <code>short</code> value from this stream and
- * returns it as an int.
- *
- * @return the next unsigned <code>short</code> value from the source
- * stream.
+ * Reads a 16-bit unsigned short value from this stream and returns it as an
+ * int.
*
+ * @return the next unsigned short value from the source stream.
+ * @throws EOFException
+ * if the end of the filtered stream is reached before two bytes
+ * have been read.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeShort(int)
*/
public final int readUnsignedShort() throws IOException {
@@ -398,13 +409,15 @@
}
/**
- * Reads a UTF format String from this Stream.
- *
- * @return the next UTF String from the source stream.
+ * Reads an string encoded in {@link DataInput modified UTF-8} from this
+ * stream.
*
+ * @return the next {@link DataInput MUTF-8} encoded string read from the
+ * source stream.
+ * @throws EOFException if the end of the input is reached before the read
+ * request can be satisfied.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
+ * if a problem occurs while reading from this stream.
* @see DataOutput#writeUTF(java.lang.String)
*/
public final String readUTF() throws IOException {
@@ -425,33 +438,35 @@
}
/**
- * Reads a UTF format String from the DataInput Stream <code>in</code>.
+ * Reads a string encoded in {@link DataInput modified UTF-8} from the
+ * {@code DataInput} stream {@code in}.
*
* @param in
- * the input stream to read from
- * @return the next UTF String from the source stream.
- *
+ * the input stream to read from.
+ * @return the next {@link DataInput MUTF-8} encoded string from the source
+ * stream.
* @throws IOException
- * If a problem occurs reading from this DataInputStream.
- *
- * @see DataOutput#writeUTF(java.lang.String)
+ * if a problem occurs while reading from this stream.
+ * @see DataOutputStream#writeUTF(java.lang.String)
*/
public static final String readUTF(DataInput in) throws IOException {
return decodeUTF(in.readUnsignedShort(), in);
}
/**
- * Skips <code>count</code> number of bytes in this stream. Subsequent
- * <code>read()</code>'s will not return these bytes unless
- * <code>reset()</code> is used.
+ * Skips {@code count} number of bytes in this stream. Subsequent {@code
+ * read()}s will not return these bytes unless {@code reset()} is used.
*
+ * This method will not throw an {@link EOFException} if the end of the
+ * input is reached before {@code count} bytes where skipped.
+ *
* @param count
* the number of bytes to skip.
* @return the number of bytes actually skipped.
- *
* @throws IOException
- * If the stream is already closed or another IOException
- * occurs.
+ * if a problem occurs during skipping.
+ * @see #mark(int)
+ * @see #reset()
*/
public final int skipBytes(int count) throws IOException {
int skipped = 0;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java Fri May 1 08:08:59 2009
@@ -18,10 +18,11 @@
package java.io;
/**
- * DataOutput is an interface which declares methods for writing typed data to a
- * Stream. Typically, this stream can be read in by a class which implements
+ * Defines an interface for classes that are able to write typed data to some
+ * target. Typically, this data can be read in by a class which implements
* DataInput. Types that can be written include byte, 16-bit short, 32-bit int,
- * 32-bit float, 64-bit long, 64-bit double, byte strings, and UTF Strings.
+ * 32-bit float, 64-bit long, 64-bit double, byte strings, and {@link DataInput
+ * MUTF-8} encoded strings.
*
* @see DataOutputStream
* @see RandomAccessFile
@@ -29,35 +30,30 @@
public interface DataOutput {
/**
- * Writes the entire contents of the byte array <code>buffer</code> to the
- * OutputStream.
+ * Writes the entire contents of the byte array {@code buffer} to this
+ * stream.
*
* @param buffer
- * the buffer to be written
- *
+ * the buffer to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readFully(byte[])
* @see DataInput#readFully(byte[], int, int)
*/
- public abstract void write(byte buffer[]) throws IOException;
+ public abstract void write(byte[] buffer) throws IOException;
/**
- * Writes <code>count</code> <code>bytes</code> from the byte array
- * <code>buffer</code> starting at offset <code>index</code> to the
- * OutputStream.
+ * Writes {@code count} bytes from the byte array {@code buffer} starting at
+ * offset {@code index}.
*
* @param buffer
- * the buffer to be written
+ * the buffer to write.
* @param offset
- * offset in buffer to get bytes
+ * the index of the first byte in {@code buffer} to write.
* @param count
- * number of bytes in buffer to write
- *
+ * the number of bytes from the {@code buffer} to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readFully(byte[])
* @see DataInput#readFully(byte[], int, int)
*/
@@ -65,170 +61,143 @@
throws IOException;
/**
- * Writes the specified <code>byte</code> to the OutputStream.
+ * Writes the specified 8-bit byte.
*
* @param oneByte
- * the byte to be written
- *
+ * the byte to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readByte()
*/
public abstract void write(int oneByte) throws IOException;
/**
- * Writes a boolean to this output stream.
+ * Writes the specified boolean.
*
* @param val
- * the boolean value to write to the OutputStream
- *
+ * the boolean value to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readBoolean()
*/
public abstract void writeBoolean(boolean val) throws IOException;
/**
- * Writes a 8-bit byte to this output stream.
+ * Writes the specified 8-bit byte.
*
* @param val
- * the byte value to write to the OutputStream
- *
+ * the byte value to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readByte()
* @see DataInput#readUnsignedByte()
*/
public abstract void writeByte(int val) throws IOException;
/**
- * Writes the low order 8-bit bytes from a String to this output stream.
+ * Writes the low order 8-bit bytes from the specified string.
*
* @param str
- * the String containing the bytes to write to the OutputStream
- *
+ * the string containing the bytes to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readFully(byte[])
* @see DataInput#readFully(byte[],int,int)
*/
public abstract void writeBytes(String str) throws IOException;
/**
- * Writes the specified 16-bit character to the OutputStream. Only the lower
- * 2 bytes are written with the higher of the 2 bytes written first. This
- * represents the Unicode value of val.
- *
- * @param oneByte
- * the character to be written
+ * Writes the specified 16-bit character. Only the two least significant
+ * bytes of the integer {@code oneByte} are written, with the higher one
+ * written first. This represents the Unicode value of the char.
*
+ * @param val
+ * the character to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readChar()
*/
- public abstract void writeChar(int oneByte) throws IOException;
+ public abstract void writeChar(int val) throws IOException;
/**
- * Writes the specified 16-bit characters contained in str to the
- * OutputStream. Only the lower 2 bytes of each character are written with
- * the higher of the 2 bytes written first. This represents the Unicode
- * value of each character in str.
+ * Writes the 16-bit characters contained in {@code str}.
*
* @param str
- * the String whose characters are to be written.
- *
+ * the string that contains the characters to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readChar()
*/
public abstract void writeChars(String str) throws IOException;
/**
- * Writes a 64-bit double to this output stream. The resulting output is the
- * 8 bytes resulting from calling Double.doubleToLongBits().
+ * Writes the specified 64-bit double. The resulting output is the eight
+ * bytes returned by {@link Double#doubleToLongBits(double)}.
*
* @param val
- * the double to be written.
- *
+ * the double to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readDouble()
*/
public abstract void writeDouble(double val) throws IOException;
/**
- * Writes a 32-bit float to this output stream. The resulting output is the
- * 4 bytes resulting from calling Float.floatToIntBits().
+ * Writes the specified 32-bit float. The resulting output is the four bytes
+ * returned by {@link Float#floatToIntBits(float)}.
*
* @param val
- * the float to be written.
- *
+ * the float to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readFloat()
*/
public abstract void writeFloat(float val) throws IOException;
/**
- * Writes a 32-bit int to this output stream. The resulting output is the 4
- * bytes, highest order first, of val.
+ * Writes the specified 32-bit int. The resulting output is the four bytes,
+ * highest order first, of {@code val}.
*
* @param val
- * the int to be written.
- *
+ * the int to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readInt()
*/
public abstract void writeInt(int val) throws IOException;
/**
- * Writes a 64-bit long to this output stream. The resulting output is the 8
- * bytes, highest order first, of val.
+ * Writes the specified 64-bit long. The resulting output is the eight
+ * bytes, highest order first, of {@code val}.
*
* @param val
- * the long to be written.
- *
+ * the long to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readLong()
*/
public abstract void writeLong(long val) throws IOException;
/**
- * Writes the specified 16-bit short to the OutputStream. Only the lower 2
- * bytes are written with the higher of the 2 bytes written first.
+ * Writes the specified 16-bit short. Only the lower two bytes of {@code
+ * val} are written with the higher one written first.
*
* @param val
- * the short to be written
- *
+ * the short to write.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readShort()
* @see DataInput#readUnsignedShort()
*/
public abstract void writeShort(int val) throws IOException;
/**
- * Writes the specified String out in UTF format.
+ * Writes the specified string encoded in {@link DataInput modified UTF-8}.
*
* @param str
- * the String to be written in UTF format.
- *
+ * the string to write encoded in {@link DataInput modified UTF-8}.
* @throws IOException
- * If an error occurs attempting to write to this stream.
- *
+ * if an I/O error occurs while writing.
* @see DataInput#readUTF()
*/
public abstract void writeUTF(String str) throws IOException;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java Fri May 1 08:08:59 2009
@@ -20,27 +20,29 @@
import org.apache.harmony.luni.util.Msg;
/**
- * DataOutputStream is a filter class which can write typed data to a Stream.
- * Typically, this stream can be read in by a DataInputStream. Types that can be
+ * Wraps an existing {@link OutputStream} and writes typed data to it.
+ * Typically, this stream can be read in by DataInputStream. Types that can be
* written include byte, 16-bit short, 32-bit int, 32-bit float, 64-bit long,
- * 64-bit double, byte strings, and UTF Strings.
+ * 64-bit double, byte strings, and {@link DataInput MUTF-8} encoded strings.
*
* @see DataInputStream
*/
public class DataOutputStream extends FilterOutputStream implements DataOutput {
- /** The number of bytes written out so far */
+ /**
+ * The number of bytes written out so far.
+ */
protected int written;
byte buff[];
/**
- * Constructs a new DataOutputStream on the OutputStream <code>out</code>.
- * All writes can now be filtered through this stream. Note that data
- * written by this Stream is not in a human readable format but can be
- * reconstructed by using a DataInputStream on the resulting output.
+ * Constructs a new {@code DataOutputStream} on the {@code OutputStream}
+ * {@code out}. Note that data written by this stream is not in a human
+ * readable form but can be reconstructed by using a {@link DataInputStream}
+ * on the resulting output.
*
* @param out
- * the target OutputStream to filter writes on.
+ * the target stream for writing.
*/
public DataOutputStream(OutputStream out) {
super(out);
@@ -48,11 +50,11 @@
}
/**
- * Flush this DataOutputStream to ensure all pending data is sent out to the
- * target OutputStream. This implementation flushes the target OutputStream.
+ * Flushes this stream to ensure all pending data is sent out to the target
+ * stream. This implementation then also flushes the target stream.
*
* @throws IOException
- * If an error occurs attempting to flush this DataOutputStream.
+ * if an error occurs attempting to flush this stream.
*/
@Override
public void flush() throws IOException {
@@ -60,9 +62,9 @@
}
/**
- * Answers the total number of bytes written to this stream thus far.
+ * Returns the total number of bytes written to the target stream so far.
*
- * @return the number of bytes written to this DataOutputStream.
+ * @return the number of bytes written to the target stream.
*/
public final int size() {
if (written < 0) {
@@ -72,23 +74,21 @@
}
/**
- * Writes <code>count</code> <code>bytes</code> from the byte array
- * <code>buffer</code> starting at offset <code>index</code> to the
- * OutputStream.
+ * Writes {@code count} bytes from the byte array {@code buffer} starting at
+ * {@code offset} to the target stream.
*
* @param buffer
- * the buffer to be written
+ * the buffer to write to the target stream.
* @param offset
- * offset in buffer to get bytes
+ * the index of the first byte in {@code buffer} to write.
* @param count
- * number of bytes in buffer to write
- *
+ * the number of bytes from the {@code buffer} to write.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readFully(byte[])
- * @see DataInput#readFully(byte[], int, int)
+ * if an error occurs while writing to the target stream.
+ * @throws NullPointerException
+ * if {@code buffer} is {@code null}.
+ * @see DataInputStream#readFully(byte[])
+ * @see DataInputStream#readFully(byte[], int, int)
*/
@Override
public void write(byte buffer[], int offset, int count) throws IOException {
@@ -100,16 +100,14 @@
}
/**
- * Writes the specified <code>byte</code> to the OutputStream.
+ * Writes a byte to the target stream. Only the least significant byte of
+ * the integer {@code oneByte} is written.
*
* @param oneByte
- * the byte to be written
- *
+ * the byte to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readByte()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readByte()
*/
@Override
public void write(int oneByte) throws IOException {
@@ -118,16 +116,13 @@
}
/**
- * Writes a boolean to this output stream.
+ * Writes a boolean to the target stream.
*
* @param val
- * the boolean value to write to the OutputStream
- *
+ * the boolean value to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readBoolean()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readBoolean()
*/
public final void writeBoolean(boolean val) throws IOException {
out.write(val ? 1 : 0);
@@ -135,17 +130,15 @@
}
/**
- * Writes a 8-bit byte to this output stream.
+ * Writes an 8-bit byte to the target stream. Only the least significant
+ * byte of the integer {@code val} is written.
*
* @param val
- * the byte value to write to the OutputStream
- *
+ * the byte value to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readByte()
- * @see DataInput#readUnsignedByte()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readByte()
+ * @see DataInputStream#readUnsignedByte()
*/
public final void writeByte(int val) throws IOException {
out.write(val);
@@ -153,17 +146,14 @@
}
/**
- * Writes the low order 8-bit bytes from a String to this output stream.
+ * Writes the low order bytes from a string to the target stream.
*
* @param str
- * the String containing the bytes to write to the OutputStream
- *
+ * the string containing the bytes to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readFully(byte[])
- * @see DataInput#readFully(byte[],int,int)
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readFully(byte[])
+ * @see DataInputStream#readFully(byte[],int,int)
*/
public final void writeBytes(String str) throws IOException {
if (str.length() == 0) {
@@ -178,18 +168,15 @@
}
/**
- * Writes the specified 16-bit character to the OutputStream. Only the lower
- * 2 bytes are written with the higher of the 2 bytes written first. This
- * represents the Unicode value of val.
+ * Writes a 16-bit character to the target stream. Only the two lower bytes
+ * of the integer {@code val} are written, with the higher one written
+ * first. This corresponds to the Unicode value of {@code val}.
*
* @param val
- * the character to be written
- *
+ * the character to write to the target stream
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readChar()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readChar()
*/
public final void writeChar(int val) throws IOException {
buff[0] = (byte) (val >> 8);
@@ -199,19 +186,15 @@
}
/**
- * Writes the specified 16-bit characters contained in str to the
- * OutputStream. Only the lower 2 bytes of each character are written with
- * the higher of the 2 bytes written first. This represents the Unicode
- * value of each character in str.
+ * Writes the 16-bit characters contained in {@code str} to the target
+ * stream.
*
* @param str
- * the String whose characters are to be written.
- *
+ * the string that contains the characters to write to this
+ * stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readChar()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readChar()
*/
public final void writeChars(String str) throws IOException {
byte newBytes[] = new byte[str.length() * 2];
@@ -225,51 +208,42 @@
}
/**
- * Writes a 64-bit double to this output stream. The resulting output is the
- * 8 bytes resulting from calling Double.doubleToLongBits().
+ * Writes a 64-bit double to the target stream. The resulting output is the
+ * eight bytes resulting from calling Double.doubleToLongBits().
*
* @param val
- * the double to be written.
- *
+ * the double to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readDouble()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readDouble()
*/
public final void writeDouble(double val) throws IOException {
writeLong(Double.doubleToLongBits(val));
}
/**
- * Writes a 32-bit float to this output stream. The resulting output is the
- * 4 bytes resulting from calling Float.floatToIntBits().
+ * Writes a 32-bit float to the target stream. The resulting output is the
+ * four bytes resulting from calling Float.floatToIntBits().
*
* @param val
- * the float to be written.
- *
+ * the float to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readFloat()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readFloat()
*/
public final void writeFloat(float val) throws IOException {
writeInt(Float.floatToIntBits(val));
}
/**
- * Writes a 32-bit int to this output stream. The resulting output is the 4
- * bytes, highest order first, of val.
+ * Writes a 32-bit int to the target stream. The resulting output is the
+ * four bytes, highest order first, of {@code val}.
*
* @param val
- * the int to be written.
- *
+ * the int to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readInt()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readInt()
*/
public final void writeInt(int val) throws IOException {
buff[0] = (byte) (val >> 24);
@@ -281,17 +255,14 @@
}
/**
- * Writes a 64-bit long to this output stream. The resulting output is the 8
- * bytes, highest order first, of val.
+ * Writes a 64-bit long to the target stream. The resulting output is the
+ * eight bytes, highest order first, of {@code val}.
*
* @param val
- * the long to be written.
- *
+ * the long to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readLong()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readLong()
*/
public final void writeLong(long val) throws IOException {
buff[0] = (byte) (val >> 56);
@@ -307,18 +278,16 @@
}
/**
- * Writes the specified 16-bit short to the OutputStream. Only the lower 2
- * bytes are written with the higher of the 2 bytes written first.
+ * Writes the specified 16-bit short to the target stream. Only the lower
+ * two bytes of the integer {@code val} are written, with the higher one
+ * written first.
*
* @param val
- * the short to be written
- *
+ * the short to write to the target stream.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readShort()
- * @see DataInput#readUnsignedShort()
+ * if an error occurs while writing to the target stream.
+ * @see DataInputStream#readShort()
+ * @see DataInputStream#readUnsignedShort()
*/
public final void writeShort(int val) throws IOException {
buff[0] = (byte) (val >> 8);
@@ -328,16 +297,17 @@
}
/**
- * Writes the specified String out in UTF format.
+ * Writes the specified encoded in {@link DataInput modified UTF-8} to this
+ * stream.
*
* @param str
- * the String to be written in UTF format.
- *
+ * the string to write to the target stream encoded in
+ * {@link DataInput modified UTF-8}.
* @throws IOException
- * If an error occurs attempting to write to this
- * DataOutputStream.
- *
- * @see DataInput#readUTF()
+ * if an error occurs while writing to the target stream.
+ * @throws UTFDataFormatException
+ * if the encoded string is longer than 65535 bytes.
+ * @see DataInputStream#readUTF()
*/
public final void writeUTF(String str) throws IOException {
long utfCount = countUTFBytes(str);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java Fri May 1 08:08:59 2009
@@ -18,27 +18,26 @@
package java.io;
/**
- * This End Of File (EOF) exception is thrown when a program encounters the end
- * of a file or stream during an operation.
+ * Thrown when a program encounters the end of a file or stream during an input
+ * operation.
*/
public class EOFException extends IOException {
private static final long serialVersionUID = 6433858223774886977L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- *
+ * Constructs a new {@code EOFException} with its stack trace filled in.
*/
public EOFException() {
super();
}
/**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
+ * Constructs a new {@code EOFException} with its stack trace and detail
+ * message filled in.
*
* @param detailMessage
- * The detail message for the exception.
+ * the detail message for this exception.
*/
public EOFException(String detailMessage) {
super(detailMessage);
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java Fri May 1 08:08:59 2009
@@ -18,21 +18,19 @@
package java.io;
/**
- * Objects that want to be serialized/deserialized using
- * ObjectOutputStream/ObjectInputStream but defining their own byte
- * representation should implement this interface.
+ * Defines an interface for classes that want to be serializable, but have their
+ * own binary representation.
*/
public interface Externalizable extends Serializable {
/**
- * Reads the next object from the ObjectInput <code>input</code>
+ * Reads the next object from the ObjectInput <code>input</code>.
*
* @param input
- * the ObjectInput from which the next object is read
- *
+ * the ObjectInput from which the next object is read.
* @throws IOException
- * If an error occurs attempting to read from this ObjectInput.
+ * if an error occurs attempting to read from {@code input}.
* @throws ClassNotFoundException
- * If the class of the instance being loaded cannot be found
+ * if the class of the instance being loaded cannot be found.
*/
public void readExternal(ObjectInput input) throws IOException,
ClassNotFoundException;
@@ -41,10 +39,9 @@
* Writes the receiver to the ObjectOutput <code>output</code>.
*
* @param output
- * an ObjectOutput where to write the object
- *
+ * the ObjectOutput to write the object to.
* @throws IOException
- * If an error occurs attempting to write to the ObjectOutput.
+ * if an error occurs attempting to write to {@code output}.
*/
public void writeExternal(ObjectOutput output) throws IOException;
}