Terminal I/O

 

Terminal I/O

The prototypical example of an InputStream object is the “standard input” of a Java application. Like stdin in C or cin in C++, this object reads data from the program’s environment, which is usually a terminal window or a command pipe. The java.lang.System class, a general repository for system-related resources, provides a reference to standard input in the static variable in. System also provides objects for standard output and standard error in the out and errvariables, respectively. The following example shows the correspondence:

InputStream stdin = System.in;  
OutputStream stdout = System.out;  
OutputStream stderr = System.err;

This example hides the fact that System.out and System.err aren’t really OutputStream objects, but more specialized and useful PrintStream objects. We’ll explain these later, but for now we can reference out and err as OutputStream objects, since they are a kind of OutputStream as well.

We can read a single byte at a time from standard input with the InputStream’s read( ) method. If you look closely at the API, you’ll see that the read( )method of the base InputStream class is an abstract method. What lies behind System.in is a particular implementation of InputStream—the subclass provides a real implementation of the read( ) method.

try {  
    int val = System.in.read( );  
    ...  
}  
catch ( IOException e ) {  
    ...  
}

As is the convention in C, read( ) provides a byte of information, but its return type is int. A return value of -1 indicates a normal end of stream has been reached; you’ll need to test for this condition when using the simple read( )method. If an error occurs during the read, an IOException is thrown. All basic input and output stream commands can throw an IOException, so you should arrange to catch and handle them appropriately.

To retrieve the value as a byte, perform a cast:

byte b = (byte) val;

Be sure to check for the end-of-stream condition before you perform the cast.

An overloaded form of read( ) fills a byte array with as much data as possible up to the capacity of the array, and returns the number of bytes read:

byte [] bity = new byte [1024];  
int got = System.in.read( bity );

We can also check the number of bytes available for reading on an InputStreamwith the available( ) method. Using that information, we could create an array of exactly the right size:

int waiting = System.in.available( );  
if ( waiting > 0 ) {  
    byte [] data = new byte [ waiting ];  
    System.in.read( data );  
    ...  
}

However, the reliability of this technique depends on the ability of the underlying stream implementation to detect how much data is arriving.

InputStream provides the skip( ) method as a way of jumping over a number of bytes. Depending on the implementation of the stream, skipping bytes may be more efficient than reading them. The close( ) method shuts down the stream and frees up any associated system resources. It’s a good idea to close a stream when you are done using it.