Commit 30da0969 by Aaron M. Renn Committed by Michael Koch

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

From-SVN: r65329
parent d5019ba3
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> 2003-04-06 Michael Koch <konqueror@gmx.de>
* java/net/URLConnection.java: * java/net/URLConnection.java:
......
...@@ -84,7 +84,7 @@ public interface DataInput ...@@ -84,7 +84,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the byte * @exception EOFException If end of file is reached before reading the byte
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeBoolean
*/ */
byte readByte() throws EOFException, IOException; byte readByte() throws EOFException, IOException;
...@@ -94,7 +94,7 @@ public interface DataInput ...@@ -94,7 +94,7 @@ public interface DataInput
* <p> * <p>
* This method can read an unsigned byte written by an object * This method can read an unsigned byte written by an object
* implementing the * implementing the
* <code>writeUnsignedByte()</code> method in the <code>DataOutput</code> * <code>writeByte()</code> method in the <code>DataOutput</code>
* interface. * interface.
* *
* @return The unsigned bytes value read as a Java <code>int</code>. * @return The unsigned bytes value read as a Java <code>int</code>.
...@@ -102,7 +102,7 @@ public interface DataInput ...@@ -102,7 +102,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the value * @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeByte
*/ */
int readUnsignedByte() throws EOFException, IOException; int readUnsignedByte() throws EOFException, IOException;
...@@ -128,7 +128,7 @@ public interface DataInput ...@@ -128,7 +128,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the char * @exception EOFException If end of file is reached before reading the char
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeChar
*/ */
char readChar() throws EOFException, IOException; char readChar() throws EOFException, IOException;
...@@ -143,7 +143,7 @@ public interface DataInput ...@@ -143,7 +143,7 @@ public interface DataInput
* first and second byte read from the stream respectively, they will be * first and second byte read from the stream respectively, they will be
* transformed to a <code>short</code> in the following manner: * transformed to a <code>short</code> in the following manner:
* <p> * <p>
* <code>(short)((byte1 << 8) + byte2)</code> * <code>(short)((byte1 << 8) + (byte2 & 0xFF))</code>
* <p> * <p>
* The value returned is in the range of -32768 to 32767. * The value returned is in the range of -32768 to 32767.
* <p> * <p>
...@@ -157,7 +157,7 @@ public interface DataInput ...@@ -157,7 +157,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the value * @exception EOFException If end of file is reached before reading the value
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeShort
*/ */
short readShort() throws EOFException, IOException; short readShort() throws EOFException, IOException;
...@@ -172,12 +172,12 @@ public interface DataInput ...@@ -172,12 +172,12 @@ public interface DataInput
* first and second byte read from the stream respectively, they will be * first and second byte read from the stream respectively, they will be
* transformed to an <code>int</code> in the following manner: * transformed to an <code>int</code> in the following manner:
* <p> * <p>
* <code>(int)((byte1 << 8) + byte2)</code> * <code>(int)(((byte1 0xFF) << 8) + (byte2 & 0xFF))</code>
* <p> * <p>
* The value returned is in the range of 0 to 65535. * The value returned is in the range of 0 to 65535.
* <p> * <p>
* This method can read an unsigned short written by an object implementing * 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> * <code>DataOutput</code>
* interface. * interface.
* *
...@@ -186,6 +186,8 @@ public interface DataInput ...@@ -186,6 +186,8 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading * @exception EOFException If end of file is reached before reading
* the value * the value
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
*
* @see DataOutput#writeShort
*/ */
int readUnsignedShort() throws EOFException, IOException; int readUnsignedShort() throws EOFException, IOException;
...@@ -200,7 +202,8 @@ public interface DataInput ...@@ -200,7 +202,8 @@ public interface DataInput
* the first four bytes read from the stream, they will be * the first four bytes read from the stream, they will be
* transformed to an <code>int</code> in the following manner: * transformed to an <code>int</code> in the following manner:
* <p> * <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> * <p>
* The value returned is in the range of -2147483648 to 2147483647. * The value returned is in the range of -2147483648 to 2147483647.
* <p> * <p>
...@@ -213,7 +216,7 @@ public interface DataInput ...@@ -213,7 +216,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the int * @exception EOFException If end of file is reached before reading the int
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeInt
*/ */
int readInt() throws EOFException, IOException; int readInt() throws EOFException, IOException;
...@@ -228,8 +231,10 @@ public interface DataInput ...@@ -228,8 +231,10 @@ public interface DataInput
* the first eight bytes read from the stream, they will be * the first eight bytes read from the stream, they will be
* transformed to an <code>long</code> in the following manner: * transformed to an <code>long</code> in the following manner:
* <p> * <p>
* <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) + * <code>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) +
* (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9)) * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) +
* ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) +
* ((byte7 & 0xFF) << 8) + (byte9 & 0xFF)))
* </code> * </code>
* <p> * <p>
* The value returned is in the range of -9223372036854775808 to * The value returned is in the range of -9223372036854775808 to
...@@ -244,7 +249,7 @@ public interface DataInput ...@@ -244,7 +249,7 @@ public interface DataInput
* @exception EOFException If end of file is reached before reading the long * @exception EOFException If end of file is reached before reading the long
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeLong
*/ */
long readLong() throws EOFException, IOException; long readLong() throws EOFException, IOException;
...@@ -267,8 +272,8 @@ public interface DataInput ...@@ -267,8 +272,8 @@ public interface DataInput
* float * float
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see java.lang.Float * @see DataOutput#writeFloat
* @see DataOutput * @see java.lang.Float#intBitsToFloat
*/ */
float readFloat() throws EOFException, IOException; float readFloat() throws EOFException, IOException;
...@@ -290,8 +295,8 @@ public interface DataInput ...@@ -290,8 +295,8 @@ public interface DataInput
* double * double
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see java.lang.Double * @see DataOutput#writeDouble
* @see DataOutput * @see java.lang.Double#longBitsToDouble
*/ */
double readDouble() throws EOFException, IOException; double readDouble() throws EOFException, IOException;
...@@ -309,6 +314,7 @@ public interface DataInput ...@@ -309,6 +314,7 @@ public interface DataInput
* A line terminator is a byte sequence consisting of either * A line terminator is a byte sequence consisting of either
* <code>\r</code>, <code>\n</code> or <code>\r\n</code>. These termination * <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. * charaters are discarded and are not returned as part of the string.
* A line is also terminated by an end of file condition.
* <p> * <p>
* This method can read data that was written by an object implementing the * This method can read data that was written by an object implementing the
* <code>writeLine()</code> method in <code>DataOutput</code>. * <code>writeLine()</code> method in <code>DataOutput</code>.
...@@ -317,7 +323,7 @@ public interface DataInput ...@@ -317,7 +323,7 @@ public interface DataInput
* *
* @exception IOException If an error occurs * @exception IOException If an error occurs
* *
* @see DataOutput * @see DataOutput#writeLine
*/ */
String readLine() throws IOException; String readLine() throws IOException;
...@@ -390,7 +396,7 @@ public interface DataInput ...@@ -390,7 +396,7 @@ public interface DataInput
* @exception UTFDataFormatException If the data is not in UTF-8 format * @exception UTFDataFormatException If the data is not in UTF-8 format
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
* *
* @see DataOutput * @see DataOutput#writeUTF
*/ */
String readUTF() throws EOFException, UTFDataFormatException, IOException; String readUTF() throws EOFException, UTFDataFormatException, IOException;
...@@ -398,7 +404,9 @@ public interface DataInput ...@@ -398,7 +404,9 @@ public interface DataInput
* This method reads raw bytes into the passed array until the array is * 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 * 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 * 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 * @param buf The buffer into which to read the data
* *
...@@ -414,8 +422,10 @@ public interface DataInput ...@@ -414,8 +422,10 @@ public interface DataInput
* <code>offset</code> bytes into the buffer. The number of bytes read * <code>offset</code> bytes into the buffer. The number of bytes read
* will be * will be
* exactly <code>len</code>. Note that this method blocks until the data is * 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 * available and throws an exception if there is not enough data left in
* the stream to read <code>len</code> bytes. * 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 buf The buffer into which to read the data
* @param offset The offset into the buffer to start storing data * @param offset The offset into the buffer to start storing data
...@@ -430,17 +440,18 @@ public interface DataInput ...@@ -430,17 +440,18 @@ public interface DataInput
/** /**
* This method skips and discards the specified number of bytes in an * 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 * @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 * @exception EOFException If end of file is reached before all bytes can be
* skipped * skipped
* @exception IOException If any other error occurs * @exception IOException If any other error occurs
*/ */
int skipBytes(int n) throws EOFException, IOException; int skipBytes(int numBytes) throws EOFException, IOException;
} // interface DataInput } // interface DataInput
/* FileFilter.java -- Filter a list of pathnames /* 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 file is part of GNU Classpath.
...@@ -41,12 +41,14 @@ package java.io; ...@@ -41,12 +41,14 @@ package java.io;
/** /**
* This interface has one method which is used for filtering pathnames * This interface has one method which is used for filtering pathnames
* returned in a pathname listing. It is currently used by the * returned in a pathname listing. It is currently used by the
* <code>File.listFiles()</code> method. * <code>File.listFiles(FileFilter)</code> method.
* <p> * <p>
* The method in this interface determines if a particular pathname should * The method in this interface determines if a particular pathname should
* or should not be included in the pathname listing. * or should not be included in the pathname listing.
* *
* @author Aaron M. Renn (arenn@urbanophile.com) * @author Aaron M. Renn (arenn@urbanophile.com)
*
* @see File#listFiles(java.io.FileFilter)
*/ */
public interface FileFilter public interface FileFilter
{ {
......
/* FilenameFilter.java -- Filter a list of filenames /* 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 file is part of GNU Classpath.
...@@ -46,17 +46,20 @@ package java.io; ...@@ -46,17 +46,20 @@ package java.io;
/** /**
* This interface has one method which is used for filtering filenames * This interface has one method which is used for filtering filenames
* returned in a directory listing. It is currently used by the * 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> * <p>
* The method in this interface determines if a particular file should * The method in this interface determines if a particular file should
* or should not be included in the file listing. * or should not be included in the file listing.
* *
* @author Aaron M. Renn (arenn@urbanophile.com) * @author Aaron M. Renn (arenn@urbanophile.com)
* @author Tom Tromey <tromey@cygnus.com> * @author Tom Tromey <tromey@cygnus.com>
*
* @see File#listFiles(java.io.FilenameFilter)
* @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter)
*/ */
public interface FilenameFilter public interface FilenameFilter
{ {
/** /**
* This method determines whether or not a given file should be included * This method determines whether or not a given file should be included
* in a directory listing. * in a directory listing.
......
...@@ -45,6 +45,8 @@ package java.io; ...@@ -45,6 +45,8 @@ package java.io;
* <code>InputStream</code> * <code>InputStream</code>
* *
* @author Aaron M. Renn (arenn@urbanophile.com) * @author Aaron M. Renn (arenn@urbanophile.com)
*
* @see DataInput
*/ */
public interface ObjectInput extends DataInput public interface ObjectInput extends DataInput
{ {
...@@ -60,7 +62,8 @@ public interface ObjectInput extends DataInput ...@@ -60,7 +62,8 @@ public interface ObjectInput extends DataInput
/** /**
* This method reading a byte of data from a stream. It returns that byte * 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 * @return The byte of data read
* *
...@@ -76,7 +79,7 @@ public interface ObjectInput extends DataInput ...@@ -76,7 +79,7 @@ public interface ObjectInput extends DataInput
* *
* @param buf The byte array to receive the 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 * @exception IOException If an error occurs
*/ */
...@@ -92,10 +95,10 @@ public interface ObjectInput extends DataInput ...@@ -92,10 +95,10 @@ public interface ObjectInput extends DataInput
* possible. * possible.
* *
* @param buf The byte array to receive the data read * @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 * @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 * @exception IOException If an error occurs
*/ */
...@@ -103,14 +106,14 @@ public interface ObjectInput extends DataInput ...@@ -103,14 +106,14 @@ public interface ObjectInput extends DataInput
/** /**
* Reads an object instance and returns it. If the class for the object * Reads an object instance and returns it. If the class for the object
* being read cannot be found, then a ClassNotFoundException will * being read cannot be found, then a <code>ClassNotFoundException</code>
* be thrown. * will be thrown.
* *
* @return The object instance that was read * @return The object instance that was read
* *
* @exception ClassNotFoundException If a class for the object cannot be * @exception ClassNotFoundException If a class for the object cannot be
* found * found
* @exception IOException If an error occurs * @exception IOException If any other error occurs
*/ */
public abstract Object readObject() public abstract Object readObject()
throws ClassNotFoundException, IOException; throws ClassNotFoundException, IOException;
...@@ -126,7 +129,7 @@ public interface ObjectInput extends DataInput ...@@ -126,7 +129,7 @@ public interface ObjectInput extends DataInput
* *
* @exception IOException If an error occurs * @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 * This method closes the input source
......
...@@ -39,16 +39,27 @@ exception statement from your version. */ ...@@ -39,16 +39,27 @@ exception statement from your version. */
package java.io; 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) * @author Aaron M. Renn (arenn@urbanophile.com)
*
* @see ObjectInputStream#registerValidation
*/ */
public interface ObjectInputValidation public interface ObjectInputValidation
{ {
/** /**
* This method is called to validate an object. If the object is invalid * This method is called to validate an object after serialization
* an exception is thrown. * is complete. If the object is invalid an exception is thrown.
* *
* @exception InvalidObjectException If the object is invalid * @exception InvalidObjectException If the object is invalid
*/ */
......
...@@ -45,10 +45,11 @@ package java.io; ...@@ -45,10 +45,11 @@ package java.io;
* <code>OutputStream</code> like. * <code>OutputStream</code> like.
* *
* @author Aaron M. Renn (arenn@urbanophile.com) * @author Aaron M. Renn (arenn@urbanophile.com)
*
* @see DataOutput
*/ */
public interface ObjectOutput extends DataOutput public interface ObjectOutput extends DataOutput
{ {
/** /**
* This method writes the specified byte to the output stream. * This method writes the specified byte to the output stream.
* *
......
/* ObjectStreamConstants.java -- Interface containing constant values /* ObjectStreamConstants.java -- Interface containing constant values
used in reading and writing serialized objects 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. This file is part of GNU Classpath.
...@@ -40,14 +40,15 @@ exception statement from your version. */ ...@@ -40,14 +40,15 @@ exception statement from your version. */
package java.io; package java.io;
/** /**
This interface contains constants that are used in object * This interface contains constants that are used in object
serialization. This interface is used by ObjectOutputStream, * serialization. This interface is used by <code>ObjectOutputStream</code>,
ObjectInputStream, ObjectStreamClass, and possibly other classes. * <code>ObjectInputStream</code>, and <code>ObjectStreamClass</code>.
The values for these constants are specified in Javasoft's "Object * The values for these constants are specified by the Java library
Serialization Specification" TODO: add reference * specification.
*/ */
public interface ObjectStreamConstants public interface ObjectStreamConstants
{ {
// FIXME: Javadoc comment these values.
public final static int PROTOCOL_VERSION_1 = 1; public final static int PROTOCOL_VERSION_1 = 1;
public final static int PROTOCOL_VERSION_2 = 2; public final static int PROTOCOL_VERSION_2 = 2;
...@@ -85,3 +86,4 @@ public interface ObjectStreamConstants ...@@ -85,3 +86,4 @@ public interface ObjectStreamConstants
final static SerializablePermission SUBCLASS_IMPLEMENTATION_PERMISSION final static SerializablePermission SUBCLASS_IMPLEMENTATION_PERMISSION
= new SerializablePermission("enableSubclassImplementation"); = new SerializablePermission("enableSubclassImplementation");
} }
/* ObjectStreamException.java -- Superclass of all serialization exceptions /* 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 file is part of GNU Classpath.
...@@ -40,7 +40,7 @@ package java.io; ...@@ -40,7 +40,7 @@ package java.io;
/** /**
* This exception is thrown when a problem occurs during serialization. * 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. * indications of the precise failure.
* *
* @author Aaron M. Renn (arenn@urbanophile.com) * @author Aaron M. Renn (arenn@urbanophile.com)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment