001 /* SequenceInputStream.java -- Reads multiple input streams in sequence
002 Copyright (C) 1998, 1999, 2001, 2004, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.io;
040
041 import java.util.Enumeration;
042
043 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
044 * "The Java Language Specification", ISBN 0-201-63451-1
045 * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
046 * Status: Believed complete and correct.
047 */
048
049 /**
050 * This class merges a sequence of multiple <code>InputStream</code>'s in
051 * order to form a single logical stream that can be read by applications
052 * that expect only one stream.
053 * <p>
054 * The streams passed to the constructor method are read in order until
055 * they return -1 to indicate they are at end of stream. When a stream
056 * reports end of stream, it is closed, then the next stream is read.
057 * When the last stream is closed, the next attempt to read from this
058 * stream will return a -1 to indicate it is at end of stream.
059 * <p>
060 * If this stream is closed prior to all subordinate streams being read
061 * to completion, all subordinate streams are closed.
062 *
063 * @author Aaron M. Renn (arenn@urbanophile.com)
064 * @author Warren Levy (warrenl@cygnus.com)
065 */
066 public class SequenceInputStream extends InputStream
067 {
068 /** The handle for the current input stream. */
069 private InputStream in;
070
071 /** Secondary input stream; not used if constructed w/ enumeration. */
072 private InputStream in2;
073
074 /**
075 * The enumeration handle; not used if constructed w/ 2 explicit
076 * input streams.
077 */
078 private Enumeration<? extends InputStream> e;
079
080 /**
081 * This method creates a new <code>SequenceInputStream</code> that obtains
082 * its list of subordinate <code>InputStream</code>s from the specified
083 * <code>Enumeration</code>
084 *
085 * @param e An <code>Enumeration</code> that will return a list of
086 * <code>InputStream</code>s to read in sequence
087 */
088 public SequenceInputStream(Enumeration<? extends InputStream> e)
089 {
090 this.e = e;
091 in = e.nextElement();
092 in2 = null;
093 }
094
095 /**
096 * This method creates a new <code>SequenceInputStream</code> that will read
097 * the two specified subordinate <code>InputStream</code>s in sequence.
098 *
099 * @param s1 The first <code>InputStream</code> to read
100 * @param s2 The second <code>InputStream</code> to read
101 */
102 public SequenceInputStream(InputStream s1, InputStream s2)
103 {
104 in = s1;
105 in2 = s2;
106 }
107
108 /**
109 * This method returns the number of bytes than can be read from the
110 * currently being read subordinate stream before that stream could
111 * block. Note that it is possible more bytes than this can actually
112 * be read without the stream blocking. If a 0 is returned, then the
113 * stream could block on the very next read.
114 *
115 * @return The number of bytes that can be read before blocking could occur
116 *
117 * @exception IOException If an error occurs
118 */
119 public int available() throws IOException
120 {
121 if (in == null)
122 return 0;
123
124 return in.available();
125 }
126
127 /**
128 * Closes this stream. This will cause any remaining unclosed subordinate
129 * <code>InputStream</code>'s to be closed as well. Subsequent attempts to
130 * read from this stream may cause an exception.
131 *
132 * @exception IOException If an error occurs
133 */
134 public void close() throws IOException
135 {
136 while (in != null)
137 {
138 in.close();
139 in = getNextStream ();
140 }
141 }
142
143 /**
144 * This method reads an unsigned byte from the input stream and returns it
145 * as an int in the range of 0-255. This method also will return -1 if
146 * the end of the stream has been reached. This will only happen when
147 * all of the subordinate streams have been read.
148 * <p>
149 * This method will block until the byte can be read.
150 *
151 * @return The byte read, or -1 if end of stream
152 *
153 * @exception IOException If an error occurs
154 */
155 public int read() throws IOException
156 {
157 int ch = -1;
158
159 while (in != null && (ch = in.read()) < 0)
160 {
161 in.close();
162 in = getNextStream();
163 }
164
165 return ch;
166 }
167
168 /**
169 * This method reads bytes from a stream and stores them into a caller
170 * supplied buffer. It starts storing the data at index <code>offset</code>
171 * into the buffer and attempts to read <code>len</code> bytes. This method
172 * can return before reading the number of bytes requested. The actual number
173 * of bytes read is returned as an int. A -1 is returend to indicate the
174 * end of the stream. This will only happen when all of the subordinate
175 * streams have been read.
176 * <p>
177 * This method will block until at least one byte can be read.
178 *
179 * @param b The array into which bytes read should be stored
180 * @param off The offset into the array to start storing bytes
181 * @param len The requested number of bytes to read
182 *
183 * @return The actual number of bytes read, or -1 if end of stream
184 *
185 * @exception IOException If an error occurs
186 */
187 public int read(byte[] b, int off, int len) throws IOException
188 {
189 int ch = -1;
190
191 // The validity of the parameters will be checked by in.read so
192 // don't bother doing it here.
193 while (in != null && (ch = in.read(b, off, len)) < 0)
194 {
195 in.close();
196 in = getNextStream();
197 }
198
199 return ch;
200 }
201
202 /**
203 * This private method is used to get the next <code>InputStream</code> to
204 * read from. Returns null when no more streams are available.
205 */
206 private InputStream getNextStream()
207 {
208 InputStream nextIn = null;
209
210 if (e != null)
211 {
212 if (e.hasMoreElements())
213 nextIn = e.nextElement();
214 }
215 else if (in2 != null)
216 {
217 nextIn = in2;
218 in2 = null;
219 }
220
221 return nextIn;
222 }
223 }