Print Streams

System.out is the first output stream most Java programmers encounter. System.err is probably the second. Both are instances of the java.io.PrintStream class. PrintStream is a subclass of FilterOutputStream that converts numbers and objects to text. System.out is primarily used for simple, character-mode applications and for debugging. Its raison d'étre is convenience, not robustness; print streams ignore many issues involved in internationalization and error checking. This makes System.out easy to use in quick-and-dirty hacks and simple examples, while simultaneously making it unsuitable for production code, which should use the java.io.PrintWriter class (discussed in Chapter 20) instead.

PrintStream is not limited to the console. PrintStream is a filter stream and thus can be connected to any other output stream: a FileOutputStream, a ByteArrayOutputStream, a TelnetOutputStream, or anything else you write to. Three constructors can be used to chain a PrintStream to an underlying stream:

public PrintStream(OutputStream out)
public PrintStream(OutputStream out, boolean autoFlush)
public PrintStream(OutputStream out, boolean autoFlush, String encoding)
 throws UnsupportedEncodingException

The out argument is just the underlying output stream. The autoFlush argument is a boolean. If it's true, the stream is flushed every time a linefeed character ( ) or byte is written, a println( ) method is invoked, or a byte array is written. The encoding argument names the character encoding used to convert strings to bytes. The last option is available only in Java 1.4 and later. Print streams in Java 1.3 and earlier (and all print streams created with the first two constructors) use the local system's default encoding, whatever that may be. Often this is not the encoding you need, so you should specify the encoding explicitly if possible.

Java 5 added four more constructors, though these are mostly just conveniences. They allow you to create a PrintStream that will write data in a file. The file to be written is specified with either a java.io.File object (which will be discussed in Chapter 17) or a String containing the filename. You can also specify the character encoding used to write the file:

public PrintStream(String fileName) throws FileNotFoundException
public PrintStream(String fileName, String encoding)
 throws FileNotFoundException, UnsupportedEncodingException
public PrintStream(File file) throws FileNotFoundException
public PrintStream(File file, String encoding)
 throws FileNotFoundException, UnsupportedEncodingException

These constructors don't accomplish anything that chaining a PrintStream to a FileOutputStream won't do.