Byte Output Streams

The byte output stream class hierarchy is shown in Figure 25.2. The OutputStream class is the abstract superclass of all byte output stream classes. It defines methods to close an output stream, to write the contents on a buffer to the stream, and to write 1 byte or an array of bytes to the stream. The OutputStream class has a number of subclasses that override the OutputStream methods and/or provide additional functionality.

Figure 25.2. Byte output stream class hierarchy

The FileOutputStream class connects an output stream to a file allowing you to write data to that file. The ObjectOutputStream class lets you write the data from an object to an output stream. If the ObjectOutputStream is wrapped around a FileOutputStream , you can write the data for an object to a file. A saved object can be restored using an ObjectInputStream . The ByteArrayOutputStream class writes data to a byte array.

The FilterOutputStream class is the superclass of three classes that are wrapped around other OutputStream objects to provide additional functionality. The BufferedOutputStream class provides an intermediate buffer that improves I/O performance. The DataOutputStream class defines methods that can write a primitive value directly to the stream without first having to convert it to bytes. The PrintStream class provides the print() and println() methods that print a String or a String representation of a primitive type value or Object to the output stream.

OutputStream Class

The OutputStream class is the abstract superclass of all byte output stream classes and defines methods available to all byte output streams. OutputStream subclasses will often override these methods to suit their own needs.

[View full width]

 
 [View full width] 
 public void close() throws IOException public void flush() throws IOException public abstract void write(int b) throws IOException public void write(byte[] b) throws IOException public void write(byte[] b, int offset, int length)  throwsIOException 

The close() method is overridden by OutputStream subclasses to close the output stream and release any resources allocated to it. The flush() method is overridden by OutputStream subclasses to force any bytes stored in an output buffer to be written to the stream. The write() method is used to write one or more bytes to the output stream. The first version, when overridden by an OutputStream subclass, writes a single byte (the input argument is really an int ) to the output stream. The second version writes the contents of an array of bytes to the stream. The third version writes length bytes to the stream from the specified byte array starting at position offset .

BufferedOutputStream Class

A BufferedOutputStream is wrapped around another OutputStream to provide buffered output. Rather than writing bytes to the output stream one at a time, the bytes are first written to an internal buffer. When the buffer reaches its capacity the contents are written to the output stream. This operation improves performance by reducing the number of low-level system calls required. The BufferedOutputStream class defines two public constructors.

 public BufferedOutputStream(OutputStream stream) public BufferedOutputStream(OutputStream stream, int bufferSize) 

The second constructor allows you to specify the size of the internal buffer. The BufferedOutputStream class overrides some of the methods from the OutputStream class but does not define any new methods.

ByteArrayOutputStream Class

A ByteArrayOutputStream object is an output stream that writes data into a byte array. The class defines two public constructors.

 public ByteArrayOutputStream() public ByteArrayOutputStream(int bufferSize) 

The second constructor allows you to specify the size of the output stream byte array. In addition to overriding some of the methods from the OutputStream class, the ByteArrayOutputStream defines the following methods.

 public int size() public byte[] toByteArray() public String toString() public void writeTo(OutputStream stream) throws IOException 

The size() method returns the current size of the byte array. The toByteArray() method returns the contents of the output stream byte array. The toString() method returns the contents of the output stream byte array as a String by converting the bytes to character data. The writeTo() method writes the contents of the output stream byte array to another output stream. This method could be used, for instance, to write the contents of the byte array to a file.

DataOutputStream Class

The DataOutputStream class allows you to write primitive type values to a byte output stream. A DataOutputStream object is always wrapped around another OutputStream object. If you want to write primitive types to a file, you could wrap a DataOutputStream around a FileOutputStream . The DataOutputStream class defines one public constructor.

 public DataOutputStream(OutputStream stream) 

In addition to overriding some of the OutputStream class methods, the DataOutputStream class defines the following methods to write primitive values or String objects to the output stream.

 public final void writeBoolean(boolean b) throws IOException public final void writeByte(int b) throws IOException public final void writeBytes(String str) throws IOException public final void writeChar(int c) throws IOException public final void writeChars(String str) throws IOException public final void writeDouble(double d) throws IOException public final void writeFloat(float f) throws IOException public final void writeInt(int i) throws IOException public final void writeLong(long l) throws IOException public final void writeShort(short s) throws IOException public final void writeUTF(String str) throws IOException 

These methods are used to write a primitive value or String to the output stream. The writeBytes() method writes a String as a sequence of bytes. The writeChars() method writes a String as a sequence of characters . The writeUTF() method writes a String as a sequence of bytes using the UTF-8 character encoding scheme.

FileOutputStream Class

The FileOutputStream class is used to connect an output stream with a file on disk. Whatever is written to the output stream will be written to the file. The FileOutputStream class defines five public constructors.

[View full width]

 
 [View full width] 
 public FileOutputStream(File file) throws FileNotFoundException public FileOutputStream(File file, boolean append) throws  FileNotFoundException public FileOutputStream(FileDescriptor desc) public FileOutputStream(String name) throws FileNotFoundException public FileOutputStream(String name,boolean append) throws  FileNotFoundException 

The file can be specified by a File object, a FileDescriptor object, or by providing the name and, if necessary, path of the file. If the file does not exist, it will be created. If you specify a path , the directory structure must already exist. If append is true, data is written starting at the end of the file. The default is false, meaning that data is written from the beginning of the file.

The FileOutputStream class overrides the three write() methods from the OutputStream class but does not provide any new methods to write data to the output stream.

FilterOutputStream Class

The FilterOutputStream is the superclass for byte output streams that are wrapped around other output streams to provide additional functionality to the underlying stream. Child classes of the FilterOutputStream class include the BufferedOutputStream , DataOutputStream , and PrintStream classes. The FilterOutputStream class overrides the OutputStream methods to pass all requests to the underlying stream, but does not define any new methods.

ObjectOutputStream Class

An ObjectOutputStream object can be used to write primitive types and objects to an output stream. An ObjectOutputStream is always wrapped around another output stream. If the ObjectOutputStream is wrapped around a FileOutputStream , you can save an object or primitive type value to a file. A saved object or value can be restored using an ObjectInputStream . The class defines one public constructor.

 public ObjectOutputStream(OutputStream stream) throws IOException 

In addition to overriding some of the OutputStream class methods, the ObjectOutputStream class provides the following methods for writing a primitive value to an output stream. The description of these methods is the same as previously given in the "DataOutputStream Class" section.

 public void writeBoolean(boolean b) throws IOException public void writeByte(int b) throws IOException public void writeBytes(String str) throws IOException public void writeChar(int c) throws IOException public void writeChars(String str) throws IOException public void writeDouble(double d) throws IOException public void writeFloat(float f) throws IOException public void writeInt(int i) throws IOException public void writeLong(long l) throws IOException public void writeShort(short s) throws IOException public void writeUTF(String str) throws IOException 

The ObjectOutputStream class also defines a method for writing an object to an output stream.

 public final void writeObject(Object obj) throws IOException 

The writeObject() method writes the class of the object, the class signature, and the values of the nonstatic and nontransient data members to the underlying output stream. If the underlying stream is a FileOutputStream , the object will be saved as a file. Only objects that are instances of classes that implement the Serializable interface can be passed to this method. An attempt to write an object that does not implement Serializable will cause an exception to be thrown. An object written by this method can be restored using an ObjectInputStream .

For an example of how an ObjectOutputStream can store an object to disk, see the "Saving and Restoring Objects" section later in this chapter.

PrintStream Class

A PrintStream object can be wrapped around another output stream allowing the underlying stream access to the print() and println() methods. The standard output stream is implemented as an instance of the PrintStream class. One useful feature of the PrintStream class is that its methods never throw an IOException and don't have to be enclosed in a try block.

The PrintStream class defines three public constructors.

[View full width]

 
 [View full width] 
 public PrintStream(OutputStream stream) public PrintStream(OutputStream stream, boolean autoFlush) public PrintStream(OutputStream stream, boolean autoFlush,  String encoding) 

If the argument autoFlush is true, the output buffer is flushed whenever a byte array is written. You can also specify a character encoding scheme if you wish. Examples of character encoding schemes include Unicode and UTF8. In addition to overriding some of the OutputStream class methods, the PrintStream class defines the following methods.

 public void print(boolean b) public void print(char c) public void print(char[] chars) public void print(double d) public void print(float f) public void print(int i) public void print(long l) public void print(Object obj) public void print(String str) 

The print() method prints a String or a String representation of a primitive type value or Object to the output stream without appending a newline character to the end of the String .

 public void println() public void println(boolean b) public void println(char c) public void println(char[] chars) public void println(double d) public void println(float f) public void println(int i) public void println(long l) public void println(Object obj) public void println(String str) 

The println() method prints a String or a String representation of a primitive type value or Object to the output stream. A newline character is appended to the end of the String . The no-argument version simply writes a newline to the output stream. The println() method that has been used dozens of times in the examples of this book is usually called by the standard output stream.