The java.io.Writer Class

The Writer class is abstract, just like OutputStream is abstract. You won't have any pure instances of Writer that are not also instances of some concrete subclass of Writer. However, many of the subclasses of Writer differ primarily in the targets of the text they write, just as many concrete subclasses of OutputStream differ only in the targets of the data they write. Most of the time you don't care about the difference between FileOutputStream and ByteArrayOutputStream. Similarly, most of the time you won't care about the difference between FileWriter and StringWriter. You'll just use the methods of the common superclass, java.io.Writer.

You use a writer almost exactly like you use an output stream. Rather than writing bytes, you write chars. The write( ) method writes a subarray from the char array text starting at offset and continuing for length characters:

public abstract void write(char[] text, int offset, int length)
 throws IOException

For example, given some Writer object w, you can write the string Testing 1-2-3 like this:

char[] test = {'T', 'e', 's', 't', 'i', 'n', 'g', ' ',
 '1', '-', '2', '-', '3'};
w.write(test, 0, test.length);

This method is abstract. Concrete subclasses that convert chars into bytes according to a specified encoding and write those bytes onto an underlying stream must override this method. An IOException may be thrown if the underlying stream's write( ) method throws an IOException. You can also write a single character, an entire array of characters, a string, or a substring:

public void write(int c) throws IOException
public void write(char[] text) throws IOException
public void write(String s) throws IOException
public void write(String s, int offset, int length) throws IOException

The default implementations of these four methods convert their first argument into an array of chars and pass that to write(char[] text, int offset, int length). Specific subclasses may provide more efficient implementations of these methods.

This is one of the few instances where the general structure of the Writer and the OutputStream classes diverge, though not in a very significant way. In OutputStream, the fundamental, abstract method that must be overridden by subclasses is the write( ) method that writes a single byte. OutputStream's multibyte write( ) methods are implemented in terms of the single-byte write( ) method whereas Writer's single-character write( ) method is implemented in terms of a multicharacter write( ) method.

Beginning in Java 5, the Writer class implements the Appendable interface. This gives it three more methods:

public W0riter append(char c) throws IOException // Java 5
public Writer append(CharSequence sequence)throws IOException // Java 5
public Writer append(CharSequence sequence,int start,int end)// Java 5
 throws IOException

The append(char) method behaves the same as write(char) with the single difference that it returns this Writer object to allow method invocation chaining. The other two methods behave the same as the equivalent write(String) and write(String, int, int) methods. However, they accept any class that implements CharSequence, not just String.

Like output streams, writers may be buffered. To force the write to take place, call flush( ):

public abstract void flush( ) throws IOException

The close( ) method closes the writer and releases any resources associated with it:

public abstract void close( ) throws IOException

This flushes the writer and closes the underlying output stream.

In Java 5, Writer implements Flushable and Closeable. However, it still has these two methods in 1.4 and earlier.