From ce0d5fce2b08fc33961ae31c2032b6abf5bd40da Mon Sep 17 00:00:00 2001 From: Mark Wielaard Date: Thu, 4 Oct 2001 05:34:47 +0000 Subject: [PATCH] SequenceInputStream.java: Merge with Classpath * java/io/SequenceInputStream.java: Merge with Classpath * java/io/StringBufferInputStream.java: Ditto * java/util/Collections.java: Remerge with Classpath From-SVN: r46005 --- libjava/ChangeLog | 6 + libjava/java/io/SequenceInputStream.java | 124 +++++++++++++++++-- libjava/java/io/StringBufferInputStream.java | 119 ++++++++++++++++-- libjava/java/util/Collections.java | 22 ++-- 4 files changed, 239 insertions(+), 32 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 450e0c894a4..b2767d02bbe 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,9 @@ +2001-10-03 Mark Wielaard + + * java/io/SequenceInputStream.java: Merge with Classpath + * java/io/StringBufferInputStream.java: Ditto + * java/util/Collections.java: Remerge with Classpath + 2001-10-03 Tom Tromey * java/lang/ref/natReference.cc (add_to_hash): Set n->next before diff --git a/libjava/java/io/SequenceInputStream.java b/libjava/java/io/SequenceInputStream.java index 054527774ab..f125953ebea 100644 --- a/libjava/java/io/SequenceInputStream.java +++ b/libjava/java/io/SequenceInputStream.java @@ -1,36 +1,76 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* SequenceInputStream.java -- Reads multiple input streams in sequence + Copyright (C) 1998, 1999, 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; import java.util.Enumeration; -/** - * @author Warren Levy - * @date November 3, 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 merges a sequence of multiple InputStream's in + * order to form a single logical stream that can be read by applications + * that expect only one stream. + *

+ * The streams passed to the constructor method are read in order until + * they return -1 to indicate they are at end of stream. When a stream + * reports end of stream, it is closed, then the next stream is read. + * When the last stream is closed, the next attempt to read from this + * stream will return a -1 to indicate it is at end of stream. + *

+ * If this stream is closed prior to all subordinate streams being read + * to completion, all subordinate streams are closed. + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class SequenceInputStream extends InputStream { - /* The handle for the current input stream. */ + /** The handle for the current input stream. */ private InputStream in; - /* Secondary input stream; not used if constructed w/ enumeration. */ + /** Secondary input stream; not used if constructed w/ enumeration. */ private InputStream in2; - /* The enum handle; not used if constructed w/ 2 explicit input streams. */ + /** The enum handle; not used if constructed w/ 2 explicit input streams. */ private Enumeration enum; + /** + * This method creates a new SequenceInputStream that obtains + * its list of subordinate InputStreams from the specified + * Enumeration + * + * @param e An Enumeration that will return a list of + * InputStreams to read in sequence + */ public SequenceInputStream(Enumeration e) { enum = e; @@ -38,12 +78,30 @@ public class SequenceInputStream extends InputStream in2 = null; } + /** + * This method creates a new SequenceInputStream that will read + * the two specified subordinate InputStreams in sequence. + * + * @param s1 The first InputStream to read + * @param s2 The second InputStream to read + */ public SequenceInputStream(InputStream s1, InputStream s2) { in = s1; in2 = s2; } + /** + * This method returns the number of bytes than can be read from the + * currently being read subordinate stream before that stream could + * block. Note that it is possible more bytes than this can actually + * be read without the stream blocking. If a 0 is returned, then the + * stream could block on the very next read. + * + * @return The number of bytes that can be read before blocking could occur + * + * @exception IOException If an error occurs + */ public int available() throws IOException { if (in == null) @@ -52,6 +110,13 @@ public class SequenceInputStream extends InputStream return in.available(); } + /** + * Closes this stream. This will cause any remaining unclosed subordinate + * InputStream's to be closed as well. Subsequent attempts to + * read from this stream may cause an exception. + * + * @exception IOException If an error occurs + */ public void close() throws IOException { while (in != null) @@ -61,6 +126,18 @@ public class SequenceInputStream extends InputStream } } + /** + * 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 will only happen when + * all of the subordinate streams have been read. + *

+ * 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 int read() throws IOException { int ch = -1; @@ -74,6 +151,25 @@ public class SequenceInputStream extends InputStream return ch; } + /** + * This method reads 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 returend to indicate the + * end of the stream. This will only happen when all of the subordinate + * streams have been read. + *

+ * This method will block until at least one byte can be read. + * + * @param b The array into which 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 { int ch = -1; @@ -89,6 +185,10 @@ public class SequenceInputStream extends InputStream return ch; } + /** + * This private method is used to get the next InputStream to + * read from. Returns null when no more streams are available. + */ private InputStream getNextStream() { InputStream nextIn = null; diff --git a/libjava/java/io/StringBufferInputStream.java b/libjava/java/io/StringBufferInputStream.java index 063e19d3fc7..40ef73cf9a4 100644 --- a/libjava/java/io/StringBufferInputStream.java +++ b/libjava/java/io/StringBufferInputStream.java @@ -1,46 +1,106 @@ -/* Copyright (C) 1998, 1999 Free Software Foundation +/* StringBufferInputStream.java -- Read an String as a stream + Copyright (C) 1998, 1999, 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 November 11, 1998. - * @deprecated - */ /* 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. Deprecated in JDK 1.1. */ +/** + * This class permits a String to be read as an input stream. + * The low eight bits of each character in the String are the + * bytes that are returned. The high eight bits of each character are + * discarded. + *

+ * The mark/reset functionality in this class behaves differently than + * normal. The mark() method is always ignored and the + * reset() method always resets in stream to start reading from + * position 0 in the String. Note that since this method does not override + * markSupported() in InputStream, calling that + * method will return false. + *

+ * Note that this class is deprecated because it does not properly handle + * 16-bit Java characters. It is provided for backwards compatibility only + * and should not be used for new development. The StringReader + * class should be used instead. + * + * @deprecated + * + * @author Aaron M. Renn (arenn@urbanophile.com) + * @author Warren Levy + */ public class StringBufferInputStream extends InputStream { - /* The String which is the input to this stream. */ + /** The String which is the input to this stream. */ protected String buffer; - /* Position of the next byte in buffer to be read. */ + /** Position of the next byte in buffer to be read. */ protected int pos = 0; - /* The length of the String buffer. */ + /** The length of the String buffer. */ protected int count; + /** + * Create a new StringBufferInputStream that will read bytes + * from the passed in String. This stream will read from the + * beginning to the end of the String. + * + * @param s The String this stream will read from. + */ public StringBufferInputStream(String s) { buffer = s; count = s.length(); } + /** + * This method returns the number of bytes available to be read from this + * stream. The value returned will be equal to count - pos. + * + * @return The number of bytes that can be read from this stream before + * blocking, which is all of them + */ public int available() { return count - pos; } + /** + * This method reads one byte from the stream. The pos counter + * is advanced to the next byte to be read. The byte read is returned as + * an int in the range of 0-255. If the stream position is already at the + * end of the buffer, no byte is read and a -1 is returned in order to + * indicate the end of the stream. + * + * @return The byte read, or -1 if end of stream + */ public int read() { if (pos >= count) @@ -49,6 +109,23 @@ public class StringBufferInputStream extends InputStream return ((int) buffer.charAt(pos++)) & 0xFF; } +/** + * This method reads bytes 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 bytes. This method + * can return before reading the number of bytes requested if the end of the + * stream is encountered first. The actual number of bytes read is + * returned. If no bytes 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 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. + */ public int read(byte[] b, int off, int len) { if (off < 0 || len < 0 || off + len > b.length) @@ -66,11 +143,27 @@ public class StringBufferInputStream extends InputStream return numRead; } + /** + * This method sets the read position in the stream to the beginning + * setting the pos variable equal to 0. Note that this differs + * from the common implementation of the reset() method. + */ public void reset() { pos = 0; } + /** + * This method attempts to skip the requested number of bytes in the + * input stream. It does this by advancing the pos value by the + * specified number of bytes. It this would exceed the length of the + * buffer, then only enough bytes are skipped to position the stream at + * the end of the buffer. The actual number of bytes skipped is returned. + * + * @param n The requested number of bytes to skip + * + * @return The actual number of bytes skipped. + */ public long skip(long n) { if (n < 0) diff --git a/libjava/java/util/Collections.java b/libjava/java/util/Collections.java index 74efdec65bf..3e2a40e554c 100644 --- a/libjava/java/util/Collections.java +++ b/libjava/java/util/Collections.java @@ -1,5 +1,5 @@ /* Collections.java -- Utility class with methods to operate on collections - Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc. + Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -595,7 +595,7 @@ public class Collections * of this method is Serializable. * * @param o the single element. - * @returns an immutable Set containing only o. + * @return an immutable Set containing only o. */ // It's not serializable because the spec is broken. public static Set singleton(final Object o) @@ -645,7 +645,7 @@ public class Collections * of this method is Serializable. * * @param o the single element. - * @returns an immutable List containing only o. + * @return an immutable List containing only o. */ // It's not serializable because the spec is broken. public static List singletonList(final Object o) @@ -677,7 +677,7 @@ public class Collections * * @param key the single key. * @param value the single value. - * @returns an immutable Map containing only the single key value pair. + * @return an immutable Map containing only the single key value pair. */ // It's not serializable because the spec is broken. public static Map singletonMap(final Object key, final Object value) @@ -686,7 +686,7 @@ public class Collections { public Set entrySet() { - return singleton(new HashMap.Entry(key, value)); + return singleton(new BasicMapEntry(key, value)); } }; } @@ -1294,7 +1294,11 @@ public class Collections } } - private static class SynchronizedCollection implements Collection, + /** + * Package visible, so that collections such as the one for + * Hashtable.values() can specify which object to synchronize on. + */ + static class SynchronizedCollection implements Collection, Serializable { Object sync; @@ -1522,7 +1526,11 @@ public class Collections } } - private static class SynchronizedSet extends SynchronizedCollection + /** + * Package visible, so that sets such as the one for Hashtable.keySet() + * can specify which object to synchronize on. + */ + static class SynchronizedSet extends SynchronizedCollection implements Set { public SynchronizedSet(Object sync, Set s) -- 2.30.2