public class File implements Serializable, Comparable {
    public static final char separatorChar ; 
    public static final String separator ; 
    public static final char pathSeparatorChar ; 
    public static final String pathSeparator ; 

// constructors: 
    public File(String path); 
    public File(String director y,String file); 
    public File(File director y,String file); 

// about the file: 
    public String getName(); 
    public String getParent(); 
    public File getParentFile(); 
    public String getPath(); 
    public String getAbsolutePath(); 
    public File getAbsoluteFile(); 
    public String getCanonicalPath() throws IOException; 
    public File getCanonicalFile() throws IOException; 

    public boolean canRead(); 
    public boolean canWrite(); 
    public boolean exists(); 
    public boolean isAbsolute(); 
    public boolean isDirectory(); 
    public boolean isFile(); 
    public boolean isHidden(); 
    public long lastModified(); 
    public long length(); 

// about the directory 
    public String[]  list(); 
    public String[] list(FilenameFilter); 
    public File[] listFiles(); 
    public File[] listFiles(FilenameFilter); 
    public File[] listFiles(FileFilter); 
    public static File[] listRoots(); 
    public boolean mkdir(); 
    public boolean mkdirs(); 
// using temporary files 
    public boolean createNewFile() throws IOException; 
    public boolean delete(); 
    public void deleteOnExit(); 
    public static File createTempFile(String, String) throws IOException; 
    public static File createTempFile(String, String, File) throws IOException; 

// miscellaneous: 
    public boolean renameTo(File); 
    public boolean setLastModified(long); 
    public boolean setReadOnly(); 
    public int compareTo(File); 
    public int compareTo(Object); 
    public boolean equals(Object); 
    public int hashCode(); 
    public String toString(); 
    public URL toURL() throws java.net.MalformedURLException; 
} 

You create a File object by giving strings for the directory and filename. The file doesn’t actually have to exist when you instantiate the File object, and you can go on to create it using createNewFile(). You only bother to instantiate a File object if one of the operations listed above is of interest to you. If you just want to do some I/O, then keep reading—that information is coming soon. Most of the method names in File give a clear indication of what they do. Here are the details on some of the less obvious ones.

public int compareTo(File); 

This method compares the pathnames of two files for equality or otherwise. Filename comparisons are platform-dependent, as Microsoft Windows does not distinguish letter case in filenames. A straight alphabetic comparison would give the wrong result on Windows, but the compareTo method ensures the correct ordering for the platform.

public static File createTempFile(String prefix, String suffix) throws IOException; 

This routine creates a temporary file in the default temporary directory. A unique filename will be generated for you, and it will have the prefix and suffix that you provide. This lets you give all temporary files created by, e.g., your mail program—a name that starts with “mail” and ends with “.tmp.” There is another form of this method that takes a third parameter, a File object, to specify the directory.

public boolean createNewFile() throws IOException; 
public void deleteOnExit(); 

These two routines could be used together to provide a simple file-locking protocol, giving exclusive access to some other file or resource. The createNewFile method would either atomically create a new file, or return “false” if the file already existed. “Atomically create” means that the check for the existence of the file, and the creation of the file if it does not exist, form a single operation. If there are several copies of your program running and making the same call at the same time, only one of them will succeed in creating the file. JDK 1.4 introduces the java.nio package which provides more direct support for file locking. See Chapter 14 for details.

public boolean mkdir(); 
public boolean mkdirs(); 

The first method creates just that directory. The second creates that directory plus any non-existent parent directory as needed.

public String[]  list(); 
public File[] listFiles(); 

The first method returns an array of strings representing the files and directories in the directory the method is invoked on. The second method returns the same information, but as File objects, not strings.

public static File[] listRoots(); 

This method lists all the available filesystems on this system. On Windows systems, the array will hold File objects for “A:”, “C:”, “D:”, and so on, allowing the programmer to learn what active drives there are. On Unix, the root drive is just “/” the root filesystem. On Windows, File objects for the root directories of the local and mapped network drives will be returned. Windows UNC pathnames (Universal Naming Convention pathnames that start with “//”) indicate a non-local file and are not returned by this method.

The basic operating system object used to manipulate files is called a file descriptor, but you’re not expected to create them or work with them much in Java.

For interest, we will mention what descriptors are, and then move on to some tips on portable I/O. A file descriptor is a non-negative integer, 0,1,2,3... etc., that is used by the native I/O system calls to index a control structure containing data about each open file or socket. Each process has its own table of file descriptors, with each entry pointing to an entry in a system-wide file descriptor table. The size of the process descriptor table places a limit on the number of files or sockets that a process can have open simultaneously. A typical size is 128 or 256 file descriptors.

Java applications should not create their own file descriptors. The FileInputStream and FileOutputStream classes have methods that get the file descriptor for a file that you have open, and that open the file for a descriptor that you have. The class java.io.FileDescriptor is used when the operating system needs a file descriptor, perhaps for a JNI call, or as part of the runtime library.

The basic portability approach of the Java runtime library is to have the same method do slightly different things appropriate to each platform. The standard end of line sequence on Windows is “carriage return, linefeed,” while on Unix it is just “linefeed.” Any library method that writes an end of line sequence, such as System.out.println(), will output a “carriage return, linefeed” pair on Windows, a linefeed on Unix, and a carriage return when run on the Mac. In contrast, any string data where you wrote a literal ' ' (line feed) or ' ' (carriage return) in a string will be output on every platform exactly as you wrote it.

There is a field in the class java.io.File that contains the filename separator, which is a backslash on Windows and a forward slash on Unix. Instead of writing a pathname as “ a/b/c.txt,” you can write it using the separator character, ensuring that it will be correct on all platforms. If you insist on reducing portability by using literal strings for pathnames, remember that backslash is also the string escape character. Therefore, you have to write it twice (to escape itself) when writing literal file names for the PC. Here is an example:

String myFile = “a\b\c.txt”; 

You can actually use “/” to separate components in a Windows pathname in a program. The Windows file system calls all use it internally. The Windows interactive shell, COMMAND.COM, is the only part of the system that can’t handle it. This is an interesting historical artifact, dating from the origins of MS-DOS as an unauthorized port (known as QDOS) of CP/M with a few trivial changes. That port was eventually bought by Microsoft, renamed to MS-DOS, and the rest is history. Most programmers form a filename by declaring a variable with a briefer name to represent the separator character, like this:

final String s = java.io.File.separator; 
String myFile = "a" + s + "b" + s + "c.txt"; 

This helps, but does not provide 100% data file portability because it doesn’t mention the Windows drive. The form of an absolute pathname differs from system to system. One approach to minimizing this is to tell the program its data filenames at runtime, either as command line arguments or as system properties.

Those five “write” output methods common to every Writer class (listed at the start of this section) are very spartan. Therefore, you usually “wrap” the destination Writer class with another Writer class that has more output methods. You wrap a class around the Writer by passing the Writer as an argument to the wrapping class’s constructor. Here’s an example that wraps a PrintWriter around the FileWriter we declared a few lines back:

// myPrt wraps myFW 
PrintWriter myPrt = new PrintWriter(myFW); 

The PrintWriter class is the one with the methods that actually transfer data to the Writer destination as printable strings. When you call a PrintWriter method, the data goes through to the destination writer that it is wrapped around, in this case the FileWriter.

public class java.io.PrintWriter extends java.io.Writer {
    public PrintWriter(java.io.Writer); 
    public PrintWriter(java.io.Writer,boolean); 
    public PrintWriter(java.io.OutputStream); 
    public PrintWriter(java.io.OutputStream,boolean); 
    public void flush(); 
    public void close(); 
    public boolean checkError(); 

    public void print(boolean); 
    public void print(char); 
    public void print(int); 
    public void print(long); 
    public void print(float); 
    public void print(double); 
    public void print(char[]); 
    public void print(java.lang.String); 
    public void print(java.lang.Object); 

   public void println(); 
     // there are also println versions of all the above print methods, e.g. 
   public void println(boolean); 
    // and so on... through to... 
   public void println(Object); 

   public void write(int); 
   public void write(char[]); 
   public void write(char[], int from, int to); 
   public void write(java.lang.String); 
   public void write(java.lang.String, int from, int to); 
} 

There is a print() method for most primitive types, and also a println() method that follows the output with the end of line sequence for that platform. There is no print(byte) because byte-oriented output is done with an OutputStream, not a Writer. The print methods are all implemented by calling the write methods. These write methods override similar methods in the parent Writer, and suppress IOExceptions. No methods in PrintWriter throw IOException. You can call the method checkError() to see if an I/O error occurred at some earlier point. The API designer should have named that method “ isError ” to follow the standard naming conventions, by the way.

As an aside, all the print methods are implemented in terms of the five basic write methods. Here is java.io.PrintWriter’s print(int) method in full:

public void print(int i) {
     write(String.valueOf(i)); 
} 

Writing everything in terms of the five basic write methods makes it very easy to implement wrapping. When you call myPW.print(i), that routine calls myPW.write(i) and that calls the write method of the object passed in to the constructor. The delegation continues along the line until the write request has been through all the wrappers and reaches an object that does the operation directly on a file or string in memory, etc.

Here is the code to create a file and write printable numbers and strings into it.

FileWriter myFW = null; 
try {
          myFW = new FileWriter( "\jj4\dogs.txt” ); 
} catch(IOException x) { System.err.println(“IOExcpn: “ + x); } 

PrintWriter myPW = new PrintWriter( myFW ); 
int i =101; 
myPW.print( i ); 
myPW.println(" Dalmatians”); 
myPW.close(); 

Notice the close() method in PrintWriter. Even though there is no separate open for files, all I/O stream classes have a close method. You should develop the habit of closing each stream as you are done with it. Java does not automatically flush and close streams just because you stop writing to them. Failing to close an output stream may leave it with some data not yet flushed to the underlying device. You should also close input streams when you are done with them, as a matter of good programming practice. Streams take up some OS resources, of which there is a limited quantity. By closing a stream when you are finished with it, you allow the JVM to give the file descriptor and buffers back to the OS. Also, for pipes/sockets/URLs, closing allows the other end of the connection to see an end-of-file, and therefore is able to gracefully terminate instead of waiting for an event that may never happen.

import java.io.*; 
class MyFilter extends java.io.FilterWriter {
        public MyFilter(Writer w) { super(w); } 

        public void write(String s, int off, int len) throws java.io.IOException {
             s = s.replace('1', '2'), 
             super.write(s, off, len); 
        } 

        public void write(char[] cbuf, int off, int len) throws IOException {
             String s= new String(cbuf); 
             this.write(s, off, len); 
        } 
} 

The lesson to take away from this is what a small amount of code is needed for such a large amount of functionality. Here is the code that uses the above filter. Try compiling and running it to see the results.

import java.io.*; 
public class Example2 {

       public static void main(String args[]) {
                FileWriter myFW = null; 
                try {
                         myFW = new FileWriter( "dogs.txt” ); 
                } catch(IOException x) { System.err.println(“IOExcpn: “ + x); } 

                FilterWriter filter = new MyFilter( myFW ); 
                BufferedWriter BW = new BufferedWriter(filter); 
                PrintWriter myPW = new PrintWriter( BW ); 
                myPW.println(“101 Dalmatians”); 
                myPW.close(); 
        } 
} 

In this example, the Filter overrides two of the write() methods, but you may need to override any or all of the FilterWriter methods depending on what you are doing. The example code also wraps a BufferedWriter around the filter, just to show how it is done. The API permits the BufferedWriter and the FilterWriter to be wrapped in either order. But to get the most performance benefit, you want as much of the pipeline as possible operating on buffers of data. So put the BufferedWriter as near to the start of the pipeline as possible (i.e., the BufferedWriter should be the outermost or next-outermost wrapper). This ensures that all wrapper objects downstream of the BufferedWriter are working with buffered data.

It’s common to cascade all these constructors together, like this:

PrintWriter myPW = new PrintWriter(
                                   new BufferedWriter(
                                       new myFilter(
                                            new FileWriter( "\jj4\dogs.txt” ) ) ) ); 

If you run the program and look at the output file dogs.txt, you will see the output has been filtered. It now contains “202 Dalmatians”.

The next section looks at output streams, which are analogous to Writers but work on a byte at a time, not a Unicode character at a time.

All Output Streams have these three basic output methods. You can write a single byte, or the bytes from an array, or a range of bytes from an array. Here are the signatures of these output methods:

public void write(int b); 
public void write(byte[]); 
public void write(byte[], int from, int len); 

The first method accepts an int argument, although you might expect a byte. This is a concession to reduce the amount of casting you may otherwise sometimes need to do. Whatever size of value you send in, only the least significant byte will be output.

These methods are promised by the abstract class OutputStream. All java.io classes with “OutputStream” in their name have these. You use OutputStreams for outputting bytes or binary values, not Unicode characters or objects. As with the Writer classes, you are expected to wrap another class around your Output Stream. One possible wrapper is a PrintStream class. Wrap that around a FileOutputStream or socket output stream, etc., when you wish to write printable bytes such as ASCII values. Another possible wrapper is the DataOutputStream class. Use DataOutputStream when you wish to do binary I/O. DataOutputStream has these output methods to write numbers in binary.

 public class java.io.DataOutputStream 
           extends java.io.FilterOutputStream 
                    implements java.io.DataOutput {
  // constructor 
    public DataOutputStream(java.io.OutputStream); 
    public final void writeBoolean(boolean) throws java.io.IOException; 
    public final void writeByte(int) throws java.io.IOException; 
    public final void writeShort(int) throws java.io.IOException; 
    public final void writeChar(int) throws java.io.IOException; 
    public final void writeInt(int) throws java.io.IOException; 
    public final void writeLong(long) throws java.io.IOException; 
    public final void writeFloat(float) throws java.io.IOException; 
    public final void writeDouble(double) throws java.io.IOException; 
    public final void writeBytes(java.lang.String) throws java.io.IOException; 
    public final void writeChars(java.lang.String) throws java.io.IOException; 
    public final void writeUTF(java.lang.String) throws java.io.IOException; 
    public void flush() throws java.io.IOException; 
    public synchronized void write(int) throws java.io.IOException; 

    public synchronized void write(byte[], int, int) throws java.io.IOException; 
    public final int size();  // returns number-of-bytes written so far 
} 

You will use DataOutputStream when you want to output numbers in binary format for later processing by another program. There is a write method for all primitive types, and also for Strings. Depending on which method you use, Strings will be written as 16-bit Unicode chars (writeChars), as 8-bit bytes discarding the high-order byte of each char (writeBytes), or in the UTF-encoded format where characters are 1-3 bytes in length (writeUTF) and preceded by a 16-bit length field. If you’re not sure what to use, you should write Strings using the writeBytes method. Or use a PrintStream instead. You use a PrintStream if all you need to do is output printable ASCII bytes.

When you wrap several classes, only write from the outermost one. Otherwise, your I/O may get mixed up due to internal buffering. You will use PrintStream when you want to output ISO 8859-1 text and numbers in readable format for reading by a person, but you do not need internationalization. The class java.io.PrintStream has the following methods:

 public class java.io.PrintStream extends java.io.FilterOutputStream {
    public PrintStream(java.io.OutputStream); 
    public PrintStream(java.io.OutputStream,boolean autoFlush); 
    public PrintStream(java.io.OutputStream,boolean,String encoding) throws 

java.io.Unsuppor tedEncodingException; 
    public void print(boolean); 
    public void print(char); 
    public void print(int); 
    public void print(long); 
    public void print(float); 
    public void print(double); 
    public void print(char[]); 
    public void print(java.lang.String); 
    public void print(java.lang.Object); 

    public void println(); 
    // there are also println versions of all the above print methods, e.g. 
    public void println(boolean); 
    // and so on ... 

    public void flush(); 
    public void close(); 
    public boolean checkError(); 
    public void write(int); 
    public void write(byte[], int, int); 
} 

Use PrintStream to write ASCII bytes. Use PrintWriter when you need to write internationalizable Unicode characters. All characters printed by a PrintStream are converted into bytes using the platform’s default character encoding, or the encoding given as an argument String to the constructor. Some examples of this are at the end of the next chapter.

On all Unix operating systems, and on Windows, three file descriptors are automatically opened by the shell that starts every process. This is even true on the Mac with OS-X (because OS-X is based on the Mach variant of Unix). The file descriptor convention is so common because it is a part of the C language API. File descriptor ’0’ is used for the standard input of the process. File descriptor ’1’ is used for the standard output of the process, and file descriptor ’2’ is used for the standard error of the process.

These three standard connections are known as “standard in,” “standard out,” and “standard err” or error. Normally, the standard input gets input from the keyboard, while standard output and standard error write data to the terminal from which the process was started. Every Java program contains two predefined PrintStreams, known as “out” and “err.” They are kept in Java.lang.System, and represent the command line output and error output, respectively. There is also an input stream called System.in that is the command line input. This is also referred to as console I/O or terminal I/O.

Anytime you have written System.out.println(“foo = “ + foo); you have already used a PrintStream, maybe without knowing it. See? It’s easier than you thought!

You can redirect the standard error, in, or out streams to a file or another stream (such as a socket) this way:

System.setErr(PrintStream err); 
System.setIn(InputStream in); 
System.setOut(PrintStream out); 

Stdin and stdout are used for low volume interactive I/O. Stderr is intended for error messages only. That way, if the output of a program is redirected somewhere, the error messages still appear on the console.

Here is some sample code to create a file and write binary numbers into it.

FileOutputStream myFOS = null; 
try {
        myFOS = new FileOutputStream( "numbers.bin” ); 
        DataOutputStream myDOS = new DataOutputStream( myFOS ); 
        myDOS.writeInt(29019 ); 
        myDOS.writeInt(3); 
        myDOS.writeInt(5); 
        myDOS.writeInt(67); 
} catch(IOException x) { System.err.println(“IOExcpn: “ + x); } 

If you look at the “numbers.bin” output file with an editor that can display the contents of a file in hexadecimal, you will see four, four-byte ints there containing the values written. Later in this chapter, we’ll develop the code to dump the contents of a file that way.

Instead of a DataOutputStream or a PrintStream, you can layer an ObjectOutputStream and write Java objects from your program out to disk or across the net on a socket. There’s a longer explanation of object I/O in the next chapter.

At the beginning of the chapter, we saw how a Writer could have a BufferedWriter and/or a subclass of FilterWriter interposed between the FileWriter (or other destination) and the PrintWriter. Output Streams can be wrapped in the same way to provide more functionality. You can wrap any or all of these output streams onto your original OutputStream:

The OutputStreamWriter class converts an OutputStream class to a Writer class, allowing you to layer any of the Writer classes on top of that. It provides a bridge from the 8-bit byte world to the 16-bit character world. The main motivation for doing so is that you can also specify the character set when you construct an OutputStreamWriter. Please review the next chapter for more information on character sets. It’s not something frequently used.

The CipherOutputStream will encrypt the stream that it gets and write the encrypted bytes. You have to set it up with a Cipher object (and a key). There is more detail in the online API documentation.

The zip, gzip, and jar output streams will compress the bytes written into them using the zip, gzip, and zip algorithms, respectively. Jar format is identical to zip format, but with the addition of a manifest file listing the names of other files in the archive. An example of writing an archive of several files in Zip format is shown in the next section.

The ObjectOutputStream class allows you to save an object and all the objects it references. You can wrap this class around any of the other output streams and send the object to a file, to a socket, down a pipe, etc. The next chapter shows an example of ObjectOutputStream in use.

Zip is a multifile archive format popularized by the PC but available on almost all systems now. The zip format offers two principal benefits: it can bundle several files into one file, and it can compress the data as it writes it to the zip archive. It’s more convenient to pass around one file than twenty separate files. Compressed files are faster and cheaper to download or e-mail than their uncompressed versions. Java Archives (.jar) files are in zip format.

Support for zip and gzip files was introduced with JDK 1.1. GZIP, an alternative to ZIP widely used on Unix, uses a different format for the data and can only hold one file (not a series of them).

Java has classes that will compress and expand files into either the gzip or the zip format. If you wrote a file out in zip format, you have to read it back in that way too. The same holds for gzip format. The formats are not interchangeable. If you have a choice, opt for zip over gzip because it does more and is much more widely used.

Files aren’t the only possible destination for zip streams (or any output, compressed or otherwise). You can equally send streams through a socket to another computer across the Internet, put them in a String or byte array for later retrieval, or send them through a pipe to another thread. The following is an example program showing how three files can be put into a zip archive. After running this program, compare the size of the zip archive with the sum of the sizes of the three files. Text strings compress well, binary data less so.

import java.io.*; 
import java.util.zip.*; 
public class Example4 {

      // writing a zip archive 
    static ZipOutputStream myZOS; 

      public static void main(String args[]) throws IOException {
               myZOS = new ZipOutputStream (
                                        new BufferedOutputStream (
                                                new FileOutputStream(“code.zip”) ) ); 
               writeOneFile(“Example1.java”); 
               writeOneFile(“Example2.java”); 
               writeOneFile(“Example3.java”); 
               myZOS.close(); 
      } 

      static void writeOneFile(String name) throws IOException {
               ZipEntr y myZE = new ZipEntr y(name); 
               myZOS.putNextEntr y(myZE); 

               BufferedReader myBR = new BufferedReader(
                                                                       new FileReader
(name) ); 
               int c; 
               while((c = myBR.read()) != -1)     // read a char until EOF 
                        myZOS.write(c);                  // write the char we just read 
               myBR.close(); 
      } 
} 

Executing this program will create a zip archive called code.zip. Each file in a zip archive is represented by an object called a ZipEntry. You can unpack it and recover the original source files with a Zip Input Stream, or use any of the standard Zip tools like winzip or Java’s jar command.

A very common mistake in Java is to use binary I/O where Unicode or ASCII I/O was intended. The numeric values transferred will not usually be human readable, and you’ll get a different length of data and a different value of data than you were expecting. The character values transferred will be fine because an ASCII character has the same bit representation whether it was written using an ASCII method or a binary method.

Let’s finish this section by looking at how Java copes with platform differences in I/O and data. Table 13-6 shows some I/O-related platform differences. The rightmost column shows the approach Java takes to minimize these differences.

The end-of-line sequence is different on different platforms. Most of the time it doesn’t matter. You can write out a “ ” character and platforms will interpret it correctly. If you have some legacy code that requires the actual end-of-line sequence, you can obtain it with the following method call:

String actualEOL = java.lang.System.getProper ty(“line.separator”); 

That statement will put the EOL sequence used by this platform into the variable. The println() methods of PrintWriter and PrintStream also output the EOL sequence of the specific platform. The I/O API often allows a file to be identified in two parts: the directory it is in, and the filename. That allows you to split off the platform-sensitive directory pathname from the comparatively portable filename string.

As usual, first decide between binary and character I/O, then choose your class based on where the data is coming from. For reading double-byte character data, you will use one of the Reader classes shown in Table 13-7. Note the symmetry with the Writer classes.

There are only four places from which you can read chars with a Reader, and FileReader is by far the most common. That class opens a connection onto a file. The constructors are shown in the table above. The constructor takes an argument that is the String pathname to the file, or a File object or FileDescriptor object.

All Readers give you at least these three somewhat basic input methods:

public int read() 
public int read(char[] cbuf) 
public int read(char[] cbuf, int from, int len) 

These read into, respectively, a single character, an array of characters, and a range in an array of characters. The call will not return until some data is available to read, although it won’t necessarily fill the array. The return value will be -1 if the Reader hits end of file (EOF). This is why the single char call returns a 32-bit int, even though it only reads a 16-bit character. The high-order 16 bits in the return value allow you to distinguish EOF from a character read. Those bits will be zero when a character is read, and 0xFFFF when EOF is reached. Test the return value for equality with -1 to see if you reached EOF.

At this point, from general symmetry, you are probably expecting to “wrap” another class on top of these Readers. That class will probably be called PrintReader, and it will have all the convenient methods for reading a String and returning a short, an int, a float, a boolean, etc. Bzzzt! Sorry, the design falls apart here. There is no such class as PrintReader. Not only that, there is no class that can give you the desired feature of being able to read back in exactly the same number values as were output using PrintWriter. The problem is an algorithmic one. Numbers in printed format vary in length, so your code has no way of telling where one number ends and an immediately adjacent starts. For example, if you use PrintWriter to print two ints like this into a file:

myPW.print(293); 
myPW.print(19); 

The file will contain the string “29319”, but if you try to read those numbers back in from that file, because of the variable length, there is no way of telling where one int ends and the next one starts. No program in any language can deduce whether the ints were originally 2 and 9319, or 29 and 319, or 293 and 19, or 2931 and 9. This problem does not arise with binary output, because all the binary types (short, int, float, etc.) have a fixed known size. This “where does a string of digits end?” problem is the reason that the XML language (see Chapter 28 on XML) always marks the end of a field with a closing tag.

The best you can do when reading printed numbers is to read characters until you hit something that can’t be part of a number (e.g., a space), then assemble a number out of the characters that preceded it. It’s common to break up such files with end-of-line sequences, and it’s convenient to be able to read a line at a time and tokenize (bundle together the groups of) the characters on that line.

You really need something more than reading individual characters though, so a kludgey little hack has been devised. A readLine() method has been placed in class BufferedReader. You can wrap a BufferedReader around a FileReader, which you probably want to do anyway for the performance, and then read lines from it. Each line comes into your program as a String with the end-of-line sequence removed. You can then tokenize the line however you like to recover individual values. Here’s an example of reading a line that way.

import java.io.*; 
public class Example4 {
       public static void main(String args[]) {
                FileReader myFR = null; 
                try {
                          myFR = new FileReader( "\jj4\dogs.txt” ); 
                } catch(IOException x) { System.err.println(“IOExcpn: “ + x); } 

                BufferedReader myBR = new BufferedReader(myFR); 

                try {
                          String in = myBR.readLine(); 
                          System.out.println(in); 
                } catch(IOException x) { System.err.println(“IOExcpn: “ + x); } 
       } 
} 

Another approach is to write all numeric strings into fixed length fields, say, 20 characters long. Then you can always read in fixed length input. Another approach is to avoid reading/writing printable data; instead, do it all with binary byte streams. Input is certainly messier than output.

The classes that wrap a Reader are:

All InputStreams give you at least these three somewhat basic input methods:

public int read() 
public int read(byte[] b) 
public int read(byte[] b, int from, int len) 

These read into, respectively, a single byte, an array of bytes, and a range in an array of bytes. The call will not return until some data is available to read, although it won’t necessarily fill the array. The return value will be -1 if the InputStream hits end of file (EOF). This is why the single byte call returns a 32-bit int, even though it only reads a 8-bit byte. The high-order 24 bits in the return value allow you to distinguish EOF from a byte read. Those bits will be zero when a data byte is read and 0xFFFFFF when EOF is reached.

The ByteArrayInputStream allows you to take data from a byte array in your program using the read() methods rather than array indexing. There is a new package in JDK 1.4 called java.nio. This package supports methods that write out an array full of data to a stream with one statement. (See Chapter 14 for an example.)

All java.io classes with “InputStream” in their name have a few other methods, too, like close(), available(), and skip(). They are methods promised by the abstract class InputStream. To harp once more on the theme that is stressed throughout this chapter: you use InputStreams for reading bytes or binary values, not Unicode characters or objects.

If those three basic read() methods aren’t enough, you will wrap another class around your Input Stream. The most common wrapper is a DataInputStream class to read binary bytes. Anything written with a DataOutputStream can be read back in by a DataInputStream. The DataInputStream class has these methods for binary input.

 public class java.io.DataInputStream 
         extends java.io.FilterInputStream implements java.io.DataInput {
    public DataInputStream(java.io.InputStream); 
    public final int read(byte[]) throws java.io.IOException; 
    public final int read(byte[], int, int) throws java.io.IOException; 
    public final void readFully(byte[]) throws java.io.IOException; 
    public final void readFully(byte[], int, int) throws java.io.IOException; 
    public final int skipBytes(int) throws java.io.IOException; 
    public final boolean readBoolean() throws java.io.IOException; 
    public final byte readByte() throws java.io.IOException; 
    public final int readUnsignedByte() throws java.io.IOException; 
    public final short readShort() throws java.io.IOException; 
    public final int readUnsignedShort() throws java.io.IOException; 
    public final char readChar() throws java.io.IOException; 
    public final int readInt() throws java.io.IOException; 
    public final long readLong() throws java.io.IOException; 
    public final float readFloat() throws java.io.IOException; 
    public final double readDouble() throws java.io.IOException; 
    public final String readLine() throws java.io.IOException;  // deprecated 
    public final String readUTF() throws java.io.IOException; 
    public static final String readUTF(java.io.DataInput) throws java.io.IOException; 
} 

As you can see, there is a read method for all primitive types, e.g., readInt() to read an int. A line of 8-bit bytes can be read into a String using the readLine() method, but this has been deprecated because it lacks proper byte-to-double-byte conversion. You can also read a string that was written in the UTF-encoded format where characters are 1-3 bytes in length (readUTF() method). The UTF format string is preceded by a 16-bit length field, allowing your code to scoop up the right amount of data. Notice that, although there is a DataOutputStream.write-Chars(), there is no DataInputStream.readChars(). You have to read chars one at a time, and you decide when you have read the entire string.

Let’s say a few words on the subject of IOExceptions. If you look at the runtime source, you’ll see that there are a dozen I/O-related exceptions. The most common I/O-related exceptions are:

FileNotFoundException EOFException InterruptedIOException UTFDataFormatError

These are all subclasses of IOException. InterruptedIOException was supposed to be raised when you called the interrupt method of a thread that was blocked on I/O. It didn’t work very well, and we’ll look at the replacement in the next chapter.

The name EOFException suggests that it is thrown whenever EOF (end of file) is encountered, and that therefore this exception might be used as the condition to break out of a loop. Unhappily, it can’t always be used that way. EOFException is raised in only three classes: DataInputStream, ObjectInputStream, and RandomAccessFile (and their subclasses, of course). The EOFException would be better named UnexpectedEOFException, as it is only raised when the programmer has asked for a fixed definite amount of input, and the end of file is reached before all the requested amount of data has been obtained.

EOFException is not a universal alert that the normal end of file has been reached. In FileInputStream or FileReader, you detect EOF by checking for the -1 return value from a read, not by trying to catch EOFException. So if you want to use an EOFException to terminate a loop, make sure that the methods you are using will throw you one. The compiler will generally warn you if you try to catch an exception that is not thrown.

FileNotFoundException is self-explanatory. UTFDataFormatException is thrown when the I/O library finds an inconsistency in reading some UTF data.

Here is some sample code to read a file and dump its contents in hexadecimal. The read method of FileInputStream returns -1 when it reaches EOF, so we use that to terminate the “get more input” loop.

// This program hex dumps the contents of the file 
// whose name is given as a commandline argument. 
import java.io.*; 
public class Dump {

    static FileInputStream myFIS = null; 
    static FileOutputStream myFOS = null; 
    static BufferedInputStream myBIS = null; 
    static PrintStream myPOS = null; 

    static public void main(String[] arg) {
           if (arg.length==0) {
                     System.out.println(“usage: java Dump somefile”); 
                     System.exit(); 
           } 
            PrintStream e = System.err ; 
           try {
                      myFIS = new FileInputStream( arg[0] ); 
                      myFOS = new FileOutputStream( arg[0] + “.hex” ); 

                      myBIS = new BufferedInputStream(myFIS); 
                      // the “true” says we want writes flushed to disk with each newline 
                      myPOS = new PrintStream (
                                                   new BufferedOutputStream(myFOS), true); 
                     myPOS.print(“Hex dump of file “ + arg[0]); 
                     int i; 
                      while ( (i=myBIS.read()) != -1 ) {
                               dump( (byte) i ); 
                      } 
           } catch(IOException x) {
                      e.println(“Exception: “ + x.getMessage() ); 
           } 
    } 

    static private long byteCount = 0; 

    static private void dump(byte b) {
           if (byteCount % 16 == 0) {
                      // output newline and the address ever y 16 bytes 
                     myPOS.println(); 
                     // pad leading zeros in address. 
                     String addr = Long.toHexString(byte Count); 
                     while (addr.length() < 8) addr = “0” + addr ; 
                     myPOS.print( addr + “:” ); 
           } 

           // output a space ever y 4 bytes 
          if (byteCount++ % 4 == 0) {
                     myPOS.print(“  “); 
           } 

           // dump the byte as 2 hex chars 
           String s = Integer.toHexString( b & 0xFF ); 
           if (s.length()==1) s = “0” + s; 
           myPOS.print( s.charAt(0) ); 
           myPOS.print( s.charAt(1) + “ “ ); 
    } 
} 

If you look at the “numbers.txt” output file with an editor that can display the contents of a file in hexadecimal, you will see four four-byte ints there containing the values written. Here is the beginning of the output you get from running this program on its own class file (it will vary with different compilers):

Hex dump of file Dump.class 
00000000:  ca fe ba be   00 03 00 2d   00 8e 0a 00   2f 00 45 09 
00000010:  00 46 00 47   07 00 48 0a   00 03 00 49   09 00 2e 00 
00000020:  4a 07 00 4b   07 00 4c 0a   00 07 00 45   0a 00 07 00 
00000030:  4d 08 00 4e   0a 00 07 00   4f 0a 00 06 

The first int word of this class file is 0xCAFE 0xBABE. The first word of all Java class files is 0xCAFE 0xBABE. It is what is known as a “magic number”— a special value put at a special place in a file to confer the magic ability to distinguish this kind of file from any other. It allows Java tools like the JVM to check that they have been given a class file to execute against. If you are going to put a special value there, you might as well use one that is easy to recognize and remember!

We wrap the FileInputStream in a BufferedInputStream as described in the next section. The program would work just as well without buffering, but may be slower for large input files. In JDK 1.4, the default size of a buffer in this class is 0.5KB. That’s much too small. For large inputs, you should do some measurements and think about moving this into the megabyte range.

The word “GZip” means GNU Zip. The GNU organization (a loose organization of expert programmers founded at MIT by Richard Stallman) has specified a simpler variant of a ZIP format that has become popular on Unix. It compresses its input by using the patent-free Lempel-Ziv coding. Gzip compressed format can only hold a single file, not an archive or directory of files, as with PK-ZIP. If you have several files, you must use the Unix “tar” utility to bundle them up into a single file first, then use the GZip Unix utility to compress that one file. Unpacking is the reverse of this. Here’s the simplest example code to unpack a GZip file.

// Expand a .gz file into uncompressed form 
// Peter van der Linden, August 2001 

import java.io.*; 
import java.util.zip.*; 
public class expandgz {

   public static void main (String args[]) throws Exception {
         if (args.length == 0) {
                System.out.println(“usage:  java expandgz  filename.gz”); 
                System.exit(0); 
         } 
         GZIPInputStream gzi = new GZIPInputStream(
                                                new FileInputStream( args[0] )); 
         int to = args[0].lastIndexOf('.'), 
         if (to == -1) {
                 System.out.println(“usage:  java expandgz  filename.gz”); 
                 System.exit(0); 
         } 
         String fout = args[0].substring(0, to); 
         BufferedOutputStream bos = new BufferedOutputStream(
                                                new FileOutputStream(fout) ); 
         System.out.println(“writing “ + fout); 

         int b; 
          do {
              b = gzi.read(); 
              if (b==-1) break; 
              bos.write(b); 
         } while (true); 
         gzi.close(); 
         bos.close(); 
   } 
} 

Executing this program will expand the gzip file whose name (e.g., abc.gz) is given on the command line. There is a corresponding GZIPOutputStream class that you can use to write a file into compressed gzip form. It would have been better for everyone if the GNU folks had not invented a new format, but just reverseengineered zip. The Unix world wasn’t paying enough attention to the PC world back in those days.

//   Convert a big number into binary and write it out 
//   Peter van der Linden, June 2001 

import java.io.*; 
import java.math.*; 
public class togz {

       static String illegalPrime = 
“4856507896573978293098418946942861377074420873513579240196520736” + 
“plug the rest of the number in here... “; 

       static BigInteger b = new BigInteger(illegalPrime); 
       static final BigInteger two_five_six = new BigInteger(“256”); 

       static byte[] result = new byte[illegalPrime.length()]; 

       public static void main (String args[]) throws Exception {
                BigInteger d_r []; 

                if (b.isProbablePrime(5)) 
                           System.out.println(“b is probably prime (good)”); 
                else System.out.println(“b is probably not prime (bad!)”); 

                int i=0; 
                do {
                           d_r = b.divideAndRemainder(two_five_six); 
                           b = d_r[0];     // the multiple 
                           result[i++] = (byte) d_r[1].intValue();  // the remainder 
                } while ( b.compareTo( two_five_six ) = 0); 

                result[i] = (byte) b.intValue(); 

                System.out.println(“writing bytes.gz”); 
                FileOutputStream fos = new FileOutputStream(“bytes.gz”); 

                DataOutputStream dos = new DataOutputStream(fos); 
                for (int j=i; j0; j--) {
                           dos.writeByte( result[j] ); 
                } 
                fos.close(); 
       } 
} 

Run winzip on the resulting .gz file to unpack it, and voila, you become eligible for a prison sentence of up to 20 years. What’s wrong with this picture? The CSS descrambler that you get is just three or four utility routines, not a main program. To play DVDs on your Linux, Mac, Solaris, or even Windows box, you’ll need to download the software from one of several open source DVD players. I like the one at www.videolan.org.

Alternatively, if you like putting things together by hand, you can do a websearch for “vobdec,” which is an open source utility that lets you discover the title keys on the encrypted DVDs that you own. If you have the title key you can run the efdtt utility (do another websearch) to turn the encrypted MPEG stream into a clear one and just point it at your favorite player.

Finally, you can try rewriting any of these in Java for fun. Just don’t blame me if the FBI knocks on your door with an MPAA warrant and seizes your debugger. Illegal code! The very idea! Next thing you know, they’ll be declaring t-shirts illegal.