The InputStream class has an abstract method:

abstract int read()

This method reads one byte and returns the byte that was read, or −1 if it encounters the end of the input source. The designer of a concrete input stream class overrides this method to provide useful functionality. For example, in the FileInputStream class, this method reads one byte from a file. System.in is a predefined object of a subclass of InputStream that allows you to read information from the keyboard.

The InputStream class also has nonabstract methods to read an array of bytes or to skip a number of bytes. These methods call the abstract read method, so subclasses need to override only one method.

Similarly, the OutputStream class defines the abstract method

abstract void write(int b)

which writes one byte to an output location.

Both the read and write methods block until the bytes are actually read or written. This means that if the stream cannot immediately be accessed (usually because of a busy network connection), the current thread blocks. This gives other threads the chance to do useful work while the method is waiting for the stream to again become available.

The available method lets you check the number of bytes that are currently available for reading. This means a fragment like the following is unlikely to block:

int bytesAvailable = in.available();
if (bytesAvailable > 0)
{
   byte[] data = new byte[bytesAvailable];
   in.read(data);
}

When you have finished reading or writing to a stream, close it by calling the close method. This call frees up operating system resources that are in limited supply. If an application opens too many streams without closing them, system resources can become depleted. Closing an output stream also flushes the buffer used for the output stream: any characters that were temporarily placed in a buffer so that they could be delivered as a larger packet are sent off. In particular, if you do not close a file, the last packet of bytes might never be delivered. You can also manually flush the output with the flush method.

Even if a stream class provides concrete methods to work with the raw read and write functions, application programmers rarely use them. The data that you are interested in probably contain numbers, strings, and objects, not raw bytes.

Java gives you many stream classes derived from the basic InputStream and OutputStream classes that let you work with data in the forms that you usually use rather than at the byte level.

java.io.InputStream 1.0

• abstract int read()

  reads a byte of data and returns the byte read. The read method returns a −1 at the end of the stream.

• int read(byte[] b)

  reads into an array of bytes and returns the actual number of bytes read, or −1 at the end of the stream. The read method reads at most b.length bytes.

• int read(byte[] b, int off, int len)

  reads into an array of bytes. The read method returns the actual number of bytes read, or −1 at the end of the stream.

  Parameters:	b	The array into which the data is read
  	off	The offset into b where the first bytes should be placed
  	len	The maximum number of bytes to read

• long skip(long n)

  skips n bytes in the input stream. Returns the actual number of bytes skipped (which may be less than n if the end of the stream was encountered).

• int available()

  returns the number of bytes available without blocking. (Recall that blocking means that the current thread loses its turn.)

• void close()

  closes the input stream.

• void mark(int readlimit)

  puts a marker at the current position in the input stream. (Not all streams support this feature.) If more than readlimit bytes have been read from the input stream, then the stream is allowed to forget the marker.

• void reset()

  returns to the last marker. Subsequent calls to read reread the bytes. If there is no current marker, then the stream is not reset.

• boolean markSupported()

  returns true if the stream supports marking.

java.io.OutputStream 1.0

• abstract void write(int n)

  writes a byte of data.

• void write(byte[] b)

• void write(byte[] b, int off, int len)

  writes all bytes or a range of bytes in the array b.

  Parameters:	b	The array from which to write the data
  	off	The offset into b to the first byte that will be written
  	len	The number of bytes to write

• void close()

  flushes and closes the output stream.

• void flush()

  flushes the output stream; that is, sends any buffered data to its destination.

Unlike C, which gets by just fine with a single type FILE*, Java has a whole zoo of more than 60 (!) different stream types (see Figures 1-1 and 1-2).

Figure 1-1. Input and output stream hierarchy

Figure 1-2. Reader and writer hierarchy

Let us divide the animals in the stream class zoo by how they are used. There are separate hierarchies for classes that process bytes and characters. As you saw, the InputStream and OutputStream classes let you read and write individual bytes and arrays of bytes. These classes form the basis of the hiearchy shown in Figure 1-1. To read and write strings and numbers, you need more capable subclasses. For example, DataInputStream and DataOutputStream let you read and write all the primitive Java types in binary format. Finally, there are streams that do useful stuff; for example, the ZipInputStream and ZipOutputStream that let you read and write files in the familiar ZIP compression format.

For Unicode text, on the other hand, you use subclasses of the abstract classes Reader and Writer (see Figure 1-2). The basic methods of the Reader and Writer classes are similar to the ones for InputStream and OutputStream.

abstract int read()
abstract void write(int c)

The read method returns either a Unicode code unit (as an integer between 0 and 65535) or −1 when you have reached the end of the file. The write method is called with a Unicode code unit. (See Volume I, Chapter 3 for a discussion of Unicode code units.)

Java SE 5.0 introduced four additional interfaces: Closeable, Flushable, Readable, and Appendable (see Figure 1-3). The first two interfaces are very simple, with methods

void close() throws IOException

and

void flush()

respectively. The classes InputStream, OutputStream, Reader, and Writer all implement the Closeable interface. OutputStream and Writer implement the Flushable interface.

Figure 1-3. The Closeable, Flushable, Readable, and Appendable interfaces

The Readable interface has a single method

int read(CharBuffer cb)

The CharBuffer class has methods for sequential and random read/write access. It represents an in-memory buffer or a memory-mapped file. (See “The Buffer Data Structure” on page 72 for details.)

The Appendable interface has two methods for appending single characters and character sequences:

Appendable append(char c)
Appendable append(CharSequence s)

The CharSequence interface describes basic properties of a sequence of char values. It is implemented by String, CharBuffer, StringBuilder, and StringBuffer.

Of the stream zoo classes, only Writer implements Appendable.

java.io.Closeable 5.0

• void close()

  closes this Closeable. This method may throw an IOException.

java.io.Flushable 5.0

• void flush()

  flushes this Flushable.

java.lang.Readable 5.0

• int read(CharBuffer cb)

  attempts to read as many char values into cb as it can hold. Returns the number of values read, or −1 if no further values are available from this Readable.

java.lang.Appendable 5.0

• Appendable append(char c)

• Appendable append(CharSequence cs)

  appends the given code unit, or all code units in the given sequence, to this Appendable; returns this.

java.lang.CharSequence 1.4

• char charAt(int index)

  returns the code unit at the given index.

• int length()

  returns the number of code units in this sequence.

• CharSequence subSequence(int startIndex, int endIndex)

  returns a CharSequence consisting of the code units stored at index startIndex to endIndex - 1.

• String toString()

  returns a string consisting of the code units of this sequence.

FileInputStream and FileOutputStream give you input and output streams attached to a disk file. You give the file name or full path name of the file in the constructor. For example,

FileInputStream fin = new FileInputStream("employee.dat");

looks in the user directory for a file named "employee.dat".

Tip

Because all the classes in java.io interpret relative path names as starting with the user’s working directory, you may want to know this directory. You can get at this information by a call to System.getProperty("user.dir").

Like the abstract InputStream and OutputStream classes, these classes support only reading and writing on the byte level. That is, we can only read bytes and byte arrays from the object fin.

byte b = (byte) fin.read();

As you will see in the next section, if we just had a DataInputStream, then we could read numeric types:

DataInputStream din = . . .;
double s = din.readDouble();

But just as the FileInputStream has no methods to read numeric types, the DataInputStream has no method to get data from a file.

Java uses a clever mechanism to separate two kinds of responsibilities. Some streams (such as the FileInputStream and the input stream returned by the openStream method of the URL class) can retrieve bytes from files and other more exotic locations. Other streams (such as the DataInputStream and the PrintWriter) can assemble bytes into more useful data types. The Java programmer has to combine the two. For example, to be able to read numbers from a file, first create a FileInputStream and then pass it to the constructor of a DataInputStream.

FileInputStream fin = new FileInputStream("employee.dat");
DataInputStream din = new DataInputStream(fin);
double s = din.readDouble();

If you look at Figure 1-1 again, you can see the classes FilterInputStream and FilterOutputStream. The subclasses of these files are used to add capabilities to raw byte streams.

You can add multiple capabilities by nesting the filters. For example, by default, streams are not buffered. That is, every call to read asks the operating system to dole out yet another byte. It is more efficient to request blocks of data instead and put them in a buffer. If you want buffering and the data input methods for a file, you need to use the following rather monstrous sequence of constructors:

DataInputStream din = new DataInputStream(
   new BufferedInputStream(
      new FileInputStream("employee.dat")));

Notice that we put the DataInputStream last in the chain of constructors because we want to use the DataInputStream methods, and we want them to use the buffered read method.

Sometimes you’ll need to keep track of the intermediate streams when chaining them together. For example, when reading input, you often need to peek at the next byte to see if it is the value that you expect. Java provides the PushbackInputStream for this purpose.

PushbackInputStream pbin = new PushbackInputStream(
   new BufferedInputStream(
      new FileInputStream("employee.dat")));

Now you can speculatively read the next byte

int b = pbin.read();

and throw it back if it isn’t what you wanted.

if (b != '<') pbin.unread(b);

But reading and unreading are the only methods that apply to the pushback input stream. If you want to look ahead and also read numbers, then you need both a pushback input stream and a data input stream reference.

DataInputStream din = new DataInputStream(
   pbin = new PushbackInputStream(
      new BufferedInputStream(
         new FileInputStream("employee.dat"))));

Of course, in the stream libraries of other programming languages, niceties such as buffering and lookahead are automatically taken care of, so it is a bit of a hassle in Java that one has to resort to combining stream filters in these cases. But the ability to mix and match filter classes to construct truly useful sequences of streams does give you an immense amount of flexibility. For example, you can read numbers from a compressed ZIP file by using the following sequence of streams (see Figure 1-4):

ZipInputStream zin = new ZipInputStream(new FileInputStream("employee.zip"));
DataInputStream din = new DataInputStream(zin);

Figure 1-4. A sequence of filtered streams

(See “ZIP Archives” on page 32 for more on Java’s ability to handle ZIP files.)

java.io.FileInputStream 1.0

• FileInputStream(String name)

• FileInputStream(File file)

  creates a new file input stream, using the file whose path name is specified by the name string or the file object. (The File class is described at the end of this chapter.) Path names that are not absolute are resolved relative to the working directory that was set when the VM started.

java.io.FileOutputStream 1.0

• FileOutputStream(String name)

• FileOutputStream(String name, boolean append)

• FileOutputStream(File file)

• FileOutputStream(File file, boolean append)

  creates a new file output stream specified by the name string or the file object. (The File class is described at the end of this chapter.) If the append parameter is true, then data are added at the end of the file. An existing file with the same name will not be deleted. Otherwise, this method deletes any existing file with the same name.

java.io.BufferedInputStream 1.0

• BufferedInputStream(InputStream in)

  creates a buffered stream. A buffered input stream reads characters from a stream without causing a device access every time. When the buffer is empty, a new block of data is read into the buffer.

java.io.BufferedOutputStream 1.0

• BufferedOutputStream(OutputStream out)

  creates a buffered stream. A buffered output stream collects characters to be written without causing a device access every time. When the buffer fills up or when the stream is flushed, the data are written.

java.io.PushbackInputStream 1.0

• PushbackInputStream(InputStream in)

• PushbackInputStream(InputStream in, int size)

  constructs a stream with one-byte lookahead or a pushback buffer of specified size.

• void unread(int b)

  pushes back a byte, which is retrieved again by the next call to read.

  Parameters:

  b

  The byte to be read again

For text output, you want to use a PrintWriter. That class has methods to print strings and numbers in text format. There is even a convenience constructor to link a PrintWriter with a FileWriter. The statement

PrintWriter out = new PrintWriter("employee.txt");

is equivalent to

PrintWriter out = new PrintWriter(new FileWriter("employee.txt"));

To write to a print writer, you use the same print, println, and printf methods that you used with System.out. You can use these methods to print numbers (int, short, long, float, double), characters, boolean values, strings, and objects.

For example, consider this code:

String name = "Harry Hacker";
double salary = 75000;
out.print(name);
out.print(' '),
out.println(salary);

This writes the characters

Harry Hacker 75000.0

to the writer out. The characters are then converted to bytes and end up in the file employee.txt.

The println method adds the correct end-of-line character for the target system (" " on Windows, " " on UNIX) to the line. This is the string obtained by the call System.getProperty("line.separator").

If the writer is set to autoflush mode, then all characters in the buffer are sent to their destination whenever println is called. (Print writers are always buffered.) By default, autoflushing is not enabled. You can enable or disable autoflushing by using the PrintWriter(Writer out, boolean autoFlush) constructor:

PrintWriter out = new PrintWriter(new FileWriter("employee.txt"), true); // autoflush

The print methods don’t throw exceptions. You can call the checkError method to see if something went wrong with the stream.

Note

Java veterans might wonder whatever happened to the PrintStream class and to System.out. In Java 1.0, the PrintStream class simply truncated all Unicode characters to ASCII characters by dropping the top byte. Clearly, that was not a clean or portable approach, and it was fixed with the introduction of readers and writers in Java 1.1. For compatibility with existing code, System.in, System.out, and System.err are still streams, not readers and writers. But now the PrintStream class internally converts Unicode characters to the default host encoding in the same way as the PrintWriter does. Objects of type PrintStream act exactly like print writers when you use the print and println methods, but unlike print writers, they allow you to output raw bytes with the write(int) and write(byte[]) methods.

java.io.PrintWriter 1.1

• PrintWriter(Writer out)

• PrintWriter(Writer out, boolean autoFlush)

  creates a new PrintWriter.

  Parameters:	out	A character-output writer
  	autoflush	If true, the println methods will flush the output buffer (default: false)

• PrintWriter(OutputStream out)

• PrintWriter(OutputStream out, boolean autoflush)

  creates a new PrintWriter from an existing OutputStream by creating the necessary intermediate OutputStreamWriter.

• PrintWriter(String filename)

• PrintWriter(File file)

  creates a new PrintWriter that writes to the given file by creating the necessary intermediate FileWriter.

• void print(Object obj)

  prints an object by printing the string resulting from toString.

  Parameters:

  obj

  The object to be printed

• void print(String s)

  prints a Unicode string.

• void println(String s)

  prints a string followed by a line terminator. Flushes the stream if the stream is in autoflush mode.

• void print(char[] s)

  prints all Unicode characters in the given array.

• void print(char c)

  prints a Unicode character.

• void print(int i)

• void print(long l)

• void print(float f)

• void print(double d)

• void print(boolean b)

  prints the given value in text format.

• void printf(String format, Object... args)

  prints the given values, as specified by the format string. See Volume I, Chapter 3 for the specification of the format string.

• boolean checkError()

  returns true if a formatting or output error occurred. Once the stream has encountered an error, it is tainted and all calls to checkError return true.

As you know:

Therefore, you might expect that there is an analog to the DataInputStream that lets you read data in text format. The closest analog is the Scanner class that we used extensively in Volume I. However, before Java SE 5.0, the only game in town for processing text input was the BufferedReader class—it has a method, readLine, that lets you read a line of text. You need to combine a buffered reader with an input source.

BufferedReader in = new BufferedReader(new FileReader("employee.txt"));

The readLine method returns null when no more input is available. A typical input loop, therefore, looks like this:

String line;
while ((line = in.readLine()) != null)
{
   do something with line
}

However, a BufferedReader has no methods for reading numbers. We suggest that you use a Scanner for reading text input.

In this section, we walk you through an example program that stores an array of Employee records in a text file. Each record is stored in a separate line. Instance fields are separated from each other by delimiters. We use a vertical bar (|) as our delimiter. (A colon (:) is another popular choice. Part of the fun is that everyone uses a different delimiter.) Naturally, we punt on the issue of what might happen if a | actually occurred in one of the strings we save.

Here is a sample set of records:

Harry Hacker|35500|1989|10|1
Carl Cracker|75000|1987|12|15
Tony Tester|38000|1990|3|15

Writing records is simple. Because we write to a text file, we use the PrintWriter class. We simply write all fields, followed by either a | or, for the last field, a . This work is done in the following writeData method that we add to our Employee class.

public void writeData(PrintWriter out) throws IOException
{
   GregorianCalendar calendar = new GregorianCalendar();
   calendar.setTime(hireDay);
   out.println(name + "|"
      + salary + "|"
      + calendar.get(Calendar.YEAR) + "|"
      + (calendar.get(Calendar.MONTH) + 1) + "|"
      + calendar.get(Calendar.DAY_OF_MONTH));
}

To read records, we read in a line at a time and separate the fields. We use a scanner to read each line and then split the line into tokens with the String.split method.

public void readData(Scanner in)
{
   String line = in.nextLine();
   String[] tokens = line.split("\|");
   name = tokens[0];
   salary = Double.parseDouble(tokens[1]);
   int y = Integer.parseInt(tokens[2]);
   int m = Integer.parseInt(tokens[3]);
   int d = Integer.parseInt(tokens[4]);
   GregorianCalendar calendar = new GregorianCalendar(y, m - 1, d);
   hireDay = calendar.getTime();
}

The parameter of the split method is a regular expression describing the separator. We discuss regular expressions in more detail at the end of this chapter. As it happens, the vertical bar character has a special meaning in regular expressions, so it needs to be escaped with a character. That character needs to be escaped by another , yielding the "\|" expression.

The complete program is in Listing 1-1. The static method

void writeData(Employee[] e, PrintWriter out)

first writes the length of the array, then writes each record. The static method

Employee[] readData(BufferedReader in)

first reads in the length of the array, then reads in each record. This turns out to be a bit tricky:

int n = in.nextInt();
in.nextLine(); // consume newline
Employee[] employees = new Employee[n];
for (int i = 0; i < n; i++)
{
   employees[i] = new Employee();
   employees[i].readData(in);
}

The call to nextInt reads the array length but not the trailing newline character. We must consume the newline so that the readData method can get the next input line when it calls the nextLine method.

  1. import java.io.*;
  2. import java.util.*;
  3.
  4. /**
  5.  * @version 1.12 2007-06-22
  6.  * @author Cay Horstmann
  7.  */
  8. public class TextFileTest
  9. {
 10.    public static void main(String[] args)
 11.    {
 12.       Employee[] staff = new Employee[3];
 13.
 14.       staff[0] = new Employee("Carl Cracker", 75000, 1987, 12, 15);
 15.       staff[1] = new Employee("Harry Hacker", 50000, 1989, 10, 1);
 16.       staff[2] = new Employee("Tony Tester", 40000, 1990, 3, 15);
 17.
 18.       try
 19.       {
 20.          // save all employee records to the file employee.dat
 21.          PrintWriter out = new PrintWriter("employee.dat");
 22.          writeData(staff, out);
 23.          out.close();
 24.
 25.          // retrieve all records into a new array
 26.          Scanner in = new Scanner(new FileReader("employee.dat"));
 27.          Employee[] newStaff = readData(in);
 28.          in.close();
 29.
 30.          // print the newly read employee records
 31.          for (Employee e : newStaff)
 32.             System.out.println(e);
 33.       }
 34.       catch (IOException exception)
 35.       {
 36.          exception.printStackTrace();
 37.       }
 38.    }
 39.
 40.    /**
 41.     * Writes all employees in an array to a print writer
 42.     * @param employees an array of employees
 43.     * @param out a print writer
 44.     */
 45.    private static void writeData(Employee[] employees, PrintWriter out) throws IOException
 46.    {
 47.       // write number of employees
 48.       out.println(employees.length);
 49.
 50.       for (Employee e : employees)
 51.          e.writeData(out);
 52.    }
 53.    /**
 54.     * Reads an array of employees from a scanner
 55.     * @param in the scanner
 56.     * @return the array of employees
 57.     */
 58.    private static Employee[] readData(Scanner in)
 59.    {
 60.       // retrieve the array size
 61.       int n = in.nextInt();
 62.       in.nextLine(); // consume newline
 63.
 64.       Employee[] employees = new Employee[n];
 65.       for (int i = 0; i < n; i++)
 66.       {
 67.          employees[i] = new Employee();
 68.          employees[i].readData(in);
 69.       }
 70.       return employees;
 71.    }
 72. }
 73.
 74. class Employee
 75. {
 76.    public Employee()
 77.    {
 78.    }
 79.
 80.    public Employee(String n, double s, int year, int month, int day)
 81.    {
 82.       name = n;
 83.       salary = s;
 84.       GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day);
 85.       hireDay = calendar.getTime();
 86.    }
 87.
 88.    public String getName()
 89.    {
 90.       return name;
 91.    }
 92.
 93.    public double getSalary()
 94.    {
 95.       return salary;
 96.    }
 97.
 98.    public Date getHireDay()
 99.    {
100.       return hireDay;
101.    }
102.
103.    public void raiseSalary(double byPercent)
104.    {
105.       double raise = salary * byPercent / 100;
106.       salary += raise;
107.    }
108.
109.    public String toString()
110.    {
111.       return getClass().getName() + "[name=" + name + ",salary=" + salary + ",hireDay="
112.             + hireDay + "]";
113.    }
114.
115.    /**
116.     * Writes employee data to a print writer
117.     * @param out the print writer
118.     */
119.    public void writeData(PrintWriter out)
120.    {
121.       GregorianCalendar calendar = new GregorianCalendar();
122.       calendar.setTime(hireDay);
123.       out.println(name + "|" + salary + "|" + calendar.get(Calendar.YEAR) + "|"
124.            + (calendar.get(Calendar.MONTH) + 1) + "|" + calendar.get(Calendar.DAY_OF_MONTH));
125.    }
126.
127.    /**
128.     * Reads employee data from a buffered reader
129.     * @param in the scanner
130.     */
131.    public void readData(Scanner in)
132.    {
133.       String line = in.nextLine();
134.       String[] tokens = line.split("\|");
135.       name = tokens[0];
136.       salary = Double.parseDouble(tokens[1]);
137.       int y = Integer.parseInt(tokens[2]);
138.       int m = Integer.parseInt(tokens[3]);
139.       int d = Integer.parseInt(tokens[4]);
140.       GregorianCalendar calendar = new GregorianCalendar(y, m - 1, d);
141.       hireDay = calendar.getTime();
142.    }
143.
144.    private String name;
145.    private double salary;
146.    private Date hireDay;
147. }

In the past, international character sets have been handled rather unsystematically throughout the Java library. The java.nio package—introduced in Java SE 1.4—unifies character set conversion with the introduction of the Charset class. (Note that the s is lower case.)

A character set maps between sequences of two-byte Unicode code units and byte sequences used in a local character encoding. One of the most popular character encodings is ISO-8859-1, a single-byte encoding of the first 256 Unicode characters. Gaining in importance is ISO-8859-15, which replaces some of the less useful characters of ISO-8859-1 with accented letters used in French and Finnish, and, more important, replaces the “international currency” character ¤ with the Euro symbol (€) in code point 0xA4. Other examples for character encodings are the variable-byte encodings commonly used for Japanese and Chinese.

The Charset class uses the character set names standardized in the IANA Character Set Registry (http://www.iana.org/assignments/character-sets). These names differ slightly from those used in previous versions. For example, the “official” name of ISO-8859-1 is now "ISO-8859-1" and no longer "ISO8859_1", which was the preferred name up to Java SE 1.3.

Note

An excellent reference for the “ISO 8859 alphabet soup” is http://czyborra.com/charsets/iso8859.html.

You obtain a Charset by calling the static forName method with either the official name or one of its aliases:

Charset cset = Charset.forName("ISO-8859-1");

Character set names are case insensitive.

For compatibility with other naming conventions, each character set can have a number of aliases. For example, ISO-8859-1 has aliases

ISO8859-1
ISO_8859_1
ISO8859_1
ISO_8859-1
ISO_8859-1:1987
8859_1
latin1
l1
csISOLatin1
iso-ir-100
cp819
IBM819
IBM-819
819

The aliases method returns a Set object of the aliases. Here is the code to iterate through the aliases:

Set<String> aliases = cset.aliases();
for (String alias : aliases)
   System.out.println(alias);

To find out which character sets are available in a particular implementation, call the static availableCharsets method. Use this code to find out the names of all available character sets:

Map<String, Charset> charsets = Charset.availableCharsets();
for (String name : charsets.keySet())
   System.out.println(name);

Table 1-1 lists the character encodings that every Java implementation is required to have. Table 1-2 lists the encoding schemes that the Java Development Kit (JDK) installs by default. The character sets in Table 1-3 are installed only on operating systems that use non-European languages.

Local encoding schemes cannot represent all Unicode characters. If a character cannot be represented, it is transformed to a ?.

Once you have a character set, you can use it to convert between Unicode strings and encoded byte sequences. Here is how you encode a Unicode string:

String str = . . .;
ByteBuffer buffer = cset.encode(str);
byte[] bytes = buffer.array();

Conversely, to decode a byte sequence, you need a byte buffer. Use the static wrap method of the ByteBuffer array to turn a byte array into a byte buffer. The result of the decode method is a CharBuffer. Call its toString method to get a string.

byte[] bytes = . . .;
ByteBuffer bbuf = ByteBuffer.wrap(bytes, offset, length);
CharBuffer cbuf = cset.decode(bbuf);
String str = cbuf.toString();

java.nio.charset.Charset 1.4

• static SortedMap availableCharsets()

  gets all available character sets for this virtual machine. Returns a map whose keys are character set names and whose values are character sets.

• static Charset forName(String name)

  gets a character set for the given name.

• Set aliases()

  returns the set of alias names for this character set.

• ByteBuffer encode(String str)

  encodes the given string into a sequence of bytes.

• CharBuffer decode(ByteBuffer buffer)

  decodes the given byte sequence. Unrecognized inputs are converted to the Unicode “replacement character” ('uFFFD').

java.nio.ByteBuffer 1.4

• byte[] array()

  returns the array of bytes that this buffer manages.

• static ByteBuffer wrap(byte[] bytes)

• static ByteBuffer wrap(byte[] bytes, int offset, int length)

  returns a byte buffer that manages the given array of bytes or the given range.

java.nio.CharBuffer

• char[] array()

  returns the array of code units that this buffer manages.

• char charAt(int index)

  returns the code unit at the given index.

• String toString()

  returns a string consisting of the code units that this buffer manages.

The RandomAccessFile class lets you find or write data anywhere in a file. Disk files are random access, but streams of data from a network are not. You open a random-access file either for reading only or for both reading and writing. You specify the option by using the string "r" (for read access) or "rw" (for read/write access) as the second argument in the constructor.

RandomAccessFile in = new RandomAccessFile("employee.dat", "r");
RandomAccessFile inOut = new RandomAccessFile("employee.dat", "rw");

When you open an existing file as a RandomAccessFile, it does not get deleted.

A random-access file has a file pointer that indicates the position of the next byte that will be read or written. The seek method sets the file pointer to an arbitrary byte position within the file. The argument to seek is a long integer between zero and the length of the file in bytes.

The getFilePointer method returns the current position of the file pointer.

The RandomAccessFile class implements both the DataInput and DataOutput interfaces. To read and write from a random-access file, you use methods such as readInt/writeInt and readChar/writeChar that we discussed in the preceding section.

We now walk through an example program that stores employee records in a random access file. Each record will have the same size. This makes it easy to read an arbitrary record. Suppose you want to position the file pointer to the third record. Simply set the file pointer to the appropriate byte position and start reading.

long n = 3;
in.seek((n - 1) * RECORD_SIZE);
Employee e = new Employee();
e.readData(in);

If you want to modify the record and then save it back into the same location, remember to set the file pointer back to the beginning of the record:

in.seek((n - 1) * RECORD_SIZE);
e.writeData(out);

To determine the total number of bytes in a file, use the length method. The total number of records is the length divided by the size of each record.

long nbytes = in.length(); // length in bytes
int nrecords = (int) (nbytes / RECORD_SIZE);

Integers and floating-point values have a fixed size in binary format, but we have to work harder for strings. We provide two helper methods to write and read strings of a fixed size.

The writeFixedString writes the specified number of code units, starting at the beginning of the string. (If there are too few code units, the method pads the string, using zero values.)

public static void writeFixedString(String s, int size, DataOutput out)
   throws IOException
{
   for (int i = 0; i < size; i++)
   {
      char ch = 0;
      if (i < s.length()) ch = s.charAt(i);
      out.writeChar(ch);
   }
}

The readFixedString method reads characters from the input stream until it has consumed size code units or until it encounters a character with a zero value. Then, it skips past the remaining zero values in the input field. For added efficiency, this method uses the StringBuilder class to read in a string.

public static String readFixedString(int size, DataInput in)
   throws IOException
{
   StringBuilder b = new StringBuilder(size);
   int i = 0;
   boolean more = true;
   while (more && i < size)
   {
      char ch = in.readChar();
      i++;
      if (ch == 0) more = false;
      else b.append(ch);
   }
   in.skipBytes(2 * (size - i));
   return b.toString();
}

We placed the writeFixedString and readFixedString methods inside the DataIO helper class.

To write a fixed-size record, we simply write all fields in binary.

public void writeData(DataOutput out) throws IOException
{
   DataIO.writeFixedString(name, NAME_SIZE, out);
   out.writeDouble(salary);

   GregorianCalendar calendar = new GregorianCalendar();
   calendar.setTime(hireDay);
   out.writeInt(calendar.get(Calendar.YEAR));
   out.writeInt(calendar.get(Calendar.MONTH) + 1);
   out.writeInt(calendar.get(Calendar.DAY_OF_MONTH));
}

Reading the data back is just as simple.

public void readData(DataInput in) throws IOException
{
   name = DataIO.readFixedString(NAME_SIZE, in);
   salary = in.readDouble();
   int y = in.readInt();
   int m = in.readInt();
   int d = in.readInt();
   GregorianCalendar calendar = new GregorianCalendar(y, m - 1, d);
   hireDay = calendar.getTime();
}

Let us compute the size of each record. We will use 40 characters for the name strings. Therefore, each record contains 100 bytes:

The program shown in Listing 1-2 writes three records into a data file and then reads them from the file in reverse order. To do this efficiently requires random access—we need to get at the third record first.

  1. import java.io.*;
  2. import java.util.*;
  3.
  4. /**
  5.   * @version 1.11 2004-05-11
  6.   * @author Cay Horstmann
  7.   */
  8.
  9. public class RandomFileTest
 10. {
 11.    public static void main(String[] args)
 12.    {
 13.       Employee[] staff = new Employee[3];
 14.
 15.       staff[0] = new Employee("Carl Cracker", 75000, 1987, 12, 15);
 16.       staff[1] = new Employee("Harry Hacker", 50000, 1989, 10, 1);
 17.       staff[2] = new Employee("Tony Tester", 40000, 1990, 3, 15);
 18.
 19.       try
 20.       {
 21.          // save all employee records to the file employee.dat
 22.          DataOutputStream out = new DataOutputStream(new FileOutputStream("employee.dat"));
 23.          for (Employee e : staff)
 24.             e.writeData(out);
 25.          out.close();
 26.
 27.          // retrieve all records into a new array
 28.          RandomAccessFile in = new RandomAccessFile("employee.dat", "r");
 29.          // compute the array size
 30.          int n = (int)(in.length() / Employee.RECORD_SIZE);
 31.          Employee[] newStaff = new Employee[n];
 32.
 33.          // read employees in reverse order
 34.          for (int i = n - 1; i >= 0; i--)
 35.          {
 36.             newStaff[i] = new Employee();
 37.             in.seek(i * Employee.RECORD_SIZE);
 38.             newStaff[i].readData(in);
 39.          }
 40.          in.close();
 41.
 42.          // print the newly read employee records
 43.          for (Employee e : newStaff)
 44.             System.out.println(e);
 45.       }
 46.       catch (IOException e)
 47.       {
 48.          e.printStackTrace();
 49.       }
 50.    }
 51. }
 52.
 53. class Employee
 54. {
 55.    public Employee() {}
 56.
 57.    public Employee(String n, double s, int year, int month, int day)
 58.    {
 59.       name = n;
 60.       salary = s;
 61.       GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day);
 62.       hireDay = calendar.getTime();
 63.    }
 64.
 65.    public String getName()
 66.    {
 67.       return name;
 68.    }
 69.
 70.    public double getSalary()
 71.    {
 72.       return salary;
 73.    }
 74.
 75.    public Date getHireDay()
 76.    {
 77.       return hireDay;
 78.    }
 79.
 80.    /**
 81.       Raises the salary of this employee.
 82.       @byPercent the percentage of the raise
 83.    */
 84.    public void raiseSalary(double byPercent)
 85.    {
 86.       double raise = salary * byPercent / 100;
 87.       salary += raise;
 88.    }
 89.
 90.    public String toString()
 91.    {
 92.       return getClass().getName()
 93.          + "[name=" + name
 94.          + ",salary=" + salary
 95.          + ",hireDay=" + hireDay
 96.          + "]";
 97.    }
 98.
 99.    /**
100.       Writes employee data to a data output
101.       @param out the data output
102.    */
103.    public void writeData(DataOutput out) throws IOException
104.    {
105.       DataIO.writeFixedString(name, NAME_SIZE, out);
106.       out.writeDouble(salary);
107.
108.       GregorianCalendar calendar = new GregorianCalendar();
109.       calendar.setTime(hireDay);
110.       out.writeInt(calendar.get(Calendar.YEAR));
111.       out.writeInt(calendar.get(Calendar.MONTH) + 1);
112.       out.writeInt(calendar.get(Calendar.DAY_OF_MONTH));
113.    }
114.
115.    /**
116.       Reads employee data from a data input
117.       @param in the data input
118.    */
119.    public void readData(DataInput in) throws IOException
120.    {
121.       name = DataIO.readFixedString(NAME_SIZE, in);
122.       salary = in.readDouble();
123.       int y = in.readInt();
124.       int m = in.readInt();
125.       int d = in.readInt();
126.       GregorianCalendar calendar = new GregorianCalendar(y, m - 1, d);
127.       hireDay = calendar.getTime();
128.    }
129.
130.    public static final int NAME_SIZE = 40;
131.    public static final int RECORD_SIZE = 2 * NAME_SIZE + 8 + 4 + 4 + 4;
132.
133.    private String name;
134.    private double salary;
135.    private Date hireDay;
136. }
137.
138. class DataIO
139. {
140.    public static String readFixedString(int size, DataInput in)
141.       throws IOException
142.    {
143.       StringBuilder b = new StringBuilder(size);
144.       int i = 0;
145.       boolean more = true;
146.       while (more && i < size)
147.       {
148.          char ch = in.readChar();
149.          i++;
150.          if (ch == 0) more = false;
151.          else b.append(ch);
152.       }
153.       in.skipBytes(2 * (size - i));
154.       return b.toString();
155.    }
156.
157.    public static void writeFixedString(String s, int size, DataOutput out)
158.       throws IOException
159.    {
160.       for (int i = 0; i < size; i++)
161.       {
162.          char ch = 0;
163.          if (i < s.length()) ch = s.charAt(i);
164.          out.writeChar(ch);
165.       }
166.    }
167. }

java.io.RandomAccessFile 1.0

• RandomAccessFile(String file, String mode)

• RandomAccessFile(File file, String mode)

  Parameters:	file	The file to be opened
  	mode	"r" for read-only mode, "rw" for read/write mode, "rws" for read/write mode with synchronous disk writes of data and metadata for every update, and "rwd" for read/write mode with synchronous disk writes of data only

• long getFilePointer()

  returns the current location of the file pointer.

• void seek(long pos)

  sets the file pointer to pos bytes from the beginning of the file.

• long length()

  returns the length of the file in bytes.

Object serialization saves object data in a particular file format. Of course, you can use the writeObject/readObject methods without having to know the exact sequence of bytes that represents objects in a file. Nonetheless, we found studying the data format to be extremely helpful for gaining insight into the object streaming process. Because the details are somewhat technical, feel free to skip this section if you are not interested in the implementation.

Every file begins with the two-byte “magic number”

AC ED

followed by the version number of the object serialization format, which is currently

00 05

(We use hexadecimal numbers throughout this section to denote bytes.) Then, it contains a sequence of objects, in the order that they were saved.

String objects are saved as

For example, the string “Harry” is saved as

74 00 05 Harry

The Unicode characters of the string are saved in “modified UTF-8” format.

When an object is saved, the class of that object must be saved as well. The class description contains

The fingerprint is obtained by ordering descriptions of the class, superclass, interfaces, field types, and method signatures in a canonical way, and then applying the so-called Secure Hash Algorithm (SHA) to that data.

SHA is a fast algorithm that gives a “fingerprint” to a larger block of information. This fingerprint is always a 20-byte data packet, regardless of the size of the original data. It is created by a clever sequence of bit operations on the data that makes it essentially 100 percent certain that the fingerprint will change if the information is altered in any way. (For more details on SHA, see, for example, Cryptography and Network Security: Principles and Practice, by William Stallings [Prentice Hall, 2002].) However, the serialization mechanism uses only the first 8 bytes of the SHA code as a class fingerprint. It is still very likely that the class fingerprint will change if the data fields or methods change.

When reading an object, its fingerprint is compared against the current fingerprint of the class. If they don’t match, then the class definition has changed after the object was written, and an exception is generated. Of course, in practice, classes do evolve, and it might be necessary for a program to read in older versions of objects. We discuss this later in the section entitled “Versioning” on page 54.

Here is how a class identifier is stored:

The flag byte is composed of three bit masks, defined in java.io.ObjectStreamConstants:

static final byte SC_WRITE_METHOD = 1;
   // class has writeObject method that writes additional data
static final byte SC_SERIALIZABLE = 2;
   // class implements Serializable interface
static final byte SC_EXTERNALIZABLE = 4;
   // class implements Externalizable interface

We discuss the Externalizable interface later in this chapter. Externalizable classes supply custom read and write methods that take over the output of their instance fields. The classes that we write implement the Serializable interface and will have a flag value of 02. The serializable java.util.Date class defines its own readObject/writeObject methods and has a flag of 03.

Each data field descriptor has the format:

The type code is one of the following:

When the type code is L, the field name is followed by the field type. Class and field name strings do not start with the string code 74, but field types do. Field types use a slightly different encoding of their names, namely, the format used by native methods.

For example, the salary field of the Employee class is encoded as:

D 00 06 salary

Here is the complete class descriptor of the Employee class:

These descriptors are fairly long. If the same class descriptor is needed again in the file, an abbreviated form is used:

The serial number refers to the previous explicit class descriptor. We discuss the numbering scheme later.

An object is stored as

For example, here is how an Employee object is stored:

As you can see, the data file contains enough information to restore the Employee object.

Arrays are saved in the following format:

The array class name in the class descriptor is in the same format as that used by native methods (which is slightly different from the class name used by class names in other class descriptors). In this format, class names start with an L and end with a semicolon.

For example, an array of three Employee objects starts out like this:

Note that the fingerprint for an array of Employee objects is different from a fingerprint of the Employee class itself.

All objects (including arrays and strings) and all class descriptors are given serial numbers as they are saved in the output file. The numbers start at 00 7E 00 00.

We already saw that a full class descriptor for any given class occurs only once. Subsequent descriptors refer to it. For example, in our previous example, a repeated reference to the Date class was coded as

71 00 7E 00 08

The same mechanism is used for objects. If a reference to a previously saved object is written, it is saved in exactly the same way; that is, 71 followed by the serial number. It is always clear from the context whether the particular serial reference denotes a class descriptor or an object.

Finally, a null reference is stored as

70

Here is the commented output of the ObjectRefTest program of the preceding section. If you like, run the program, look at a hex dump of its data file employee.dat, and compare it with the commented listing. The important lines toward the end of the output show the reference to a previously saved object.

Of course, studying these codes can be about as exciting as reading the average phone book. It is not important to know the exact file format (unless you are trying to create an evil effect by modifying the data), but it is still instructive to know that the object stream contains a detailed description of all the objects that it contains, with sufficient detail to allow reconstruction of both objects and arrays of objects.

What you should remember is this:

Certain data fields should never be serialized, for example, integer values that store file handles or handles of windows that are only meaningful to native methods. Such information is guaranteed to be useless when you reload an object at a later time or transport it to a different machine. In fact, improper values for such fields can actually cause native methods to crash. Java has an easy mechanism to prevent such fields from ever being serialized. Mark them with the keyword transient. You also need to tag fields as transient if they belong to nonserializable classes. Transient fields are always skipped when objects are serialized.

The serialization mechanism provides a way for individual classes to add validation or any other desired action to the default read and write behavior. A serializable class can define methods with the signature

private void readObject(ObjectInputStream in)
   throws IOException, ClassNotFoundException;
private void writeObject(ObjectOutputStream out)
   throws IOException;

Then, the data fields are no longer automatically serialized, and these methods are called instead.

Here is a typical example. A number of classes in the java.awt.geom package, such as Point2D.Double, are not serializable. Now suppose you want to serialize a class LabeledPoint that stores a String and a Point2D.Double. First, you need to mark the Point2D.Double field as transient to avoid a NotSerializableException.

public class LabeledPoint implements Serializable
{
   . . .
   private String label;
   private transient Point2D.Double point;
}

In the writeObject method, we first write the object descriptor and the String field, state, by calling the defaultWriteObject method. This is a special method of the ObjectOutputStream class that can only be called from within a writeObject method of a serializable class. Then we write the point coordinates, using the standard DataOutput calls.

private void writeObject(ObjectOutputStream out)
   throws IOException
{
   out.defaultWriteObject();
   out.writeDouble(point.getX());
   out.writeDouble(point.getY());
}

In the readObject method, we reverse the process:

private void readObject(ObjectInputStream in)
   throws IOException
{
   in.defaultReadObject();
   double x = in.readDouble();
   double y = in.readDouble();
   point = new Point2D.Double(x, y);
}

Another example is the java.util.Date class that supplies its own readObject and writeObject methods. These methods write the date as a number of milliseconds from the epoch (January 1, 1970, midnight UTC). The Date class has a complex internal representation that stores both a Calendar object and a millisecond count to optimize lookups. The state of the Calendar is redundant and does not have to be saved.

The readObject and writeObject methods only need to save and load their data fields. They should not concern themselves with superclass data or any other class information.

Rather than letting the serialization mechanism save and restore object data, a class can define its own mechanism. To do this, a class must implement the Externalizable interface. This in turn requires it to define two methods:

public void readExternal(ObjectInputStream in)
  throws IOException, ClassNotFoundException;
public void writeExternal(ObjectOutputStream out)
  throws IOException;

Unlike the readObject and writeObject methods that were described in the preceding section, these methods are fully responsible for saving and restoring the entire object, including the superclass data. The serialization mechanism merely records the class of the object in the stream. When reading an externalizable object, the object stream creates an object with the default constructor and then calls the readExternal method. Here is how you can implement these methods for the Employee class:

public void readExternal(ObjectInput s)
   throws IOException
{
   name = s.readUTF();
   salary = s.readDouble();
   hireDay = new Date(s.readLong());
}

public void writeExternal(ObjectOutput s)
   throws IOException
{
  s.writeUTF(name);
  s.writeDouble(salary);
  s.writeLong(hireDay.getTime());
}

Tip

Serialization is somewhat slow because the virtual machine must discover the structure of each object. If you are concerned about performance and if you read and write a large number of objects of a particular class, you should investigate the use of the Externalizable interface. The tech tip http://java.sun.com/developer/TechTips/2000/tt0425.html demonstrates that in the case of an employee class, using external reading and writing was about 35 to 40 percent faster than the default serialization.

Caution

Unlike the readObject and writeObject methods, which are private and can only be called by the serialization mechanism, the readExternal and writeExternal methods are public. In particular, readExternal potentially permits modification of the state of an existing object.

You have to pay particular attention when serializing and deserializing objects that are assumed to be unique. This commonly happens when you are implementing singletons and typesafe enumerations.

If you use the enum construct of Java SE 5.0, then you need not worry about serialization—it just works. However, suppose you maintain legacy code that contains an enumerated type such as

public class Orientation
{
   public static final Orientation HORIZONTAL = new Orientation(1);
   public static final Orientation VERTICAL  = new Orientation(2);
   private Orientation(int v) { value = v; }
   private int value;
}

This idiom was common before enumerations were added to the Java language. Note that the constructor is private. Thus, no objects can be created beyond Orientation.HORIZONTAL and Orientation.VERTICAL. In particular, you can use the == operator to test for object equality:

if (orientation == Orientation.HORIZONTAL) . . .

There is an important twist that you need to remember when a typesafe enumeration implements the Serializable interface. The default serialization mechanism is not appropriate. Suppose we write a value of type Orientation and read it in again:

Orientation original = Orientation.HORIZONTAL;
ObjectOutputStream out = . . .;
out.write(value);
out.close();
ObjectInputStream in = . . .;
Orientation saved = (Orientation) in.read();

Now the test

if (saved == Orientation.HORIZONTAL) . . .

will fail. In fact, the saved value is a completely new object of the Orientation type and not equal to any of the predefined constants. Even though the constructor is private, the serialization mechanism can create new objects!

To solve this problem, you need to define another special serialization method, called readResolve. If the readResolve method is defined, it is called after the object is deserialized. It must return an object that then becomes the return value of the readObject method. In our case, the readResolve method will inspect the value field and return the appropriate enumerated constant:

protected Object readResolve() throws ObjectStreamException
{
   if (value == 1) return Orientation.HORIZONTAL;
   if (value == 2) return Orientation.VERTICAL;
   return null; // this shouldn't happen
}

Remember to add a readResolve method to all typesafe enumerations in your legacy code and to all classes that follow the singleton design pattern.

If you use serialization to save objects, you will need to consider what happens when your program evolves. Can version 1.1 read the old files? Can the users who still use 1.0 read the files that the new version is now producing? Clearly, it would be desirable if object files could cope with the evolution of classes.

At first glance it seems that this would not be possible. When a class definition changes in any way, then its SHA fingerprint also changes, and you know that object streams will refuse to read in objects with different fingerprints. However, a class can indicate that it is compatible with an earlier version of itself. To do this, you must first obtain the fingerprint of the earlier version of the class. You use the stand-alone serialver program that is part of the JDK to obtain this number. For example, running

serialver Employee

prints

Employee: static final long serialVersionUID = -1814239825517340645L;

If you start the serialver program with the -show option, then the program brings up a graphical dialog box (see Figure 1-8).

Figure 1-8. The graphical version of the serialver program

All later versions of the class must define the serialVersionUID constant to the same fingerprint as the original.

class Employee implements Serializable // version 1.1
{
   . . .
   public static final long serialVersionUID = -1814239825517340645L;
}

When a class has a static data member named serialVersionUID, it will not compute the fingerprint manually but instead will use that value.

Once that static data member has been placed inside a class, the serialization system is now willing to read in different versions of objects of that class.

If only the methods of the class change, there is no problem with reading the new object data. However, if data fields change, then you may have problems. For example, the old file object may have more or fewer data fields than the one in the program, or the types of the data fields may be different. In that case, the object stream makes an effort to convert the stream object to the current version of the class.

The object stream compares the data fields of the current version of the class with the data fields of the version in the stream. Of course, the object stream considers only the nontransient and nonstatic data fields. If two fields have matching names but different types, then the object stream makes no effort to convert one type to the other—the objects are incompatible. If the object in the stream has data fields that are not present in the current version, then the object stream ignores the additional data. If the current version has data fields that are not present in the streamed object, the added fields are set to their default (null for objects, zero for numbers, and false for boolean values).

Here is an example. Suppose we have saved a number of employee records on disk, using the original version (1.0) of the class. Now we change the Employee class to version 2.0 by adding a data field called department. Figure 1-9 shows what happens when a 1.0 object is read into a program that uses 2.0 objects. The department field is set to null. Figure 1-10 shows the opposite scenario: A program using 1.0 objects reads a 2.0 object. The additional department field is ignored.

Figure 1-9. Reading an object with fewer data fields

Figure 1-10. Reading an object with more data fields

Is this process safe? It depends. Dropping a data field seems harmless—the recipient still has all the data that it knew how to manipulate. Setting a data field to null might not be so safe. Many classes work hard to initialize all data fields in all constructors to non-null values, so that the methods don’t have to be prepared to handle null data. It is up to the class designer to implement additional code in the readObject method to fix version incompatibilities or to make sure the methods are robust enough to handle null data.

There is an amusing use for the serialization mechanism: It gives you an easy way to clone an object provided the class is serializable. Simply serialize it to an output stream and then read it back in. The result is a new object that is a deep copy of the existing object. You don’t have to write the object to a file—you can use a ByteArrayOutputStream to save the data into a byte array.

As Listing 1-5 shows, to get clone for free, simply extend the SerialCloneable class, and you are done.

You should be aware that this method, although clever, will usually be much slower than a clone method that explicitly constructs a new object and copies or clones the data fields.

 1. import java.io.*;
 2. import java.util.*;
 3.
 4. public class SerialCloneTest
 5. {
 6.    public static void main(String[] args)
 7.    {
 8.       Employee harry = new Employee("Harry Hacker", 35000, 1989, 10, 1);
 9.       // clone harry
10.       Employee harry2 = (Employee) harry.clone();
11.
12.       // mutate harry
13.       harry.raiseSalary(10);
14.
15.       // now harry and the clone are different
16.       System.out.println(harry);
17.       System.out.println(harry2);
18.    }
19. }
20.
21. /**
22.    A class whose clone method uses serialization.
23. */
24. class SerialCloneable implements Cloneable, Serializable
25. {
26.    public Object clone()
27.    {
28.       try
29.       {
30.          // save the object to a byte array
31.          ByteArrayOutputStream bout = new ByteArrayOutputStream();
32.          ObjectOutputStream out = new ObjectOutputStream(bout);
33.          out.writeObject(this);
34.          out.close();
35.
36.          // read a clone of the object from the byte array
37.          ByteArrayInputStream bin = new ByteArrayInputStream(bout.toByteArray());
38.          ObjectInputStream in = new ObjectInputStream(bin);
39.          Object ret = in.readObject();
40.          in.close();
41.
42.          return ret;
43.       }
44.       catch (Exception e)
45.       {
46.          return null;
47.       }
48.    }
49. }
50.
51. /**
52.    The familiar Employee class, redefined to extend the
53.    SerialCloneable class.
54. */
55. class Employee extends SerialCloneable
56. {
57.    public Employee(String n, double s, int year, int month, int day)
58.    {
59.       name = n;
60.       salary = s;
61.       GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day);
62.       hireDay = calendar.getTime();
63.    }
64.
65.    public String getName()
66.    {
67.       return name;
68.    }
69.
70.    public double getSalary()
71.    {
72.       return salary;
73.    }
74.
75.    public Date getHireDay()
76.    {
77.       return hireDay;
78.    }
79.
80.    public void raiseSalary(double byPercent)
81.    {
82.       double raise = salary * byPercent / 100;
83.       salary += raise;
84.    }
85.
86.    public String toString()
87.    {
88.       return getClass().getName()
89.          + "[name=" + name
90.          + ",salary=" + salary
91.          + ",hireDay=" + hireDay
92.          + "]";
93.    }
94.
95.    private String name;
96.    private double salary;
97.    private Date hireDay;
98. }

Most operating systems can take advantage of the virtual memory implementation to “map” a file, or a region of a file, into memory. Then the file can be accessed as if it were an in-memory array, which is much faster than the traditional file operations.

At the end of this section, you can find a program that computes the CRC32 checksum of a file, using traditional file input and a memory-mapped file. On one machine, we got the timing data shown in Table 1-6 when computing the checksum of the 37-Mbyte file rt.jar in the jre/lib directory of the JDK.

As you can see, on this particular machine, memory mapping is a bit faster than using buffered sequential input and dramatically faster than using a RandomAccessFile.

Of course, the exact values will differ greatly from one machine to another, but it is obvious that the performance gain can be substantial if you need to use random access. For sequential reading of files of moderate size, on the other hand, there is no reason to use memory mapping.

The java.nio package makes memory mapping quite simple. Here is what you do.

First, get a channel from the file. A channel is an abstraction for disk files that lets you access operating system features such as memory mapping, file locking, and fast data transfers between files. You get a channel by calling the getChannel method that has been added to the FileInputStream, FileOutputStream, and RandomAccessFile class.

FileInputStream in = new FileInputStream(. . .);
FileChannel channel = in.getChannel();

Then you get a MappedByteBuffer from the channel by calling the map method of the FileChannel class. You specify the area of the file that you want to map and a mapping mode. Three modes are supported:

Once you have the buffer, you can read and write data, using the methods of the ByteBuffer class and the Buffer superclass.

Buffers support both sequential and random data access. A buffer has a position that is advanced by get and put operations. For example, you can sequentially traverse all bytes in the buffer as

while (buffer.hasRemaining())
{
   byte b = buffer.get();
   . . .
}

Alternatively, you can use random access:

for (int i = 0; i < buffer.limit(); i++)
{
   byte b = buffer.get(i);
   . . .
}

You can also read and write arrays of bytes with the methods

get(byte[] bytes)
get(byte[], int offset, int length)

Finally, there are methods

getInt
getLong
getShort
getChar
getFloat
getDouble

to read primitive type values that are stored as binary values in the file. As we already mentioned, Java uses big-endian ordering for binary data. However, if you need to process a file containing binary numbers in little-endian order, simply call

buffer.order(ByteOrder.LITTLE_ENDIAN);

To find out the current byte order of a buffer, call

ByteOrder b = buffer.order()

Caution

This pair of methods does not use the set/get naming convention.

To write numbers to a buffer, use one of the methods

putInt
putLong
putShort
putChar
putFloat
putDouble

Listing 1-7 computes the 32-bit cyclic redundancy checksum (CRC32) of a file. That quantity is a checksum that is often used to determine whether a file has been corrupted. Corruption of a file makes it very likely that the checksum has changed. The java.util.zip package contains a class CRC32 that computes the checksum of a sequence of bytes, using the following loop:

CRC32 crc = new CRC32();
while (more bytes)
   crc.update(next byte)
long checksum = crc.getValue();

Note

For a nice explanation of the CRC algorithm, see http://www.relisoft.com/Science/CrcMath.html.

The details of the CRC computation are not important. We just use it as an example of a useful file operation.

Run the program as

java NIOTest filename

 1. import java.io.*;
 2. import java.nio.*;
 3. import java.nio.channels.*;
 4. import java.util.zip.*;
 5.
 6. /**
 7.  * This program computes the CRC checksum of a file. <br>
 8.  * Usage: java NIOTest filename
 9.  * @version 1.01 2004-05-11
10.  * @author Cay Horstmann
11.  */
12. public class NIOTest
13. {
14.    public static long checksumInputStream(String filename) throws IOException
15.    {
16.       InputStream in = new FileInputStream(filename);
17.       CRC32 crc = new CRC32();
18.
19.       int c;
20.       while ((c = in.read()) != -1)
21.          crc.update(c);
22.       return crc.getValue();
23.    }
24.
25.    public static long checksumBufferedInputStream(String filename) throws IOException
26.    {
27.       InputStream in = new BufferedInputStream(new FileInputStream(filename));
28.       CRC32 crc = new CRC32();
29.
30.       int c;
31.       while ((c = in.read()) != -1)
32.          crc.update(c);
33.       return crc.getValue();
34.    }
35.
36.    public static long checksumRandomAccessFile(String filename) throws IOException
37.    {
38.       RandomAccessFile file = new RandomAccessFile(filename, "r");
39.       long length = file.length();
40.       CRC32 crc = new CRC32();
41.
42.       for (long p = 0; p < length; p++)
43.       {
44.          file.seek(p);
45.          int c = file.readByte();
46.          crc.update(c);
47.       }
48.       return crc.getValue();
49.    }
50.
51.    public static long checksumMappedFile(String filename) throws IOException
52.    {
53.       FileInputStream in = new FileInputStream(filename);
54.       FileChannel channel = in.getChannel();
55.
56.       CRC32 crc = new CRC32();
57.       int length = (int) channel.size();
58.       MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, length);
59.
60.       for (int p = 0; p < length; p++)
61.       {
62.          int c = buffer.get(p);
63.          crc.update(c);
64.       }
65.       return crc.getValue();
66.    }
67.
68.    public static void main(String[] args) throws IOException
69.    {
70.       System.out.println("Input Stream:");
71.       long start = System.currentTimeMillis();
72.       long crcValue = checksumInputStream(args[0]);
73.       long end = System.currentTimeMillis();
74.       System.out.println(Long.toHexString(crcValue));
75.       System.out.println((end - start) + " milliseconds");
76.
77.       System.out.println("Buffered Input Stream:");
78.       start = System.currentTimeMillis();
79.       crcValue = checksumBufferedInputStream(args[0]);
80.       end = System.currentTimeMillis();
81.       System.out.println(Long.toHexString(crcValue));
82.       System.out.println((end - start) + " milliseconds");
83.
84.       System.out.println("Random Access File:");
85.       start = System.currentTimeMillis();
86.       crcValue = checksumRandomAccessFile(args[0]);
87.       end = System.currentTimeMillis();
88.       System.out.println(Long.toHexString(crcValue));
89.       System.out.println((end - start) + " milliseconds");
90.
91.       System.out.println("Mapped File:");
92.       start = System.currentTimeMillis();
93.       crcValue = checksumMappedFile(args[0]);
94.       end = System.currentTimeMillis();
95.       System.out.println(Long.toHexString(crcValue));
96.       System.out.println((end - start) + " milliseconds");
97.    }
98. }

java.io.FileInputStream 1.0

• FileChannel getChannel() 1.4

  returns a channel for accessing this stream.

java.io.FileOutputStream 1.0

• FileChannel getChannel() 1.4

  returns a channel for accessing this stream.

java.io.RandomAccessFile 1.0

• FileChannel getChannel() 1.4

  returns a channel for accessing this file.

java.nio.channels.FileChannel 1.4

• MappedByteBuffer map(FileChannel.MapMode mode, long position, long size)

  maps a region of the file to memory.

  Parameters:	mode	One of the constants READ_ONLY, READ_WRITE, or PRIVATE in the FileChannel.MapMode class
  	position	The start of the mapped region
  	size	The size of the mapped region

java.nio.Buffer 1.4

• boolean hasRemaining()

  returns true if the current buffer position has not yet reached the buffer’s limit position.

• int limit()

  returns the limit position of the buffer; that is, the first position at which no more values are available.

java.nio.ByteBuffer 1.4

• byte get()

  gets a byte from the current position and advances the current position to the next byte.

• byte get(int index)

  gets a byte from the specified index.

• ByteBuffer put(byte b)

  puts a byte to the current position and advances the current position to the next byte. Returns a reference to this buffer.

• ByteBuffer put(int index, byte b)

  puts a byte at the specified index. Returns a reference to this buffer.

• ByteBuffer get(byte[] destination)

• ByteBuffer get(byte[] destination, int offset, int length)

  fills a byte array, or a region of a byte array, with bytes from the buffer, and advances the current position by the number of bytes read. If not enough bytes remain in the buffer, then no bytes are read, and a BufferUnderflowException is thrown. Returns a reference to this buffer.

  Parameters:	destination	The byte array to be filled
  	offset	The offset of the region to be filled
  	length	The length of the region to be filled

• ByteBuffer put(byte[] source)

• ByteBuffer put(byte[] source, int offset, int length)

  puts all bytes from a byte array, or the bytes from a region of a byte array, into the buffer, and advances the current position by the number of bytes read. If not enough bytes remain in the buffer, then no bytes are written, and a BufferOverflowException is thrown. Returns a reference to this buffer.

  Parameters:	source	The byte array to be written
  	offset	The offset of the region to be written
  	length	The length of the region to be written

• Xxx getXxx()

• Xxx getXxx(int index)

• ByteBuffer putXxx(xxx value)

• ByteBuffer putXxx(int index, xxx value)

  gets or puts a binary number. Xxx is one of Int, Long, Short, Char, Float, or Double.

• ByteBuffer order(ByteOrder order)

• ByteOrder order()

  sets or gets the byte order. The value for order is one of the constants BIG_ENDIAN or LITTLE_ENDIAN of the ByteOrder class.

When you use memory mapping, you make a single buffer that spans the entire file, or the area of the file in which you are interested. You can also use buffers to read and write more modest chunks of information.

In this section, we briefly describe the basic operations on Buffer objects. A buffer is an array of values of the same type. The Buffer class is an abstract class with concrete subclasses ByteBuffer, CharBuffer, DoubleBuffer, FloatBuffer, IntBuffer, LongBuffer, and ShortBuffer.

Note

The StringBuffer class is not related to these buffers.

In practice, you will most commonly use ByteBuffer and CharBuffer. As shown in Figure 1-11, a buffer has

Figure 1-11. A buffer

These values fulfill the condition

0 ≤ mark ≤ position ≤ limit ≤ capacity

The principal purpose for a buffer is a “write, then read” cycle. At the outset, the buffer’s position is 0 and the limit is the capacity. Keep calling put to add values to the buffer. When you run out of data or you reach the capacity, it is time to switch to reading.

Call flip to set the limit to the current position and the position to 0. Now keep calling get while the remaining method (which returns limit - position) is positive. When you have read all values in the buffer, call clear to prepare the buffer for the next writing cycle. The clear method resets the position to 0 and the limit to the capacity.

If you want to reread the buffer, use rewind or mark/reset—see the API notes for details.

java.nio.Buffer 1.4

• Buffer clear()

  prepares this buffer for writing by setting the position to 0 and the limit to the capacity; returns this.

• Buffer flip()

  prepares this buffer for reading by setting the limit to the position and the position to 0; returns this.

• Buffer rewind()

  prepares this buffer for rereading the same values by setting the position to 0 and leaving the limit unchanged; returns this.

• Buffer mark()

  sets the mark of this buffer to the position; returns this.

• Buffer reset()

  sets the position of this buffer to the mark, thus allowing the marked portion to be read or written again; returns this.

• int remaining()

  returns the remaining number of readable or writable values; that is, the difference between limit and position.

• int position()

  returns the position of this buffer.

• int capacity()

  returns the capacity of this buffer.

java.nio.CharBuffer 1.4

• char get()

• CharBuffer get(char[] destination)

• CharBuffer get(char[] destination, int offset, int length)

  gets one char value, or a range of char values, starting at the buffer’s position and moving the position past the characters that were read. The last two methods return this.

• CharBuffer put(char c)

• CharBuffer put(char[] source)

• CharBuffer put(char[] source, int offset, int length)

• CharBuffer put(String source)

• CharBuffer put(CharBuffer source)

  puts one char value, or a range of char values, starting at the buffer’s position and advancing the position past the characters that were written. When reading from a CharBuffer, all remaining characters are read. All methods return this.

• CharBuffer read(CharBuffer destination)

  gets char values from this buffer and puts them into the destination until the destination’s limit is reached. Returns this.

Consider a situation in which multiple simultaneously executing programs need to modify the same file. Clearly, the programs need to communicate in some way, or the file can easily become damaged.

File locks control access to a file or a range of bytes within a file. However, file locking varies greatly among operating systems, which explains why file locking capabilities were absent from prior versions of the JDK.

File locking is not all that common in application programs. Many applications use a database for data storage, and the database has mechanisms for resolving concurrent access. If you store information in flat files and are worried about concurrent access, you might find it simpler to start using a database rather than designing complex file locking schemes.

Still, there are situations in which file locking is essential. Suppose your application saves a configuration file with user preferences. If a user invokes two instances of the application, it could happen that both of them want to write the configuration file at the same time. In that situation, the first instance should lock the file. When the second instance finds the file locked, it can decide to wait until the file is unlocked or simply skip the writing process.

To lock a file, call either the lock or tryLock method of the FileChannel class:

FileLock lock = channel.lock();

or

FileLock lock = channel.tryLock();

The first call blocks until the lock becomes available. The second call returns immediately, either with the lock or null if the lock is not available. The file remains locked until the channel is closed or the release method is invoked on the lock.

You can also lock a portion of the file with the call

FileLock lock(long start, long size, boolean exclusive)

or

FileLock tryLock(long start, long size, boolean exclusive)

The exclusive flag is true to lock the file for both reading and writing. It is false for a shared lock, which allows multiple processes to read from the file, while preventing any process from acquiring an exclusive lock. Not all operating systems support shared locks. You may get an exclusive lock even if you just asked for a shared one. Call the isShared method of the FileLock class to find out which kind you have.

Note

If you lock the tail portion of a file and the file subsequently grows beyond the locked portion, the additional area is not locked. To lock all bytes, use a size of Long.MAX_VALUE.

Keep in mind that file locking is system dependent. Here are some points to watch for:

java.nio.channels.FileChannel 1.4

• FileLock lock()

  acquires an exclusive lock on the entire file. This method blocks until the lock is acquired.

• FileLock tryLock()

  acquires an exclusive lock on the entire file, or returns null if the lock cannot be acquired.

• FileLock lock(long position, long size, boolean shared)

• FileLock tryLock(long position, long size, boolean shared)

  acquires a lock on a region of the file. The first method blocks until the lock is acquired, and the second method returns null if the lock cannot be acquired.

  Parameters:	position	The start of the region to be locked
  	size	The size of the region to be locked
  	shared	true for a shared lock, false for an exclusive lock

java.nio.channels.FileLock 1.4

• void release()

  releases this lock.