Print Writers

The java.io.PrintWriter class is a subclass of java.io.Writer that contains the familiar print( ) and println( ) methods from System.out and other instances of PrintStream. In Java 5 and later, it also has all the format( ) and printf( ) methods introduced in Chapter 7. It's deliberately similar to the java.io.PrintStream class.

The main difference between PrintStream and PrintWriter is that PrintWriter handles multiple-byte and other non-Latin-1 character sets properly. The other, more minor difference is that automatic flushing is performed only when println( ) is invoked, not every time a newline character is seen. Sun would probably like to deprecate PrintStream and use PrintWriter instead, but that would break too much existing code. (In fact, Sun did deprecate the PrintStream( ) constructors in Java 1.1, but they undeprecated them in 1.2.)

There are four constructors in this class:

public PrintWriter(Writer out)
public PrintWriter(Writer out, boolean autoFlush)
public PrintWriter(OutputStream out)
public PrintWriter(OutputStream out, boolean autoFlush)

The PrintWriter can send text either to an output stream or to another writer. If autoFlush is set to true, the PrintWriter is flushed every time println( ) is invoked.

The PrintWriter class implements the abstract write( ) method from java.io.Writer and overrides five other methods:

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

These methods are used almost identically to their equivalents in any other Writer class. The one difference is that none of them throw IOExceptions; in fact, no method in the PrintWriter class ever throws an IOException. If the underlying output stream or writer throws an IOException, it's caught inside PrintWriter and an error flag is set. Read the status of this flag with the checkError( ) method:

public boolean checkError( )

Since checkError( ) returns a boolean, it only tells you that an I/O error has occurred; it does not tell you what that error was. Furthermore, once an error has occurred, checkError( ) always returns truethere is no way to reset it so you can test for later errors.

The main advantages of the PrintWriter class are the 9-way overloaded print( ) method and the 10-way overloaded println( ) method. Any Java object, variable, or literal can be printed by passing it to a print( ) or println( ) method. The println( ) method follows its argument with a platform-dependent line separator (such as ) and then flushes the output if autoFlush is enabled. The print( ) method does not. Otherwise, these methods are the same.

public void print(boolean b)
public void print(char c)
public void print(int i)
public void print(long l)
public void print(float f)
public void print(double d)
public void print(char[] text)
public void print(String s)
public void print(Object 0)
public void println( )
public void println(boolean b)
public void println(char c)
public void println(int i)
public void println(long l)
public void println(float f)
public void println(double d)
public void println(char[] text)
public void println(String s)
public void println(Object o)

You should never use println( ), either the PrintWriter or the PrintStream version, in networking code. Most network protocols like HTTP expect to see a carriage return/linefeed pair as the line separator character. If you use println( ), your network programs may run on Windows, but they'll have problems on most other platforms. Furthermore, these problems can be hard to diagnose because some servers and clients are more forgiving of improper line-ending conventions than others.

Java 5 adds two format( ) and two printf( ) methods:

public PrintWriter printf(String format, Object... args)
 throws IllegalFormatException, NullPointerException
public PrintWriter printf(Locale l, String format, Object... args)
 throws IllegalFormatException, NullPointerException
public PrintWriter format(String format, Object... args)
 throws IllegalFormatException, NullPointerException
public PrintWriter format(Locale l, String format, Object... args)
 throws IllegalFormatException, NullPointerException

These methods have the same behavior as the similarly named methods in the PrintStream class discussed in Chapter 7.