+2003-04-07 Aaron M. Renn (arenn@urbanophile.com)
+
+ * java/io/ObjectStreamException
+ * java/io/FileFilter
+ * java/io/FilenameFilter
+ * java/io/ObjectInput
+ * java/io/ObjectOutput
+ * java/io/ObjectStreamConstants
+ Minor doc fixes, format fixes, spelling corrections, etc.
+ * java/io/DataInput
+ Corrected code samples in Javadocs to match reality
+ * java/io/DataOutput
+ * java/io/ObjectInputValidation
+ Major documentation fixes - all Javadocs re-written or updated
+
2003-04-06 Michael Koch <konqueror@gmx.de>
* java/net/URLConnection.java:
* @exception EOFException If end of file is reached before reading the byte
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeBoolean
*/
byte readByte() throws EOFException, IOException;
* <p>
* This method can read an unsigned byte written by an object
* implementing the
- * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code>
+ * <code>writeByte()</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
+ * @see DataOutput#writeByte
*/
int readUnsignedByte() throws EOFException, IOException;
* @exception EOFException If end of file is reached before reading the char
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeChar
*/
char readChar() throws EOFException, IOException;
* 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>
+ * <code>(short)((byte1 << 8) + (byte2 & 0xFF))</code>
* <p>
* The value returned is in the range of -32768 to 32767.
* <p>
* @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeShort
*/
short readShort() throws EOFException, IOException;
* 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>
+ * <code>(int)(((byte1 0xFF) << 8) + (byte2 & 0xFF))</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
+ * the <code>writeShort()</code> method in the
* <code>DataOutput</code>
* interface.
*
* @exception EOFException If end of file is reached before reading
* the value
* @exception IOException If any other error occurs
+ *
+ * @see DataOutput#writeShort
*/
int readUnsignedShort() throws EOFException, IOException;
* 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>
+ * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) +
+ * ((byte3 & 0xFF)<< 8) + (byte4 & 0xFF)))</code>
* <p>
* The value returned is in the range of -2147483648 to 2147483647.
* <p>
* @exception EOFException If end of file is reached before reading the int
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeInt
*/
int readInt() throws EOFException, IOException;
* 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>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) +
+ * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) +
+ * ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) +
+ * ((byte7 & 0xFF) << 8) + (byte9 & 0xFF)))
* </code>
* <p>
* The value returned is in the range of -9223372036854775808 to
* @exception EOFException If end of file is reached before reading the long
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeLong
*/
long readLong() throws EOFException, IOException;
* float
* @exception IOException If any other error occurs
*
- * @see java.lang.Float
- * @see DataOutput
+ * @see DataOutput#writeFloat
+ * @see java.lang.Float#intBitsToFloat
*/
float readFloat() throws EOFException, IOException;
* double
* @exception IOException If any other error occurs
*
- * @see java.lang.Double
- * @see DataOutput
+ * @see DataOutput#writeDouble
+ * @see java.lang.Double#longBitsToDouble
*/
double readDouble() throws EOFException, IOException;
* 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.
+ * A line is also terminated by an end of file condition.
* <p>
* This method can read data that was written by an object implementing the
* <code>writeLine()</code> method in <code>DataOutput</code>.
*
* @exception IOException If an error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeLine
*/
String readLine() throws IOException;
* @exception UTFDataFormatException If the data is not in UTF-8 format
* @exception IOException If any other error occurs
*
- * @see DataOutput
+ * @see DataOutput#writeUTF
*/
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
+ * fill the buffer. Note also that zero length buffers are permitted.
+ * In this case, the method will return immediately without reading any
+ * bytes from the stream.
*
* @param buf The buffer into which to read the data
*
* <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.
+ * available and throws an exception if there is not enough data left in
+ * the stream to read <code>len</code> bytes. Note also that zero length
+ * buffers are permitted. In this case, the method will return immediately
+ * without reading any bytes from the stream.
*
* @param buf The buffer into which to read the data
* @param offset The offset into the buffer to start storing data
/**
* This method skips and discards the specified number of bytes in an
- * input stream
+ * input stream. Note that this method may skip less than the requested
+ * number of bytes. The actual number of bytes skipped is returned.
*
- * @param num_bytes The number of bytes to skip
+ * @param numBytes The number of bytes to skip
*
* @return The number of bytes actually skipped, which will always be
- * <code>num_bytes</code>
+ * <code>numBytes</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;
+ int skipBytes(int numBytes) throws EOFException, IOException;
} // interface DataInput
/* DataOutput.java -- Interface for writing data from a stream
- Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+ Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
/**
* This interface is implemented by classes that can wrte data to streams
- * from Java primitive types.
+ * from Java primitive types. This data can subsequently be read back
+ * by classes implementing the <code>DataInput</code> interface.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
* @author Tom Tromey <tromey@cygnus.com>
+ *
+ * @see DataInput
*/
public interface DataOutput
{
-
/**
- * This method writes a Java boolean value to an output stream
+ * This method writes a Java boolean value to an output stream. If
+ * <code>value</code> is <code>true</code>, a byte with the value of
+ * 1 will be written, otherwise a byte with the value of 0 will be
+ * written.
+ *
+ * The value written can be read using the <code>readBoolean</code>
+ * method in <code>DataInput</code>.
*
* @param value The boolean value to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readBoolean
*/
void writeBoolean(boolean value) throws IOException;
/**
- * This method writes a Java byte value to an output stream
+ * This method writes a Java byte value to an output stream. The
+ * byte to be written will be in the lowest 8 bits of the
+ * <code>int</code> value passed.
+ *
+ * The value written can be read using the <code>readByte</code> or
+ * <code>readUnsignedByte</code> methods in <code>DataInput</code>.
*
* @param value The int value to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readByte
+ * @see DataInput#readUnsignedByte
*/
void writeByte(int value) throws IOException;
/**
- * This method writes a Java char value to an output stream
+ * This method writes a Java char value to an output stream. The
+ * char to be written will be in the lowest 16 bits of the <code>int</code>
+ * value passed. These bytes will be written "big endian". That is,
+ * with the high byte written first in the following manner:
+ * <p>
+ * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
+ * byte1 = (byte)(value & 0x00FF);</code>
+ * <p>
+ *
+ * The value written can be read using the <code>readChar</code>
+ * method in <code>DataInput</code>.
*
* @param value The char value to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readChar
*/
void writeChar(int value) throws IOException;
/**
- * This method writes a Java int value to an output stream as a 16 bit value
+ * This method writes a Java char value to an output stream. The
+ * char to be written will be in the lowest 16 bits of the <code>int</code>
+ * value passed. These bytes will be written "big endian". That is,
+ * with the high byte written first in the following manner:
+ * <p>
+ * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
+ * byte1 = (byte)(value & 0x00FF);</code>
+ * <p>
+ *
+ * The value written can be read using the <code>readShort</code> and
+ * <code>readUnsignedShort</code> methods in <code>DataInput</code>.
*
* @param value The int value to write as a 16-bit value
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readShort
+ * @see DataInput#readUnsignedShort
*/
void writeShort(int value) throws IOException;
/**
- * This method writes a Java int value to an output stream
+ * This method writes a Java int value to an output stream. The 4 bytes
+ * of the passed value will be written "big endian". That is, with
+ * the high byte written first in the following manner:
+ * <p>
+ * <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br>
+ * byte1 = (byte)((value & 0x00FF0000) >> 16);<br>
+ * byte2 = (byte)((value & 0x0000FF00) >> 8);<br>
+ * byte3 = (byte)(value & 0x000000FF);</code>
+ * <p>
+ *
+ * The value written can be read using the <code>readInt</code>
+ * method in <code>DataInput</code>.
*
* @param value The int value to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readInt
*/
void writeInt(int value) throws IOException;
/**
- * This method writes a Java long value to an output stream
+ * This method writes a Java long value to an output stream. The 8 bytes
+ * of the passed value will be written "big endian". That is, with
+ * the high byte written first in the following manner:
+ * <p>
+ * <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br>
+ * byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br>
+ * byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br>
+ * byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br>
+ * byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br>
+ * byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br>
+ * byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br>
+ * byte7 = (byte)(value & 0x00000000000000FFL);</code>
+ * <p>
+ *
+ * The value written can be read using the <code>readLong</code>
+ * method in <code>DataInput</code>.
*
* @param value The long value to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readLong
*/
void writeLong(long value) throws IOException;
/**
- * This method writes a Java float value to an output stream
+ * This method writes a Java <code>float</code> value to the stream. This
+ * value is written by first calling the method
+ * <code>Float.floatToIntBits</code>
+ * to retrieve an <code>int</code> representing the floating point number,
+ * then writing this <code>int</code> value to the stream exactly the same
+ * as the <code>writeInt()</code> method does.
+ *
+ * The value written can be read using the <code>readFloat</code>
+ * method in <code>DataInput</code>.
*
* @param value The float value to write
*
* @exception IOException If an error occurs
+ *
+ * @see writeInt
+ * @see DataInput#readFloat
+ * @see Float#floatToIntBits
*/
void writeFloat(float value) throws IOException;
/**
- * This method writes a Java double value to an output stream
+ * This method writes a Java <code>double</code> value to the stream. This
+ * value is written by first calling the method
+ * <code>Double.doubleToLongBits</code>
+ * to retrieve an <code>long</code> representing the floating point number,
+ * then writing this <code>long</code> value to the stream exactly the same
+ * as the <code>writeLong()</code> method does.
+ *
+ * The value written can be read using the <code>readDouble</code>
+ * method in <code>DataInput</code>.
*
* @param value The double value to write
*
* @exception IOException If any other error occurs
+ *
+ * @see writeLong
+ * @see DataInput#readDouble
+ * @see Double#doubleToLongBits
*/
void writeDouble(double value) throws IOException;
/**
- * This method writes a String to an output stream as an array of bytes
+ * This method writes all the bytes in a <code>String</code> out to the
+ * stream. One byte is written for each character in the
+ * <code>String</code>.
+ * The high eight bits of each character are discarded, thus this
+ * method is inappropriate for completely representing Unicode characters.
*
- * @param value The String to write
+ * @param value The <code>String</code> 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
+ * This method writes all the bytes of a <code>String</code> to an
+ * output stream as an array of <code>char</code>'s. Each character
+ * is written using the method specified in the <code>writeChar</code>
+ * method.
*
* @param value The String to write
*
* @exception IOException If an error occurs
+ *
+ * @see writeChar
*/
void writeChars(String value) throws IOException;
/**
- * This method writes a String to an output stream encoded in
- * UTF-8 format.
+ * This method writes a Java <code>String</code> to the stream in a modified
+ * UTF-8 format. First, two bytes are written to the stream indicating the
+ * number of bytes to follow. This is written in the form of a Java
+ * <code>short</code> value in the same manner used by the
+ * <code>writeShort</code> method. Note that this is the number of
+ * bytes in the
+ * encoded <code>String</code> not the <code>String</code> length. Next
+ * come the encoded characters. Each character in the <code>String</code>
+ * is encoded as either one, two or three bytes. For characters in the
+ * range of <code>\u0001</code> to <code>\u007F</code>, one byte is used.
+ * The character
+ * value goes into bits 0-7 and bit eight is 0. For characters in the range
+ * of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used. Bits
+ * 6-10 of the character value are encoded bits 0-4 of the first byte, with
+ * the high bytes having a value of "110". Bits 0-5 of the character value
+ * are stored in bits 0-5 of the second byte, with the high bits set to
+ * "10". This type of encoding is also done for the null character
+ * <code>\u0000</code>. This eliminates any C style NUL character values
+ * in the output. All remaining characters are stored as three bytes.
+ * Bits 12-15 of the character value are stored in bits 0-3 of the first
+ * byte. The high bits of the first bytes are set to "1110". Bits 6-11
+ * of the character value are stored in bits 0-5 of the second byte. The
+ * high bits of the second byte are set to "10". And bits 0-5 of the
+ * character value are stored in bits 0-5 of byte three, with the high bits
+ * of that byte set to "10".
*
- * @param value The String to write
+ * The value written can be read using the <code>readUTF</code>
+ * method in <code>DataInput</code>.
+ *
+ * @param value The <code>String</code> to write
*
* @exception IOException If an error occurs
+ *
+ * @see DataInput#readUTF
*/
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.
+ * <code>int</code>) to an output stream. The low 8 bits of the
+ * passed value are written.
*
- * @param value The byte to write to the output stream
+ * @param value The <code>byte</code> to write to the output stream
*
* @exception IOException If an 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>.
+ * 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
/* FileFilter.java -- Filter a list of pathnames
- Copyright (C) 1998 Free Software Foundation, Inc.
+ Copyright (C) 1998,2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
/**
* 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.
+ * <code>File.listFiles(FileFilter)</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)
+ *
+ * @see File#listFiles(java.io.FileFilter)
*/
public interface FileFilter
{
/* FilenameFilter.java -- Filter a list of filenames
- Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+ Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
/**
* 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.
+ * <code>File.list(FilenameFilter)</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>
+ *
+ * @see File#listFiles(java.io.FilenameFilter)
+ * @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter)
*/
public interface FilenameFilter
{
-
/**
* This method determines whether or not a given file should be included
* in a directory listing.
* <code>InputStream</code>
*
* @author Aaron M. Renn (arenn@urbanophile.com)
+ *
+ * @see DataInput
*/
public interface ObjectInput extends DataInput
{
/**
* 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.
+ * as an <code>int</code>. This method blocks if no data is available
+ * to be read.
*
* @return The byte of data read
*
*
* @param buf The byte array to receive the data read
*
- * @return The actual number fo bytes read or -1 if end of stream
+ * @return The actual number of bytes read or -1 if end of stream
*
* @exception IOException If an error occurs
*/
* possible.
*
* @param buf The byte array to receive the data read
- * @param offset The offset into @code{buf} to start storing data
+ * @param offset The offset into <code>buf</code> to start storing data
* @param len The maximum number of bytes to read
*
- * @return The actual number fo bytes read or -1 if end of stream
+ * @return The actual number of bytes read or -1 if end of stream
*
* @exception IOException If an error occurs
*/
/**
* Reads an object instance and returns it. If the class for the object
- * being read cannot be found, then a ClassNotFoundException will
- * be thrown.
+ * being read cannot be found, then a <code>ClassNotFoundException</code>
+ * will be thrown.
*
* @return The object instance that was read
*
* @exception ClassNotFoundException If a class for the object cannot be
* found
- * @exception IOException If an error occurs
+ * @exception IOException If any other error occurs
*/
public abstract Object readObject()
throws ClassNotFoundException, IOException;
*
* @exception IOException If an error occurs
*/
- public abstract long skip(long num_bytes) throws IOException;
+ public abstract long skip(long numBytes) throws IOException;
/**
* This method closes the input source
package java.io;
/**
- * What does this interface really do?
+ * This class allows an object to validate that it is valid after
+ * deserialization has run completely for it and all dependent objects.
+ * This allows an object to determine if it is invalid even if all
+ * state data was correctly deserialized from the stream. It can also
+ * be used to perform re-initialization type activities on an object
+ * after it has been completely deserialized.
+ *
+ * Since this method functions as a type of callback, it must be
+ * registered through <code>ObjectInputStream.registerValidation</code>
+ * in order to be invoked. This is typically done in the
+ * <code>readObject</code> method.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
+ *
+ * @see ObjectInputStream#registerValidation
*/
public interface ObjectInputValidation
{
-
/**
- * This method is called to validate an object. If the object is invalid
- * an exception is thrown.
+ * This method is called to validate an object after serialization
+ * is complete. If the object is invalid an exception is thrown.
*
* @exception InvalidObjectException If the object is invalid
*/
* <code>OutputStream</code> like.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
+ *
+ * @see DataOutput
*/
public interface ObjectOutput extends DataOutput
{
-
/**
* This method writes the specified byte to the output stream.
*
/* ObjectStreamConstants.java -- Interface containing constant values
used in reading and writing serialized objects
- Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+ Copyright (C) 1998, 1999, 2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
package java.io;
/**
- This interface contains constants that are used in object
- serialization. This interface is used by ObjectOutputStream,
- ObjectInputStream, ObjectStreamClass, and possibly other classes.
- The values for these constants are specified in Javasoft's "Object
- Serialization Specification" TODO: add reference
-*/
+ * This interface contains constants that are used in object
+ * serialization. This interface is used by <code>ObjectOutputStream</code>,
+ * <code>ObjectInputStream</code>, and <code>ObjectStreamClass</code>.
+ * The values for these constants are specified by the Java library
+ * specification.
+ */
public interface ObjectStreamConstants
{
+ // FIXME: Javadoc comment these values.
public final static int PROTOCOL_VERSION_1 = 1;
public final static int PROTOCOL_VERSION_2 = 2;
final static SerializablePermission SUBCLASS_IMPLEMENTATION_PERMISSION
= new SerializablePermission("enableSubclassImplementation");
}
+
/* ObjectStreamException.java -- Superclass of all serialization exceptions
- Copyright (C) 1998, 2000, 2001, 2002 Free Software Foundation, Inc.
+ Copyright (C) 1998, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
This file is part of GNU Classpath.
/**
* This exception is thrown when a problem occurs during serialization.
- * There are more specific subclasses than give more fine grained
+ * There are more specific subclasses that give more fine grained
* indications of the precise failure.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
OSDN Git Service
