From f3997ccf90496a4519cd8ec8f0985202b79f69d0 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Sun, 5 Aug 2001 22:41:30 +0000 Subject: [PATCH] StringWriter.java: Merged with Classpath. * java/io/StringWriter.java: Merged with Classpath. * java/io/InputStream.java: Merged with Classpath. * java/io/OutputStream.java: Merged with Classpath. * java/io/PushbackInputStream.java: Merged with Classpath. * java/io/CharArrayReader.java: Merged with Classpath. * java/io/CharArrayWriter.java: Merged with Classpath. From-SVN: r44652 --- libjava/ChangeLog | 9 + libjava/java/io/CharArrayReader.java | 286 +++++++++++++++++------ libjava/java/io/CharArrayWriter.java | 173 ++++++++++++-- libjava/java/io/InputStream.java | 207 ++++++++++++++-- libjava/java/io/OutputStream.java | 111 +++++++-- libjava/java/io/PushbackInputStream.java | 238 ++++++++++++++++--- libjava/java/io/StringWriter.java | 134 +++++++++-- 7 files changed, 979 insertions(+), 179 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 4eb7694b79f..c32cf36d691 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,12 @@ +2001-08-05 Tom Tromey + + * java/io/StringWriter.java: Merged with Classpath. + * java/io/InputStream.java: Merged with Classpath. + * java/io/OutputStream.java: Merged with Classpath. + * java/io/PushbackInputStream.java: Merged with Classpath. + * java/io/CharArrayReader.java: Merged with Classpath. + * java/io/CharArrayWriter.java: Merged with Classpath. + 2001-08-02 Tom Tromey * prims.cc (JNI_OnLoad): Don't declare. diff --git a/libjava/java/io/CharArrayReader.java b/libjava/java/io/CharArrayReader.java index d67c7c79f5c..4d4fca7fe65 100644 --- a/libjava/java/io/CharArrayReader.java +++ b/libjava/java/io/CharArrayReader.java @@ -1,43 +1,103 @@ -/* Copyright (C) 1998, 1999, 2001 Free Software Foundation +/* CharArrayReader.java -- Read an array of characters as a stream + Copyright (C) 1998, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ package java.io; /** - * @author Warren Levy - * @date October 16, 1998. - */ - -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. - * Status: Believed complete and correct - */ - + * This class permits an array of chars to be read as an input stream. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class CharArrayReader extends Reader { - /* An array of chars provided by the creator of the stream. */ + /** + * The array that contains the data supplied during read operations + */ protected char[] buf; - /* Position of the next char in buf to be read. */ + /** + * The array index of the next char to be read from the buffer + * buf + */ protected int pos; - /* The currently marked position in the stream. */ + /** + * The currently marked position in the stream. This defaults to 0, so a + * reset operation on the stream resets it to read from array index 0 in + * the buffer - even if the stream was initially created with an offset + * greater than 0 + */ protected int markedPos; - /* The index in buf one greater than the last valid character. */ + /** + * This indicates the maximum number of chars that can be read from this + * stream. It is the array index of the position after the last valid + * char in the buffer buf + */ protected int count; + /** + * Create a new CharArrayReader that will read chars from the passed + * in char array. This stream will read from the beginning to the end + * of the array. It is identical to calling an overloaded constructor + * as CharArrayReader(buf, 0, buf.length). + *

+ * Note that this array is not copied. If its contents are changed + * while this stream is being read, those changes will be reflected in the + * chars supplied to the reader. Please use caution in changing the + * contents of the buffer while this stream is open. + * + * @param buffer The char array buffer this stream will read from. + */ public CharArrayReader(char[] buffer) { this(buffer, 0, buffer.length); } + /** + * Create a new CharArrayReader that will read chars from the passed + * in char array. This stream will read from position + * offset in the array for a length of + * length chars past offset. If the + * stream is reset to a position before offset then + * more than length chars can be read from the stream. + * The length value should be viewed as the array index + * one greater than the last position in the buffer to read. + *

+ * Note that this array is not copied. If its contents are changed + * while this stream is being read, those changes will be reflected in the + * chars supplied to the reader. Please use caution in changing the + * contents of the buffer while this stream is open. + * + * @param buffer The char array buffer this stream will read from. + * @param offset The index into the buffer to start reading chars from + * @param length The number of chars to read from the buffer + */ public CharArrayReader(char[] buffer, int offset, int length) { super(); @@ -54,72 +114,130 @@ public class CharArrayReader extends Reader markedPos = pos; } + /** + * This method closes the stream. + */ public void close() { synchronized (lock) - { - buf = null; - } + { + buf = null; + } } + /** + * This method sets the mark position in this stream to the current + * position. Note that the readlimit parameter in this + * method does nothing as this stream is always capable of + * remembering all the chars int it. + *

+ * Note that in this class the mark position is set by default to + * position 0 in the stream. This is in constrast to some other + * stream types where there is no default mark position. + * + * @param readAheadLimit The number of chars this stream must + * remember. This parameter is ignored. + * + * @exception IOException If an error occurs + */ public void mark(int readAheadLimit) throws IOException { synchronized (lock) - { - if (buf == null) - throw new IOException("Stream closed"); - // readAheadLimit is ignored per Java Class Lib. book, p. 318. - markedPos = pos; - } + { + if (buf == null) + throw new IOException("Stream closed"); + // readAheadLimit is ignored per Java Class Lib. book, p. 318. + markedPos = pos; + } } + /** + * This method overrides the markSupported method in + * Reader in order to return true - + * indicating that this stream class supports mark/reset + * functionality. + * + * @return true to indicate that this class supports + * mark/reset. + */ public boolean markSupported() { return true; } + /** + * This method reads one char from the stream. The pos + * counter is advanced to the next char to be read. The char read + * is returned as an int in the range of 0-65535. If the stream + * position is already at the end of the buffer, no char is read and + * a -1 is returned in order to indicate the end of the stream. + * + * @return The char read, or -1 if end of stream + */ public int read() throws IOException { synchronized (lock) - { - if (buf == null) - throw new IOException("Stream closed"); + { + if (buf == null) + throw new IOException("Stream closed"); - if (pos < 0) - throw new ArrayIndexOutOfBoundsException(pos); + if (pos < 0) + throw new ArrayIndexOutOfBoundsException(pos); - if (pos < count) - return ((int) buf[pos++]) & 0xFFFF; - return -1; - } + if (pos < count) + return ((int) buf[pos++]) & 0xFFFF; + return -1; + } } + /** + * This method reads chars from the stream and stores them into a + * caller supplied buffer. It starts storing the data at index + * offset into the buffer and attempts to read + * len chars. This method can return before reading + * the number of chars requested if the end of the stream is + * encountered first. The actual number of chars read is returned. + * If no chars can be read because the stream is already at the end + * of stream position, a -1 is returned. + *

+ * This method does not block. + * + * @param b The array into which the chars read should be stored. + * @param off The offset into the array to start storing chars + * @param len The requested number of chars to read + * + * @return The actual number of chars read, or -1 if end of stream. + */ public int read(char[] b, int off, int len) throws IOException { synchronized (lock) - { - if (buf == null) - throw new IOException("Stream closed"); - - /* Don't need to check pos value, arraycopy will check it. */ - if (off < 0 || len < 0 || off + len > b.length) - throw new ArrayIndexOutOfBoundsException(); - - if (pos >= count) - return -1; - - int numChars = Math.min(count - pos, len); - System.arraycopy(buf, pos, b, off, numChars); - pos += numChars; - return numChars; - } + { + if (buf == null) + throw new IOException("Stream closed"); + + /* Don't need to check pos value, arraycopy will check it. */ + if (off < 0 || len < 0 || off + len > b.length) + throw new ArrayIndexOutOfBoundsException(); + + if (pos >= count) + return -1; + + int numChars = Math.min(count - pos, len); + System.arraycopy(buf, pos, b, off, numChars); + pos += numChars; + return numChars; + } } - /** Return true if more characters are available to be read. - * - * @specnote The JDK 1.3 API docs are wrong here. This method will - * return false if there are no more characters available. - */ + /** + * Return true if more characters are available to be read. + * + * @return true to indicate that this stream is ready + * to be read. + * + * @specnote The JDK 1.3 API docs are wrong here. This method will + * return false if there are no more characters available. + */ public boolean ready() throws IOException { if (buf == null) @@ -128,31 +246,49 @@ public class CharArrayReader extends Reader return (pos < count); } + /** + * This method sets the read position in the stream to the mark + * point by setting the pos variable equal to the + * mark variable. Since a mark can be set anywhere in + * the array, the mark/reset methods int this class can be used to + * provide random search capabilities for this type of stream. + */ public void reset() throws IOException { synchronized (lock) - { - if (buf == null) - throw new IOException("Stream closed"); + { + if (buf == null) + throw new IOException("Stream closed"); - pos = markedPos; - } + pos = markedPos; + } } + /** + * This method attempts to skip the requested number of chars in the + * input stream. It does this by advancing the pos value by the + * specified number of chars. It this would exceed the length of the + * buffer, then only enough chars are skipped to position the stream at + * the end of the buffer. The actual number of chars skipped is returned. + * + * @param n The requested number of chars to skip + * + * @return The actual number of chars skipped. + */ public long skip(long n) throws IOException { synchronized (lock) - { - if (buf == null) - throw new IOException("Stream closed"); - - // Even though the var numChars is a long, in reality it can never - // be larger than an int since the result of subtracting 2 positive - // ints will always fit in an int. Since we have to return a long - // anyway, numChars might as well just be a long. - long numChars = Math.min((long) (count - pos), n < 0 ? 0L : n); - pos += numChars; - return numChars; - } + { + if (buf == null) + throw new IOException("Stream closed"); + + // Even though the var numChars is a long, in reality it can never + // be larger than an int since the result of subtracting 2 positive + // ints will always fit in an int. Since we have to return a long + // anyway, numChars might as well just be a long. + long numChars = Math.min((long) (count - pos), n < 0 ? 0L : n); + pos += numChars; + return numChars; + } } } diff --git a/libjava/java/io/CharArrayWriter.java b/libjava/java/io/CharArrayWriter.java index 7bec5558a01..44db842fde5 100644 --- a/libjava/java/io/CharArrayWriter.java +++ b/libjava/java/io/CharArrayWriter.java @@ -1,43 +1,98 @@ -// CharArrayWriter.java - Character array output stream. +/* CharArrayWriter.java -- Write chars to a buffer + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999, 2001 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 25, 1998 - */ -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * Status: Complete to 1.1. - */ +package java.io; +/** + * This class allows data to be written to a char array buffer and + * and then retrieved by an application. The internal char array + * buffer is dynamically resized to hold all the data written. Please + * be aware that writing large amounts to data to this stream will + * cause large amounts of memory to be allocated. + *

+ * The size of the internal buffer defaults to 32 and it is resized + * in increments of 1024 chars. This behavior can be over-ridden by using the + * following two properties: + *

+ *

    + *
  • gnu.java.io.CharArrayWriter.initialBufferSize + *
  • gnu.java.io.CharArrayWriter.bufferIncrementSize + *
+ *

+ * There is a constructor that specified the initial buffer size and + * that is the preferred way to set that value because it it portable + * across all Java class library implementations. + *

+ * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public class CharArrayWriter extends Writer { + /** + * The default initial buffer size + */ + private static final int DEFAULT_INITIAL_BUFFER_SIZE = 32; + + /** + * This method initializes a new CharArrayWriter with + * the default buffer size of 32 chars. If a different initial + * buffer size is desired, see the constructor + * CharArrayWriter(int size). + */ public CharArrayWriter () { - this (32); + this (DEFAULT_INITIAL_BUFFER_SIZE); } + /** + * This method initializes a new CharArrayWriter with + * a specified initial buffer size. + * + * @param size The initial buffer size in chars + */ public CharArrayWriter (int size) { super (); buf = new char[size]; } + /** + * Closes the stream. This method is guaranteed not to free the contents + * of the internal buffer, which can still be retrieved. + */ public void close () { closed = true; } + /** + * This method flushes all buffered chars to the stream. + */ public void flush () throws IOException { synchronized (lock) @@ -47,6 +102,11 @@ public class CharArrayWriter extends Writer } } + /** + * This method discards all of the chars that have been written to the + * internal buffer so far by setting the count variable to + * 0. The internal buffer remains at its currently allocated size. + */ public void reset () { synchronized (lock) @@ -58,11 +118,31 @@ public class CharArrayWriter extends Writer } } + /** + * This method returns the number of chars that have been written to + * the buffer so far. This is the same as the value of the protected + * count variable. If the reset method is + * called, then this value is reset as well. Note that this method does + * not return the length of the internal buffer, but only the number + * of chars that have been written to it. + * + * @return The number of chars in the internal buffer + * + * @see reset + */ public int size () { return count; } + /** + * This method returns a char array containing the chars that have been + * written to this stream so far. This array is a copy of the valid + * chars in the internal buffer and its length is equal to the number of + * valid chars, not necessarily to the the length of the current + * internal buffer. Note that since this method allocates a new array, + * it should be used with caution when the internal buffer is very large. + */ public char[] toCharArray () { synchronized (lock) @@ -73,6 +153,15 @@ public class CharArrayWriter extends Writer } } + /** + * Returns the chars in the internal array as a String. The + * chars in the buffer are converted to characters using the system default + * encoding. There is an overloaded toString() method that + * allows an application specified character encoding to be used. + * + * @return A String containing the data written to this + * stream so far + */ public String toString () { synchronized (lock) @@ -81,6 +170,12 @@ public class CharArrayWriter extends Writer } } + /** + * This method writes the writes the specified char into the internal + * buffer. + * + * @param oneChar The char to be read passed as an int + */ public void write (int oneChar) throws IOException { synchronized (lock) @@ -93,6 +188,14 @@ public class CharArrayWriter extends Writer } } + /** + * This method writes len chars from the passed in array + * buf starting at index offset into that buffer + * + * @param buffer The char array to write data from + * @param offset The index into the buffer to start writing data from + * @param len The number of chars to write + */ public void write (char[] buffer, int offset, int len) throws IOException { synchronized (lock) @@ -107,6 +210,15 @@ public class CharArrayWriter extends Writer } } + /** + * This method writes len chars from the passed in + * String buf starting at index + * offset into the internal buffer. + * + * @param str The String to write data from + * @param offset The index into the string to start writing data from + * @param len The number of chars to write + */ public void write (String str, int offset, int len) throws IOException { synchronized (lock) @@ -121,6 +233,14 @@ public class CharArrayWriter extends Writer } } + /** + * This method writes all the chars that have been written to this stream + * from the internal buffer to the specified Writer. + * + * @param out The Writer to write to + * + * @exception IOException If an error occurs + */ public void writeTo (Writer out) throws IOException { synchronized (lock) @@ -129,6 +249,13 @@ public class CharArrayWriter extends Writer } } + /** + * This private method makes the buffer bigger when we run out of room + * by allocating a larger buffer and copying the valid chars from the + * old array into it. This is obviously slow and should be avoided by + * application programmers by setting their initial buffer size big + * enough to hold everything if possible. + */ private final void resize (int len) { if (count + len >= buf.length) @@ -142,10 +269,18 @@ public class CharArrayWriter extends Writer } } - // The character buffer. + /** + * The internal buffer where the data written is stored + */ protected char[] buf; - // Number of valid characters in buffer. + + /** + * The number of chars that have been written to the buffer + */ protected int count; - // True if stream is closed. + + /** + * True if the stream has been closed. + */ private boolean closed; } diff --git a/libjava/java/io/InputStream.java b/libjava/java/io/InputStream.java index 2da52b1afcd..0cf1f4322b2 100644 --- a/libjava/java/io/InputStream.java +++ b/libjava/java/io/InputStream.java @@ -1,56 +1,185 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* InputStream.java -- Base class for input + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ package java.io; /** - * @author Warren Levy - * @date October 2, 1998. - */ -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. - * Status: Believed complete and correct. - */ - + * This abstract class forms the base of the hierarchy of classes that read + * input as a stream of bytes. It provides a common set of methods for + * reading bytes from streams. Subclasses implement and extend these + * methods to read bytes from a particular input source such as a file + * or network connection. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public abstract class InputStream { + /** + * Default, no-arg, public constructor + */ public InputStream() { } + /** + * This method returns the number of bytes that can be read from this + * stream before a read can block. A return of 0 indicates that blocking + * might (or might not) occur on the very next read attempt. + *

+ * This method always returns 0 in this class + * + * @return The number of bytes that can be read before blocking could occur + * + * @exception IOException If an error occurs + */ public int available() throws IOException { return 0; } + /** + * This method closes the stream. Any futher attempts to read from the + * stream may generate an IOException + *

+ * This method does nothing in this class, but subclasses may override + * this method in order to provide additional functionality. + * + * @exception IOException If an error occurs, which can only happen + * in a subclass + */ public void close() throws IOException { // Do nothing } + /** + * This method marks a position in the input to which the stream can + * be "reset" by calling the reset() method. The + * parameter @code{readlimit} is the number of bytes that can be read + * from the stream after setting the mark before the mark becomes + * invalid. For example, if mark() is called with a + * read limit of 10, then when 11 bytes of data are read from the + * stream before the reset() method is called, then the + * mark is invalid and the stream object instance is not required to + * remember the mark. + *

+ * This method does nothing in this class, but subclasses may override it + * to provide mark/reset functionality. + * + * @param readLimit The number of bytes that can be read before the + * mark becomes invalid + */ public void mark(int readlimit) { // Do nothing } + /** + * This method returns a boolean that indicates whether the mark/reset + * methods are supported in this class. Those methods can be used to + * remember a specific point in the stream and reset the stream to that + * point. + *

+ * This method always returns false in this class, but + * subclasses can override this method to return true + * if they support mark/reset functionality. + * + * @return true if mark/reset functionality is + * supported, false otherwise + */ public boolean markSupported() { return false; } + /** + * This method reads an unsigned byte from the input stream and returns it + * as an int in the range of 0-255. This method also will return -1 if + * the end of the stream has been reached. + *

+ * This method will block until the byte can be read. + * + * @return The byte read or -1 if end of stream + * + * @exception IOException If an error occurs + */ public abstract int read() throws IOException; + /** + * This method reads bytes from a stream and stores them into a caller + * supplied buffer. This method attempts to completely fill the buffer, + * but can return before doing so. The actual number of bytes read is + * returned as an int. A -1 is returned to indicate the end of the stream. + *

+ * This method will block until some data can be read. + *

+ * This method operates by calling an overloaded read method like so: + * read(b, 0, b.length) + * + * @param b The buffer into which the bytes read will be stored. + * + * @return The number of bytes read or -1 if end of stream. + * + * @exception IOException If an error occurs. + */ public int read(byte[] b) throws IOException { return read(b, 0, b.length); } + /** + * This method read bytes from a stream and stores them into a + * caller supplied buffer. It starts storing the data at index + * off into the buffer and attempts to read + * len bytes. This method can return before reading the + * number of bytes requested. The actual number of bytes read is + * returned as an int. A -1 is returned to indicate the end of the + * stream. + *

+ * This method will block until some data can be read. + *

+ * This method operates by calling the single byte read() method + * in a loop until the desired number of bytes are read. The read loop + * stops short if the end of the stream is encountered or if an IOException + * is encountered on any read operation except the first. If the first + * attempt to read a bytes fails, the IOException is allowed to propagate + * upward. And subsequent IOException is caught and treated identically + * to an end of stream condition. Subclasses can (and should if possible) + * override this method to provide a more efficient implementation. + * + * @param b The array into which the bytes read should be stored + * @param off The offset into the array to start storing bytes + * @param len The requested number of bytes to read + * + * @return The actual number of bytes read, or -1 if end of stream. + * + * @exception IOException If an error occurs. + */ public int read(byte[] b, int off, int len) throws IOException { if (off < 0 || len < 0 || off + len > b.length) @@ -62,27 +191,55 @@ public abstract class InputStream for (i = 0; i < len; ++i) try - { - if ((ch = read()) < 0) - return i == 0 ? -1 : i; // EOF - b[off + i] = (byte) ch; - } + { + if ((ch = read()) < 0) + return i == 0 ? -1 : i; // EOF + b[off + i] = (byte) ch; + } catch (IOException ex) - { - // Only reading the first byte should cause an IOException. - if (i == 0) - throw ex; - return i; - } + { + // Only reading the first byte should cause an IOException. + if (i == 0) + throw ex; + return i; + } return i; } + /** + * This method resets a stream to the point where the + * mark() method was called. Any bytes that were read + * after the mark point was set will be re-read during subsequent + * reads. + *

+ * This method always throws an IOException in this class, but subclasses + * can override this method if they provide mark/reset functionality. + * + * @exception IOException Always thrown for this class + */ public void reset() throws IOException { throw new IOException("mark/reset not supported"); } + /** + * This method skips the specified number of bytes in the stream. It + * returns the actual number of bytes skipped, which may be less than the + * requested amount. + *

+ * This method reads and discards bytes into a byte array until the + * specified number of bytes were skipped or until either the end of stream + * is reached or a read attempt returns a short count. Subclasses can + * override this metho to provide a more efficient implementation where + * one exists. + * + * @param n The requested number of bytes to skip + * + * @return The actual number of bytes skipped. + * + * @exception IOException If an error occurs + */ public long skip(long n) throws IOException { // Throw away n bytes by reading them into a temp byte[]. diff --git a/libjava/java/io/OutputStream.java b/libjava/java/io/OutputStream.java index 46770394b22..d4d9a190cff 100644 --- a/libjava/java/io/OutputStream.java +++ b/libjava/java/io/OutputStream.java @@ -1,34 +1,95 @@ -// OutputStream.java - Send output bytes to output sink. +/* OutputStream.java -- Base class for byte output streams + Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 24, 1998 - */ -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * Status: Complete to version 1.1. - */ +package java.io; +/** + * This abstract class forms the base of the hierarchy of classes that + * write output as a stream of bytes. It provides a common set of methods + * for writing bytes to stream. Subclasses implement and/or extend these + * methods to write bytes in a particular manner or to a particular + * destination such as a file on disk or network connection. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public abstract class OutputStream { + /** + * This is the default no-argument constructor for this class. This method + * does nothing in this class. + */ + public OutputStream () + { + } + + /** + * This method writes a single byte to the output stream. The byte written + * is the low eight bits of the int passed and a argument. + *

+ * Subclasses must provide an implementation of this abstract method + * + * @param b The byte to be written to the output stream, passed as + * the low eight bits of an int + * + * @exception IOException If an error occurs + */ public abstract void write (int b) throws IOException; + /** + * This method all the writes bytes from the passed array to the + * output stream. This method is equivalent to write(b, 0, + * buf.length) which is exactly how it is implemented in this + * class. + * + * @param b The array of bytes to write + * + * @exception IOException If an error occurs + */ public void write (byte[] b) throws IOException, NullPointerException { write (b, 0, b.length); } + /** + * This method writes len bytes from the specified array + * b starting at index off into the array. + *

+ * This method in this class calls the single byte write() + * method in a loop until all bytes have been written. Subclasses should + * override this method if possible in order to provide a more efficent + * implementation. + * + * @param b The array of bytes to write from + * @param off The index into the array to start writing from + * @param len The number of bytes to write + * + * @exception IOException If an error occurs + */ public void write (byte[] b, int off, int len) throws IOException, NullPointerException, IndexOutOfBoundsException { @@ -38,10 +99,30 @@ public abstract class OutputStream write (b[off + i]); } + /** + * This method forces any data that may have been buffered to be written + * to the underlying output device. Please note that the host environment + * might perform its own buffering unbeknowst to Java. In that case, a + * write made (for example, to a disk drive) might be cached in OS + * buffers instead of actually being written to disk. + *

+ * This method in this class does nothing. + * + * @exception IOException If an error occurs + */ public void flush () throws IOException { } + /** + * This method closes the stream. Any internal or native resources + * associated with this stream are freed. Any subsequent attempt to + * access the stream might throw an exception. + *

+ * This method in this class does nothing. + * + * @exception IOException If an error occurs + */ public void close () throws IOException { } diff --git a/libjava/java/io/PushbackInputStream.java b/libjava/java/io/PushbackInputStream.java index 537e1dbec57..94c83ab742f 100644 --- a/libjava/java/io/PushbackInputStream.java +++ b/libjava/java/io/PushbackInputStream.java @@ -1,36 +1,86 @@ -/* Copyright (C) 1998, 1999, 2000 Free Software Foundation +/* PushbackInputStream.java -- An input stream that can unread bytes + Copyright (C) 1998, 1999, 2001, 2001 Free Software Foundation, Inc. - This file is part of libgcj. +This file is part of GNU Classpath. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ + package java.io; /** - * @author Warren Levy - * @date October 15, 1998. - */ -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * plus online API docs for JDK 1.2 beta from http://www.javasoft.com. - * Status: Believed complete and correct. - */ - + * This subclass of FilterInputStream provides the ability to + * unread data from a stream. It maintains an internal buffer of unread + * data that is supplied to the next read operation. This is conceptually + * similar to mark/reset functionality, except that in this case the + * position to reset the stream to does not need to be known in advance. + *

+ * The default pushback buffer size one byte, but this can be overridden + * by the creator of the stream. + *

+ * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class PushbackInputStream extends FilterInputStream { - /* Internal buffer array for data. */ + /** + * This is the default buffer size + */ + private static final int DEFAULT_BUFFER_SIZE = 1; + + /** + * This is the buffer that is used to store the pushed back data + */ protected byte[] buf; - /* The current position in the buffer. */ + /** + * This is the position in the buffer from which the next byte will be + * read. Bytes are stored in reverse order in the buffer, starting from + * buf[buf.length - 1] to buf[0]. Thus when + * pos is 0 the buffer is full and buf.length when + * it is empty + */ protected int pos; + /** + * This method initializes a PushbackInputStream to + * read from the * specified subordinate InputStream + * with a default pushback buffer * size of 1. + * + * @param in The subordinate stream to read from + */ public PushbackInputStream(InputStream in) { - this(in, 1); + this(in, DEFAULT_BUFFER_SIZE); } + /** + * This method initializes a PushbackInputStream to + * read from the specified subordinate InputStream with + * the specified buffer size + * + * @param in The subordinate InputStream to read from + * @param size The pushback buffer size to use + */ public PushbackInputStream(InputStream in, int size) { super(in); @@ -40,23 +90,72 @@ public class PushbackInputStream extends FilterInputStream pos = buf.length; } + /** + * This method returns the number of bytes that can be read from this + * stream before a read can block. A return of 0 indicates that blocking + * might (or might not) occur on the very next read attempt. + *

+ * This method will return the number of bytes available from the + * pushback buffer plus the number of bytes available from the + * underlying stream. + * + * @return The number of bytes that can be read before blocking could occur + * + * @exception IOException If an error occurs + */ public int available() throws IOException { return pos + super.available(); } - public void close() throws IOException + /** + * This method closes the stream and releases any associated resources. + * + * @exception IOException If an error occurs. + */ + public synchronized void close() throws IOException { buf = null; super.close(); } + /** + * This method returns false to indicate that it does + * not support mark/reset functionality. + * + * @return This method returns false to indicate that + * this class does not support mark/reset functionality + */ public boolean markSupported() { return false; } - public int read() throws IOException + /** + * This method always throws an IOException in this class because + * mark/reset functionality is not supported. + * + * @exception IOException Always thrown for this class + */ + public void reset() throws IOException + { + throw new IOException("Mark not supported in this class"); + } + + /** + * This method reads an unsigned byte from the input stream and returns it + * as an int in the range of 0-255. This method also will return -1 if + * the end of the stream has been reached. The byte returned will be read + * from the pushback buffer, unless the buffer is empty, in which case + * the byte will be read from the underlying stream. + *

+ * This method will block until the byte can be read. + * + * @return The byte read or -1 if end of stream + * + * @exception IOException If an error occurs + */ + public synchronized int read() throws IOException { if (pos < buf.length) return ((int) buf[pos++]) & 0xFF; @@ -64,7 +163,31 @@ public class PushbackInputStream extends FilterInputStream return super.read(); } - public int read(byte[] b, int off, int len) throws IOException + /** + * This method read bytes from a stream and stores them into a + * caller supplied buffer. It starts storing the data at index + * offset into the buffer and attempts to read + * len bytes. This method can return before reading the + * number of bytes requested. The actual number of bytes read is + * returned as an int. A -1 is returned to indicate the end of the + * stream. + *

+ * This method will block until some data can be read. + *

+ * This method first reads bytes from the pushback buffer in order to + * satisfy the read request. If the pushback buffer cannot provide all + * of the bytes requested, the remaining bytes are read from the + * underlying stream. + * + * @param b The array into which the bytes read should be stored + * @param off The offset into the array to start storing bytes + * @param len The requested number of bytes to read + * + * @return The actual number of bytes read, or -1 if end of stream. + * + * @exception IOException If an error occurs. + */ + public synchronized int read(byte[] b, int off, int len) throws IOException { if (off < 0 || len < 0 || off + len > b.length) throw new ArrayIndexOutOfBoundsException(); @@ -80,23 +203,68 @@ public class PushbackInputStream extends FilterInputStream return super.read(b, off, len); } - public void unread(int b) throws IOException + /** + * This method pushes a single byte of data into the pushback buffer. + * The byte pushed back is the one that will be returned as the first byte + * of the next read. + *

+ * If the pushback buffer is full, this method throws an exception. + *

+ * The argument to this method is an int. Only the low + * eight bits of this value are pushed back. + * + * @param b The byte to be pushed back, passed as an int + * + * @exception IOException If the pushback buffer is full. + */ + public synchronized void unread(int b) throws IOException { if (pos <= 0) - throw new IOException(); + throw new IOException("Insufficient space in pushback buffer"); buf[--pos] = (byte) b; } - public void unread(byte[] b) throws IOException + /** + * This method pushes all of the bytes in the passed byte array into + * the pushback bfer. These bytes are pushed in reverse order so that + * the next byte read from the stream after this operation will be + * b[0] followed by b[1], etc. + *

+ * If the pushback buffer cannot hold all of the requested bytes, an + * exception is thrown. + * + * @param b The byte array to be pushed back + * + * @exception IOException If the pushback buffer is full + */ + public synchronized void unread(byte[] b) throws IOException { unread(b, 0, b.length); } - public void unread(byte[] b, int off, int len) throws IOException + /** + * This method pushed back bytes from the passed in array into the + * pushback buffer. The bytes from b[offset] to + * b[offset + len] are pushed in reverse order so that + * the next byte read from the stream after this operation will be + * b[offset] followed by b[offset + 1], + * etc. + *

+ * If the pushback buffer cannot hold all of the requested bytes, an + * exception is thrown. + * + * @param b The byte array to be pushed back + * @param off The index into the array where the bytes to be push start + * @param len The number of bytes to be pushed. + * + * @exception IOException If the pushback buffer is full + */ + public synchronized void unread(byte[] b, int off, int len) + throws IOException { if (pos < len) - throw new IOException(); + throw new IOException("Insufficient space in pushback buffer"); // Note the order that these bytes are being added is the opposite // of what would be done if they were added to the buffer one at a time. @@ -108,8 +276,24 @@ public class PushbackInputStream extends FilterInputStream pos -= len; } - // JDK1.2 - public long skip(long n) throws IOException + /** + * This method skips the specified number of bytes in the stream. It + * returns the actual number of bytes skipped, which may be less than the + * requested amount. + *

+ * This method first discards bytes from the buffer, then calls the + * skip method on the underlying InputStream to + * skip additional bytes if necessary. + * + * @param num_bytes The requested number of bytes to skip + * + * @return The actual number of bytes skipped. + * + * @exception IOException If an error occurs + * + * @since 1.2 + */ + public synchronized long skip(long n) throws IOException { final long origN = n; diff --git a/libjava/java/io/StringWriter.java b/libjava/java/io/StringWriter.java index 92135437983..10cc3ec307f 100644 --- a/libjava/java/io/StringWriter.java +++ b/libjava/java/io/StringWriter.java @@ -1,27 +1,55 @@ -// StringWriter.java - StringBuffer output stream +/* StringWriter.java -- Writes bytes to a StringBuffer + Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc. -/* Copyright (C) 1998, 1999, 2000 Free Software Foundation +This file is part of GNU Classpath. - This file is part of libgcj. +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. -This software is copyrighted work licensed under the terms of the -Libgcj License. Please consult the file "LIBGCJ_LICENSE" for -details. */ +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. -package java.io; +As a special exception, if you link this library with other files to +produce an executable, this library does not by itself cause the +resulting executable to be covered by the GNU General Public License. +This exception does not however invalidate any other reasons why the +executable file might be covered by the GNU General Public License. */ -/** - * @author Tom Tromey - * @date September 25, 1998 - */ -/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3 - * "The Java Language Specification", ISBN 0-201-63451-1 - * Status: Complete to 1.2. - */ +package java.io; +// Wow is this a dumb class. CharArrayWriter can do all this and +// more. I would redirect all calls to one in fact, but the javadocs say +// use a StringBuffer so I will comply. + +/** + * This class writes chars to an internal StringBuffer that + * can then be used to retrieve a String. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Tom Tromey + */ public class StringWriter extends Writer { + /** + * This is the default size of the buffer if the user doesn't specify it. + * @specnote The JCL Volume 1 says that 16 is the default size. + */ + private static final int DEFAULT_BUFFER_SIZE = 16; + + /** + * This method closes the stream. The contents of the internal buffer + * can still be retrieved, but future writes are not guaranteed to work. + */ public void close () { // JCL says this does nothing. This seems to violate the Writer @@ -29,20 +57,42 @@ public class StringWriter extends Writer // IOException after a close. Still, we just follow JCL. } + /** + * This method flushes any buffered characters to the underlying output. + * It does nothing in this class. + */ public void flush () { } + /** + * This method returns the StringBuffer object that this + * object is writing to. Note that this is the actual internal buffer, so + * any operations performed on it will affect this stream object. + * + * @return The StringBuffer object being written to + */ public StringBuffer getBuffer () { return buffer; } + /** + * This method initializes a new StringWriter to write to a + * StringBuffer initially sized to a default size of 16 + * chars. + */ public StringWriter () { - this (16); + this (DEFAULT_BUFFER_SIZE); } + /** + * This method initializes a new StringWriter to write to a + * StringBuffer with the specified initial size. + * + * @param size The initial size to make the StringBuffer + */ public StringWriter (int size) { super (); @@ -50,31 +100,79 @@ public class StringWriter extends Writer lock = buffer; } + /** + * This method returns the contents of the internal StringBuffer + * as a String. + * + * @return A String representing the chars written to + * this stream. + */ public String toString () { return buffer.toString(); } + /** + * This method writes a single character to the output, storing it in + * the internal buffer. + * + * @param oneChar The char to write, passed as an int. + */ public void write (int oneChar) { - buffer.append((char) oneChar); + buffer.append((char) (oneChar & 0xFFFF)); } + /** + * This method writes len chars from the specified + * array starting at index offset in that array to this + * stream by appending the chars to the end of the internal buffer. + * + * @param chars The array of chars to write + * @param offset The index into the array to start writing from + * @param len The number of chars to write + */ public void write (char[] chars, int offset, int len) { buffer.append(chars, offset, len); } + /** + * This method writes the characters in the specified String + * to the stream by appending them to the end of the internal buffer. + * + * @param str The String to write to the stream. + */ public void write (String str) { buffer.append(str); } + /** + * This method writes out len characters of the specified + * String to the stream starting at character position + * offset into the stream. This is done by appending the + * characters to the internal buffer. + * + * @param str The String to write characters from + * @param offset The character position to start writing from + * @param len The number of characters to write. + */ public void write (String str, int offset, int len) { +// char[] tmpbuf = new char[len]; +// str.getChars(offset, offset+len, tmpbuf, 0); +// buf.append(tmpbuf, 0, tmpbuf.length); + // This implementation assumes that String.substring is more + // efficient than using String.getChars and copying the data + // twice. For libgcj, this is true. For Classpath, it is not. + // FIXME. buffer.append(str.substring(offset, offset + len)); } - // The string buffer. + /** + * This is the StringBuffer that we use to store bytes that + * are written. + */ private StringBuffer buffer; } -- 2.30.2