Writing data Resource management

} The idea behind IOException is this: streams are mostly used to exchanging data with devices that are outside the JVM. If something goes wrong with the device, the device needs a universal way to indicate an error to the client code. Consider, for example, a printer that refuses to print a document because it is out of paper. The printer needs to signal an exception, and the exception should be relayed to the user; the program making the print request has no way of refilling the paper tray without human intervention. Moreover, this exception should be relayed to the user immediately. Most stream exceptions are similar to this example. That is, they often require some sort of user action or at least user notification, and are often best handled immediately. Therefore, the designers of the streams library decided to make IOException a checked exception, thereby forcing programs to explicitly handle the possibility of failure. Some foreshadowing: RMI follows a similar design philosophy. Remote methods must be declared to throw RemoteException and client code must catch RemoteException . RemoteException means something has gone wrong, somewhere outside the JVM.

1.1.3 OutputStream

OutputStream is an abstract class that represents a data sink. Once it is created, client code can write information to it. OutputStream consists of the following methods: public void close throws IOException public void flush throws IOException public void writebyte[] buffer throws IOExcep tion public void writebyte[] buffer, int startingOffset, int numberOfBytes throws IOException public void writeint value throws IOException The OutputStream class is a little simpler than InputStream ; it doesnt support navigation. After all, you probably dont want to go back and write information a second time. OutputStream methods serve two purposes: writing data and resource management.

1.1.3.1 Writing data

OutputStream defines three basic methods for writing data: public void writebyte[] buffer throws IOException public void writebyte[] buffer, int startingOffset, int numberOfBytes throws IOException public void writeint value throws IOException These methods are analogous to the read methods defined for InputStream . Just as there was one basic method for reading a single byte of data, there is one basic method, writeint value , for writing a single byte of data. The argument to this write method should be an integer between 0 and 255. If not, it is reduced to module 256 before being written. Just as there were two array-based variants of read , there are two methods for writing arrays of bytes. writebyte[] buffer causes all the bytes in the array to be written out to the stream. writebyte[] buffer, int startingOffset, int numberOfBytes causes numberOfBytes bytes to be written, starting with the value at buffer[startingOffset] . The fact that the argument to the basic write method is an integer is somewhat peculiar. Recall that read returned an integer, rather than a byte, in order to allow instances of InputStream to signal exceptional conditions. write takes an integer, rather than a byte, so that the read and write method declarations are parallel. In other words, if youve read a value in from a stream, and its not -1, you should be able to write it out to another stream without casting it.

1.1.3.2 Resource management

OutputStream defines two resource management methods: public void close public void flush close serves exactly the same role for OutputStream as it did for InputStream ™itshould be called when the client code is done using the stream and wishes to free up all the associated operating-system resources. The flush method is necessary because output streams frequently use a buffer to store data that is being written. This is especially true when data is being written to either a file or a socket. Passing data to the operating system a single byte at a time can be expensive. A much more practical strategy is to buffer the data at the JVM level and occasionally call flush to send the data en masse.

1.2 Viewing a File

To make this discussion more concrete, we will now discuss a simple application that allows the user to display the contents of a file in a JTextArea . The application is called ViewFile and is shown in Exam ple 1- 1 . Note that the applications main method is defined in the c om.ora.rmibook.chapter1.ViewFile class. [ 3] The resulting screenshot is shown in Figur e 1- 1 . [ 3] This example uses classes from the Java Swing libraries. If you would like more information on Swing, see Java Swing OReilly or Java Foundation Classes in a Nutshell OReilly. Figure 1-1. The ViewFile application