Tech and Media Labs
This site uses cookies to improve the user experience.




Java IO: OutputStream

Jakob Jenkov
Last update: 2014-11-05

The OutputStream class is the base class of all output streams in the Java IO API. Subclasses include the BufferedOutputStream and the FileOutputStream among others. To see a full list of streams, go to the bottom table of the Java IO Overview page.

OutputStream's and Destinations

An OutputStream is typically always connected to some data destination, like a file, network connection, pipe etc. This is also explained in more detail in the Java IO Overview text. The OutputStream's data destination is where all data written to the OutputStream will eventually end.

write(byte)

The write(byte) method is used to write a single byte to the OutputStream. The write() method of an OutputStream takes an int which contains the byte value of the byte to write. Only the first byte of the int value is written. The rest is ignored.

Subclasses of OutputStream may have alternative write() methods. For instance, the DataOutputStream allows you to write Java primitives like int, long, float, double, boolean etc. with its corresponding methods writeBoolean(), writeDouble() etc.

Here is an OutputStream write() example:

OutputStream output = new FileOutputStream("c:\\data\\output-text.txt");

while(hasMoreData()) {
  int data = getMoreData();
  output.write(data);
}
output.close();

This OutputStream write() example first creates a FileOutputStream to which the data will be written. Then the example enters a while loop. The condition to exit the while loop is the return value of the method hasMoreData(). The implementation of hasMoreData() is not shown, but imagine that it returns true if there is more data to write, and false if not.

Inside the while loop the example calls the method getMoreData() to get the next data to write to the OutputStream, and then writes that data to the OutputStream. The while loop continues until hasMoreData() returns false.

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

write(byte[])

The OutputStream class also has a write(byte[] bytes) method and a write(byte[] bytes, int offset, int length) which both can write an array or part of an array of bytes to the OutputStream.

The write(byte[] bytes) method writes all the bytes in the byte array to the OutputStream.

The write(byte[] bytes, int offset, int length) method writes length bytes starting from index offset from the byte array to the OutputStream.

flush()

The OutputStream's flush() method flushes all data written to the OutputStream to the underlying data destination. For instance, if the OutputStream is a FileOutputStream then bytes written to the FileOutputStream may not have been fully written to disk yet. The data might be buffered in memory somewhere, even if your Java code has written it to the FileOutputStream. By calling flush() you can assure that any buffered data will be flushed (written) to disk (or network, or whatever else the destination of your OutputStream has).

close()

Once you are done writing data to the OutputStream you should close it. You close an OutputStream by calling its close() method. Since the OutputStream's various write() methods may throw an IOException, you should close the OutputStream inside a finally block. Here is a simple OutputStream close() example:

OutputStream output = null;

try{
  output = new FileOutputStream("c:\\data\\output-text.txt");

  while(hasMoreData()) {
    int data = getMoreData();
    output.write(data);
  }
} finally {
    if(output != null) {
        output.close();
    }
}

This simple example calls the OutputStream close() method inside a finally block. While this makes sure that the OutputStream is closed, it still does not provide perfect exception handling. I have covered IO exception handling in more detail in my text about Java IO exception handling.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC