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 }