diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 39a86976748..9ad5618988f 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,15 @@ +2003-03-25 Michael Koch + + * java/io/FileInputStream.java + (read): Renamed b to buf and off to offset. + * java/io/FileOutputStream.java + (ch): Documentation added. + (FileOutputStream): Documentation added. + (getFD): Documentation added. + (write): Documentation added. + (close): Documentation added. + (getChannel): Documentation added. + 2003-03-24 Michael Koch * java/io/DataOutputStream.java diff --git a/libjava/java/io/FileInputStream.java b/libjava/java/io/FileInputStream.java index 533dd080461..50abeaa6e67 100644 --- a/libjava/java/io/FileInputStream.java +++ b/libjava/java/io/FileInputStream.java @@ -52,7 +52,6 @@ import gnu.java.nio.FileChannelImpl; * * @author Aaron M. Renn * @author Warren Levy - * @date October 28, 1998. */ public class FileInputStream extends InputStream { @@ -224,9 +223,9 @@ public class FileInputStream extends InputStream * * @exception IOException If an error occurs. */ - public int read(byte[] b) throws IOException + public int read(byte[] buf) throws IOException { - return fd.read(b, 0, b.length); + return read(buf, 0, buf.length); } /** @@ -248,12 +247,14 @@ public class FileInputStream extends InputStream * * @exception IOException If an error occurs. */ - public int read(byte[] b, int off, int len) throws IOException + public int read(byte[] buf, int offset, int len) throws IOException { - if (off < 0 || len < 0 || off + len > b.length) + if (offset < 0 + || len < 0 + || offset + len > buf.length) throw new ArrayIndexOutOfBoundsException(); - return fd.read(b, off, len); + return fd.read(buf, offset, len); } /** diff --git a/libjava/java/io/FileOutputStream.java b/libjava/java/io/FileOutputStream.java index ac823616c16..c0f8b268c4c 100644 --- a/libjava/java/io/FileOutputStream.java +++ b/libjava/java/io/FileOutputStream.java @@ -52,10 +52,29 @@ import gnu.java.nio.FileChannelImpl; */ public class FileOutputStream extends OutputStream { - // Instance variables. private FileDescriptor fd; - private FileChannel ch; - + + private FileChannel ch; /* cached associated file-channel */ + + /** + * This method initializes a FileOutputStream object to write + * to the named file. The file is created if it does not exist, and + * the bytes written are written starting at the beginning of the file if + * the append argument is false or at the end + * of the file if the append argument is true. + *

+ * Before opening a file, a security check is performed by calling the + * checkWrite method of the SecurityManager (if + * one exists) with the name of the file to be opened. An exception is + * thrown if writing is not allowed. + * + * @param name The name of the file this stream should write to + * @param append true to append bytes to the end of the file, + * or false to write bytes to the beginning + * + * @exception SecurityException If write access to the file is not allowed + * @exception FileNotFoundException If a non-security error occurs + */ public FileOutputStream (String path, boolean append) throws SecurityException, FileNotFoundException { @@ -67,12 +86,43 @@ public class FileOutputStream extends OutputStream : FileDescriptor.WRITE)); } + /** + * This method initializes a FileOutputStream object to write + * to the named file. The file is created if it does not exist, and + * the bytes written are written starting at the beginning of the file. + *

+ * Before opening a file, a security check is performed by calling the + * checkWrite method of the SecurityManager (if + * one exists) with the name of the file to be opened. An exception is + * thrown if writing is not allowed. + * + * @param name The name of the file this stream should write to + * + * @exception SecurityException If write access to the file is not allowed + * @exception FileNotFoundException If a non-security error occurs + */ public FileOutputStream (String path) throws SecurityException, FileNotFoundException { this (path, false); } + /** + * This method initializes a FileOutputStream object to write + * to the specified File object. The file is created if it + * does not exist, and the bytes written are written starting at the + * beginning of the file. + *

+ * Before opening a file, a security check is performed by calling the + * checkWrite method of the SecurityManager (if + * one exists) with the name of the file to be opened. An exception is + * thrown if writing is not allowed. + * + * @param file The File object this stream should write to + * + * @exception SecurityException If write access to the file is not allowed + * @exception FileNotFoundException If a non-security error occurs + */ public FileOutputStream (File file) throws SecurityException, FileNotFoundException { @@ -99,12 +149,28 @@ public class FileOutputStream extends OutputStream * @exception SecurityException If write access to the file is not allowed * @exception FileNotFoundException If a non-security error occurs */ - public - FileOutputStream(File file, boolean append) throws FileNotFoundException + public FileOutputStream (File file, boolean append) + throws FileNotFoundException { - this(file.getPath(), append); + this (file.getPath(), append); } + /** + * This method initializes a FileOutputStream object to write + * to the file represented by the specified FileDescriptor + * object. This method does not create any underlying disk file or + * reposition the file pointer of the given descriptor. It assumes that + * this descriptor is ready for writing as is. + *

+ * Before opening a file, a security check is performed by calling the + * checkWrite method of the SecurityManager (if + * one exists) with the specified FileDescriptor as an argument. + * An exception is thrown if writing is not allowed. + * + * @param file The FileDescriptor this stream should write to + * + * @exception SecurityException If write access to the file is not allowed + */ public FileOutputStream (FileDescriptor fdObj) throws SecurityException { @@ -120,6 +186,14 @@ public class FileOutputStream extends OutputStream // mentioned in the JCL. } + /** + * This method returns a FileDescriptor object representing + * the file that is currently being written to + * + * @return A FileDescriptor object for this stream + * + * @exception IOException If an error occurs + */ public final FileDescriptor getFD () throws IOException { if (! fd.valid()) @@ -127,16 +201,41 @@ public class FileOutputStream extends OutputStream return fd; } + /** + * This method writes a single byte of data to the file. + * + * @param b The byte of data to write, passed as an int + * + * @exception IOException If an error occurs + */ public void write (int b) throws IOException { fd.write (b); } + /** + * This method writes all the bytes in the specified array to the + * file. + * + * @param buf The array of bytes to write to the file + * + * @exception IOException If an error occurs + */ public void write (byte[] b) throws IOException, NullPointerException { fd.write (b, 0, b.length); } + /** + * This method writes len bytes from the byte array + * buf to the file starting at index offset. + * + * @param buf The array of bytes to write to the file + * @param offset The offset into the array to start writing bytes from + * @param len The number of bytes to write to the file + * + * @exception IOException If an error occurs + */ public void write (byte[] b, int off, int len) throws IOException, NullPointerException, IndexOutOfBoundsException { @@ -145,12 +244,25 @@ public class FileOutputStream extends OutputStream fd.write (b, off, len); } + /** + * This method closes the underlying file. Any further attempts to + * write to this stream will likely generate an exception since the + * file is closed. + * + * @exception IOException If an error occurs + */ public void close () throws IOException { if (fd.valid()) fd.close(); } + /** + * This method creates a java.nio.channels.FileChannel. + * Nio does not allow one to create a file channel directly. + * A file channel must be created by first creating an instance of + * Input/Output/RandomAccessFile and invoking the getChannel() method on it. + */ public FileChannel getChannel () { synchronized (this)