home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Java Fundamental Classes Reference

Previous Chapter 11
The java.io Package
Next
 

InputStream

Name

InputStream

Synopsis

Class Name:

java.io.InputStream

Superclass:

java.lang.Object

Immediate Subclasses:

java.io.ByteArrayInputStream,

java.io.FileInputStream,

java.io.FilterInputStream,

java.io.ObjectInputStream,

java.io.PipedInputStream,

java.io.SequenceInputStream,

java.io.StringBufferInputStream

Interfaces Implemented:

None

Availability:

JDK 1.0 or later

Description

The InputStream class is an abstract class that is the superclass of all classes that represent input byte streams. InputStream defines the basic input methods that all input streams provide. A similar hierarchy of classes, based around Reader, deals with character streams instead of byte streams.

InputStream is designed so that read(byte[]) and read(byte[], int, int) both call read(). Thus, a subclass can simply override read(), and all the read methods will work. However, for efficiency sake, read(byte[], int, int) should also be overridden with a method that can read a block of data more efficiently than reading each byte separately.

InputStream also defines a mechanism for marking a position in the stream and returning to it later, via the mark() and reset() methods. Another method, markSupported(), indicates whether or not this mark-and-reset functionality is available in a particular subclass.

Class Summary

public abstract class java.io.InputStream extends java.lang.Object {
  // Instance Methods
  public abstract int available();
  public void close();
  public synchronized void mark(int readlimit);
  public boolean markSupported();
  public abstract int read();
  public int read(byte[] b);
  public int read(byte[] b, int off, int len);
  public synchronized void reset();
  public long skip(long n);
}

Instance Methods

available

public abstract int available() throws IOException

Returns

The number of bytes that can be read without blocking.

Throws

IOException

If any kind of I/O error occurs.

Description

This method returns the number of bytes that can be read without having to wait for more data to become available, or in other words, blocking.

A subclass of InputStream must implement this method.

close

public void close() throws IOException

Throws

IOException

If any kind of I/O error occurs.

Description

This method closes the input stream and releases any resources associated with it.

The implementation of the close() method in InputStream does nothing; a subclass should override this method to handle cleanup for the stream.

mark

public synchronized void mark(int readlimit)

Parameters

readlimit

The maximum number of bytes that can be read before the saved position can become invalid.

Description

This method tells this InputStream object to remember its current position, so that the position can be restored by a call to the reset() method. The InputStream can read readlimit bytes beyond the marked position before the mark becomes invalid.

The implementation of the mark() method in InputStream does nothing; a subclass must override the method to provide the mark-and-reset functionality.

markSupported

public boolean markSupported()

Returns

true if this input stream supports mark() and reset(); false otherwise.

Description

This method returns a boolean value that indicates whether or not this object supports mark-and-reset functionality.

The markSupported() method in InputStream always returns false. A subclass that implements the mark-and-reset functionality should override the method to return true.

read

public abstract int read() throws IOException

Returns

The next byte of data or -1 if the end of the stream is encountered.

Throws

IOException

If any kind of I/O error occurs.

Description

This method reads the next byte of input. The byte is returned as an integer in the range 0 to 255. The method blocks until the byte is read, the end of stream is encountered, or an exception is thrown.

A subclass of InputStream must implement this method.

public int read(byte[] b) throws IOException

Parameters

b

An array of bytes to be filled from the stream.

Returns

The actual number of bytes read or -1 if the end of the stream is encountered immediately.

Throws

IOException

If any kind of I/O error occurs.

Description

This method reads bytes of input to fill the given array by calling read(b, 0, b.length). The method blocks until some data is available.

A subclass does not usually need to override this method as it can override read(byte[], int, int) and have read(byte[]) work automatically.

public int read(byte[] b, int off, int len) throws IOException

Parameters

b

An array of bytes to be filled from the stream.

off

An offset into the array.

len

The number of bytes to read.

Returns

The actual number of bytes read or -1 if the end of the stream is encountered immediately.

Throws

IOException

If any kind of I/O error occurs.

Description

This method reads up to len bytes of input into the given array starting at index off. The method blocks until some data is available.

The implementation of this method in InputStream uses read() repeatedly to fill the array. Although it is not strictly necessary, a subclass should override this method to read a block of data more efficiently.

reset

public synchronized void reset() throws IOException

Throws

IOException

If there was no previous call to the mark() method or the saved position has been invalidated.

Description

This method restores the position of the stream to the position that was saved by a previous call to mark().

The implementation of the reset() method in InputStream throws an exception to indicate that mark-and-reset functionality is not supported by default. A subclass must override the method to provide the functionality.

skip

public long skip(long n) throws IOException

Parameters

n

The number of bytes to skip.

Returns

The actual number of bytes skipped.

Throws

IOException

If any kind of I/O error occurs.

Description

This method skips n bytes of input. In other words, it moves the position of the stream forward by n bytes.

The implementation of the skip() method in InputStream simply calls read(b) where b is a byte array n bytes long. A subclass may want to override this method to implement a more efficient skipping algorithm.

Inherited Methods

Method

Inherited From

Method

Inherited From

clone()

Object

equals(Object)

Object

finalize()

Object

getClass()

Object

hashCode()

Object

notify()

Object

notifyAll()

Object

toString()

Object

wait()

Object

wait(long)

Object

wait(long, int)

Object

   

See Also

ByteArrayInputStream, FileInputStream, FilterInputStream, IOException, ObjectInputStream, PipedInputStream, SequenceInputStream, StringBufferInputStream


Previous Home Next
FilterWriter Book Index InputStreamReader

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java