001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program 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 version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.io;
028:
029: /**
030: * This abstract class is the superclass of all classes representing
031: * an input stream of bytes.
032: *
033: * <p> Applications that need to define a subclass of <code>InputStream</code>
034: * must always provide a method that returns the next byte of input.
035: *
036: * @version 12/17/01 (CLDC 1.1)
037: * @see java.io.ByteArrayInputStream
038: * @see java.io.DataInputStream
039: * @see java.io.InputStream#read()
040: * @see java.io.OutputStream
041: * @since JDK1.0, CLDC 1.0
042: */
043: public abstract class InputStream {
044:
045: /**
046: * Reads the next byte of data from the input stream. The value byte is
047: * returned as an <code>int</code> in the range <code>0</code> to
048: * <code>255</code>. If no byte is available because the end of the stream
049: * has been reached, the value <code>-1</code> is returned. This method
050: * blocks until input data is available, the end of the stream is detected,
051: * or an exception is thrown.
052: *
053: * <p> A subclass must provide an implementation of this method.
054: *
055: * @return the next byte of data, or <code>-1</code> if the end of the
056: * stream is reached.
057: * @exception IOException if an I/O error occurs.
058: */
059: public abstract int read() throws IOException;
060:
061: /**
062: * Reads some number of bytes from the input stream and stores them into
063: * the buffer array <code>b</code>. The number of bytes actually read is
064: * returned as an integer. This method blocks until input data is
065: * available, end of file is detected, or an exception is thrown.
066: *
067: * <p> If <code>b</code> is <code>null</code>, a
068: * <code>NullPointerException</code> is thrown. If the length of
069: * <code>b</code> is zero, then no bytes are read and <code>0</code> is
070: * returned; otherwise, there is an attempt to read at least one byte. If
071: * no byte is available because the stream is at end of file, the value
072: * <code>-1</code> is returned; otherwise, at least one byte is read and
073: * stored into <code>b</code>.
074: *
075: * <p> The first byte read is stored into element <code>b[0]</code>, the
076: * next one into <code>b[1]</code>, and so on. The number of bytes read is,
077: * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
078: * number of bytes actually read; these bytes will be stored in elements
079: * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
080: * leaving elements <code>b[</code><i>k</i><code>]</code> through
081: * <code>b[b.length-1]</code> unaffected.
082: *
083: * <p> If the first byte cannot be read for any reason other than end of
084: * file, then an <code>IOException</code> is thrown. In particular, an
085: * <code>IOException</code> is thrown if the input stream has been closed.
086: *
087: * <p> The <code>read(b)</code> method for class <code>InputStream</code>
088: * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
089: *
090: * @param b the buffer into which the data is read.
091: * @return the total number of bytes read into the buffer, or
092: * <code>-1</code> is there is no more data because the end of
093: * the stream has been reached.
094: * @exception IOException if an I/O error occurs.
095: * @see java.io.InputStream#read(byte[], int, int)
096: */
097: public int read(byte b[]) throws IOException {
098: return read(b, 0, b.length);
099: }
100:
101: /**
102: * Reads up to <code>len</code> bytes of data from the input stream into
103: * an array of bytes. An attempt is made to read as many as
104: * <code>len</code> bytes, but a smaller number may be read, possibly
105: * zero. The number of bytes actually read is returned as an integer.
106: *
107: * <p> This method blocks until input data is available, end of file is
108: * detected, or an exception is thrown.
109: *
110: * <p> If <code>b</code> is <code>null</code>, a
111: * <code>NullPointerException</code> is thrown.
112: *
113: * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
114: * <code>off+len</code> is greater than the length of the array
115: * <code>b</code>, then an <code>IndexOutOfBoundsException</code> is
116: * thrown.
117: *
118: * <p> If <code>len</code> is zero, then no bytes are read and
119: * <code>0</code> is returned; otherwise, there is an attempt to read at
120: * least one byte. If no byte is available because the stream is at end of
121: * file, the value <code>-1</code> is returned; otherwise, at least one
122: * byte is read and stored into <code>b</code>.
123: *
124: * <p> The first byte read is stored into element <code>b[off]</code>, the
125: * next one into <code>b[off+1]</code>, and so on. The number of bytes read
126: * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
127: * bytes actually read; these bytes will be stored in elements
128: * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
129: * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
130: * <code>b[off+len-1]</code> unaffected.
131: *
132: * <p> In every case, elements <code>b[0]</code> through
133: * <code>b[off]</code> and elements <code>b[off+len]</code> through
134: * <code>b[b.length-1]</code> are unaffected.
135: *
136: * <p> If the first byte cannot be read for any reason other than end of
137: * file, then an <code>IOException</code> is thrown. In particular, an
138: * <code>IOException</code> is thrown if the input stream has been closed.
139: *
140: * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
141: * for class <code>InputStream</code> simply calls the method
142: * <code>read()</code> repeatedly. If the first such call results in an
143: * <code>IOException</code>, that exception is returned from the call to
144: * the <code>read(b,</code> <code>off,</code> <code>len)</code> method. If
145: * any subsequent call to <code>read()</code> results in a
146: * <code>IOException</code>, the exception is caught and treated as if it
147: * were end of file; the bytes read up to that point are stored into
148: * <code>b</code> and the number of bytes read before the exception
149: * occurred is returned. Subclasses are encouraged to provide a more
150: * efficient implementation of this method.
151: *
152: * @param b the buffer into which the data is read.
153: * @param off the start offset in array <code>b</code>
154: * at which the data is written.
155: * @param len the maximum number of bytes to read.
156: * @return the total number of bytes read into the buffer, or
157: * <code>-1</code> if there is no more data because the end of
158: * the stream has been reached.
159: * @exception IOException if an I/O error occurs.
160: * @see java.io.InputStream#read()
161: */
162: public int read(byte b[], int off, int len) throws IOException {
163: if (b == null) {
164: throw new NullPointerException();
165: } else if ((off < 0) || (off > b.length) || (len < 0)
166: || ((off + len) > b.length) || ((off + len) < 0)) {
167: throw new IndexOutOfBoundsException();
168: } else if (len == 0) {
169: return 0;
170: }
171:
172: int c = read();
173: if (c == -1) {
174: return -1;
175: }
176: b[off] = (byte) c;
177:
178: int i = 1;
179: try {
180: for (; i < len; i++) {
181: c = read();
182: if (c == -1) {
183: break;
184: }
185: if (b != null) {
186: b[off + i] = (byte) c;
187: }
188: }
189: } catch (IOException ee) {
190: }
191: return i;
192: }
193:
194: /**
195: * Skips over and discards <code>n</code> bytes of data from this input
196: * stream. The <code>skip</code> method may, for a variety of reasons, end
197: * up skipping over some smaller number of bytes, possibly <code>0</code>.
198: * This may result from any of a number of conditions; reaching end of file
199: * before <code>n</code> bytes have been skipped is only one possibility.
200: * The actual number of bytes skipped is returned. If <code>n</code> is
201: * negative, no bytes are skipped.
202: *
203: * <p> The <code>skip</code> method of <code>InputStream</code> creates a
204: * byte array and then repeatedly reads into it until <code>n</code> bytes
205: * have been read or the end of the stream has been reached. Subclasses are
206: * encouraged to provide a more efficient implementation of this method.
207: *
208: * @param n the number of bytes to be skipped.
209: * @return the actual number of bytes skipped.
210: * @exception IOException if an I/O error occurs.
211: */
212: public long skip(long n) throws IOException {
213: long m = n;
214: while (m > 0) {
215: if (read() < 0) {
216: break;
217: }
218: --m;
219: }
220: return n - m;
221: }
222:
223: /**
224: * Returns the number of bytes that can be read (or skipped over) from
225: * this input stream without blocking by the next caller of a method for
226: * this input stream. The next caller might be the same thread or
227: * another thread.
228: *
229: * <p> The <code>available</code> method for class <code>InputStream</code>
230: * always returns <code>0</code>.
231: *
232: * <p> This method should be overridden by subclasses.
233: *
234: * @return the number of bytes that can be read from this input stream
235: * without blocking.
236: * @exception IOException if an I/O error occurs.
237: */
238: public int available() throws IOException {
239: return 0;
240: }
241:
242: /**
243: * Closes this input stream and releases any system resources associated
244: * with the stream.
245: *
246: * <p> The <code>close</code> method of <code>InputStream</code> does
247: * nothing.
248: *
249: * @exception IOException if an I/O error occurs.
250: */
251: public void close() throws IOException {
252: }
253:
254: /**
255: * Marks the current position in this input stream. A subsequent call to
256: * the <code>reset</code> method repositions this stream at the last marked
257: * position so that subsequent reads re-read the same bytes.
258: *
259: * <p> The <code>readlimit</code> arguments tells this input stream to
260: * allow that many bytes to be read before the mark position gets
261: * invalidated.
262: *
263: * <p> The general contract of <code>mark</code> is that, if the method
264: * <code>markSupported</code> returns <code>true</code>, the stream somehow
265: * remembers all the bytes read after the call to <code>mark</code> and
266: * stands ready to supply those same bytes again if and whenever the method
267: * <code>reset</code> is called. However, the stream is not required to
268: * remember any data at all if more than <code>readlimit</code> bytes are
269: * read from the stream before <code>reset</code> is called.
270: *
271: * <p> The <code>mark</code> method of <code>InputStream</code> does
272: * nothing.
273: *
274: * @param readlimit the maximum limit of bytes that can be read before
275: * the mark position becomes invalid.
276: * @see java.io.InputStream#reset()
277: */
278: public synchronized void mark(int readlimit) {
279: }
280:
281: /**
282: * Repositions this stream to the position at the time the
283: * <code>mark</code> method was last called on this input stream.
284: *
285: * <p> The general contract of <code>reset</code> is:
286: *
287: * <p><ul>
288: *
289: * <li> If the method <code>markSupported</code> returns
290: * <code>true</code>, then:
291: *
292: * <ul><li> If the method <code>mark</code> has not been called since
293: * the stream was created, or the number of bytes read from the stream
294: * since <code>mark</code> was last called is larger than the argument
295: * to <code>mark</code> at that last call, then an
296: * <code>IOException</code> might be thrown.
297: *
298: * <li> If such an <code>IOException</code> is not thrown, then the
299: * stream is reset to a state such that all the bytes read since the
300: * most recent call to <code>mark</code> (or since the start of the
301: * file, if <code>mark</code> has not been called) will be resupplied
302: * to subsequent callers of the <code>read</code> method, followed by
303: * any bytes that otherwise would have been the next input data as of
304: * the time of the call to <code>reset</code>. </ul>
305: *
306: * <li> If the method <code>markSupported</code> returns
307: * <code>false</code>, then:
308: *
309: * <ul><li> The call to <code>reset</code> may throw an
310: * <code>IOException</code>.
311: *
312: * <li> If an <code>IOException</code> is not thrown, then the stream
313: * is reset to a fixed state that depends on the particular type of the
314: * input stream and how it was created. The bytes that will be supplied
315: * to subsequent callers of the <code>read</code> method depend on the
316: * particular type of the input stream. </ul></ul>
317: *
318: * <p> The method <code>reset</code> for class <code>InputStream</code>
319: * does nothing and always throws an <code>IOException</code>.
320: *
321: * @exception IOException if this stream has not been marked or if the
322: * mark has been invalidated.
323: * @see java.io.InputStream#mark(int)
324: * @see java.io.IOException
325: */
326: public synchronized void reset() throws IOException {
327: throw new IOException(
328: /* #ifdef VERBOSE_EXCEPTIONS */
329: /// skipped "mark/reset not supported"
330: /* #endif */
331: );
332: }
333:
334: /**
335: * Tests if this input stream supports the <code>mark</code> and
336: * <code>reset</code> methods. The <code>markSupported</code> method of
337: * <code>InputStream</code> returns <code>false</code>.
338: *
339: * @return <code>true</code> if this true type supports the mark and reset
340: * method; <code>false</code> otherwise.
341: * @see java.io.InputStream#mark(int)
342: * @see java.io.InputStream#reset()
343: */
344: public boolean markSupported() {
345: return false;
346: }
347:
348: }
|