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 can block a thread until the byte is actually read or written. This means that if the stream cannot immediately be read from or written to (usually because of a busy network connection), Java suspends the thread containing this call. This gives other threads the chance to do useful work while the method is waiting for the stream to again become available. (We discuss threads in depth in Volume 2.)

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 ever 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 may 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 may 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, Java programmers rarely use them because programs rarely need to read and write streams of bytes. The data that you are interested in probably contain numbers, strings, and objects.

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 low byte-level.

java.io.InputStream 1.0

java.io.OutputStream 1.0

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 current directory for a file named "employee.dat".

Caution

Because the backslash character is the escape character in Java strings, be sure to use \ for Windows-style path names ("C:\Windows\win.ini"). In Windows, you can also use a single forward slash ("C:/Windows/win.ini") because most Windows file handling system calls will interpret forward slashes as file separators. However, this is not recommended—the behavior of the Windows system functions is subject to change, and on other operating systems, the file separator may yet be different. Instead, for portable programs, you should use the correct file separator character. It is stored in the constant string File.separator.

You can also use a File object (see page 684 for more on file objects):

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

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();

Tip

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

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 into what are often called filtered streams by feeding an existing stream to the constructor of another stream. 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();

It is important to keep in mind that the data input stream that we created with the above code does not correspond to a new disk file. The newly created stream still accesses the data from the file attached to the file input stream, but the point is that it now has a more capable interface.

If you look at Figure 12–1 again, you can see the classes FilterInputStream and FilterOutputStream. You combine their subclasses into a new filtered stream to construct the streams you want. For example, by default, streams are not buffered. That is, every call to read contacts the operating system to ask it to dole out yet another byte. If you want buffering and the data input methods for a file named employee.dat in the current directory, 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. Regardless of the ugliness of the above code, it is necessary: you must be prepared to continue layering stream constructors until you have access to the functionality you want.

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 layering 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 12–4).

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

Figure 12–4. A sequence of filtered streams

(See the section on ZIP file streams starting on page 643 for more on Java’s ability to handle ZIP files.)

All in all, apart from the rather monstrous constructors that are needed to layer streams, the ability to mix and match streams is a very useful feature of Java!

java.io.FileInputStream 1.0

java.io.FileOutputStream 1.0

java.io.BufferedInputStream 1.0

java.io.BufferedOutputStream 1.0

java.io.PushbackInputStream 1.0

You often need to write the result of a computation or read one back. The data streams support methods for reading back all the basic Java types. To write a number, character, Boolean value, or string, use one of the following methods of the DataOutput interface:

writeChars
writeByte
writeInt
writeShort
writeLong
writeFloat
writeDouble
writeChar
writeBoolean
writeUTF

For example, writeInt always writes an integer as a 4-byte binary quantity regardless of the number of digits, and writeDouble always writes a double as an 8-byte binary quantity. The resulting output is not humanly readable, but the space needed will be the same for each value of a given type and reading it back in will be faster. (See the section on the PrintWriter class later in this chapter for how to output numbers as human-readable text.)

Note

There are two different methods of storing integers and floating-point numbers in memory, depending on the platform you are using. Suppose, for example, you are working with a 4-byte int, say the decimal number 1234, or 4D2 in hexadecimal (1234 = 4 x 256 + 13 x 16 + 2). This can be stored in such a way that the first of the 4 bytes in memory holds the most significant byte (MSB) of the value: 00 00 04 D2. This is the so-called big-endian method. Or we can start with the least significant byte (LSB) first: D2 04 00 00. This is called, naturally enough, the little-endian method. For example, the SPARC uses big-endian; the Pentium, little-endian. This can lead to problems. When a C or C++ file is saved, the data are saved exactly as the processor stores them. That makes it challenging to move even the simplest data files from one platform to another. In Java, all values are written in the big-endian fashion, regardless of the processor. That makes Java data files platform independent.

The writeUTF method writes string data by using a modified version of 8-bit Unicode Transformation Format. Instead of simply using the standard UTF-8 encoding (which is shown in Table 12–1), character strings are first represented in UTF-16 (see Table 12–2) and then the result is encoded using the UTF-8 rules. The modified encoding is different for characters with code higher than 0xFFFF. It is used for backwards compatibility with virtual machines that were built when Unicode had not yet grown beyond 16 bits.

Because nobody else uses this modification of UTF-8, you should only use the writeUTF method to write strings that are intended for a Java virtual machine; for example, if you write a program that generates bytecodes. Use the writeChars method for other purposes.

Note

See RFC 2279 (http://ietf.org/rfc/rfc2279.txt) and RFC 2781 (http://ietf.org/rfc/rfc2781.txt) for definitions of UTF-8 and UTF-16.

To read the data back in, use the following methods:

Note

The binary data format is compact and platform independent. Except for the UTF strings, it is also suited to random access. The major drawback is that binary files are not readable by humans.

java.io.DataInput 1.0

java.io.DataOutput 1.0

The RandomAccessFile stream class lets you find or write data anywhere in a file. It implements both the DataInput and DataOutput interfaces. 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 also has a file pointer setting that comes with it. The file pointer always indicates the position of the next record 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.

To read from a random-access file, you use the same methods—such as readInt and readChar—as for DataInputStream objects. That is no accident. These methods are actually defined in the DataInput interface that both DataInputStream and RandomAccessFile implement.

Similarly, to write a random-access file, you use the same writeInt and writeChar methods as in the DataOutputStream class. These methods are defined in the DataOutput interface that is common to both classes.

The advantage of having the RandomAccessFile class implement both DataInput and DataOutput is that this lets you use or write methods whose argument types are the DataInput and DataOutput interfaces.

class Employee
{  . . .
   read(DataInput in) { . . . }
   write(DataOutput out) { . . . }
}

Note that the read method can handle either a DataInputStream or a RandomAccessFile object because both of these classes implement the DataInput interface. The same is true for the write method.

java.io.RandomAccessFile 1.0

In the last section, we discussed binary input and output. While binary I/O is fast and efficient, it is not easily readable by humans. In this section, we will focus on text I/O. For example, if the integer 1234 is saved in binary, it is written as the sequence of bytes 00 00 04 D2 (in hexadecimal notation). In text format, it is saved as the string "1234".

Unfortunately, doing this in Java requires a bit of work, because, as you know, Java uses Unicode characters. That is, the character encoding for the string "1234" really is 00 31 00 32 00 33 00 34 (in hex). However, at the present time most environments in which your Java programs will run use their own character encoding. This may be a single-byte, double-byte, or variable-byte scheme. For example, if you use Windows, the string would be written in ASCII, as 31 32 33 34, without the extra zero bytes. If the Unicode encoding were written into a text file, then it would be quite unlikely that the resulting file would be humanly readable with the tools of the host environment. To overcome this problem, Java has a set of stream filters that bridges the gap between Unicode-encoded strings and the character encoding used by the local operating system. All of these classes descend from the abstract Reader and Writer classes, and the names are reminiscent of the ones used for binary data. For example, the InputStreamReader class turns an input stream that contains bytes in a particular character encoding into a reader that emits Unicode characters. Similarly, the OutputStreamWriter class turns a stream of Unicode characters into a stream of bytes in a particular character encoding.

For example, here is how you make an input reader that reads keystrokes from the console and automatically converts them to Unicode.

InputStreamReader in = new InputStreamReader(System.in);

This input stream reader assumes the normal character encoding used by the host system. For example, under Windows, it uses the ISO 8859-1 encoding (also known as ISO Latin-1 or, among Windows programmers, as “ANSI code”). You can choose a different encoding by specifying it in the constructor for the InputStreamReader. This takes the form

InputStreamReader(InputStream, String)

where the string describes the encoding scheme that you want to use. For example,

InputStreamReader in = new InputStreamReader(
   new FileInputStream("kremlin.dat"), "ISO8859_5");

The next section has more information on character sets.

Because it is so common to want to attach a reader or writer to a file, a pair of convenience classes, FileReader and FileWriter, is provided for this purpose. For example, the writer definition

FileWriter out = new FileWriter("output.txt");

is equivalent to

FileWriter out = new FileWriter(new FileOutputStream("output.txt"));

In the past, international character sets have been handled rather unsystematically throughout the Java library. The java.nio package—introduced in JDK 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 JDK 1.3. 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

Character set names are case insensitive.

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");

The aliases method returns a Set object of the aliases. A Set is a collection that we discuss in Volume 2; here is the code to iterate through the set elements:

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

Note

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

International versions of Java support many more encodings. There is even a mechanism for adding additional character set providers—see the JDK documentation for details. To find out which character sets are available in a particular implementation, call the static availableCharsets method. It returns a SortedMap, another collection class. Use this code to find out the names of all available character sets:

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

Table 12–3 lists the character encodings that every Java implementation is required to have. Table 12–4 lists the encoding schemes that the JDK installs by default. The character sets in Tables 12–5 and 12–6 are installed only on operating systems that use non-European languages. The encoding schemes in Table 12–6 are supplied for compatibility with previous versions of the JDK.

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

java.nio.ByteBuffer 1.4

java.nio.CharBuffer

For text output, you want to use a PrintWriter. A print writer can print strings and numbers in text format. Just as a DataOutputStream has useful output methods but no destination, a PrintWriter must be combined with a destination writer.

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

You can also combine a print writer with a destination (output) stream.

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

The PrintWriter(OutputStream) constructor automatically adds an OutputStreamWriter to convert Unicode characters to bytes in the stream.

To write to a print writer, you use the same print and println 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.

Note

Java veterans may 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. Conversely, the readLine method of the DataInputStream turned ASCII to Unicode by setting the top byte to 0. 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 send raw bytes to them with the write(int) and write(byte[]) methods.

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

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

The println method automatically adds the correct end-of-line character for the target system (" " on Windows, " " on UNIX, " " on Macs) 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, boolean) constructor and passing the appropriate Boolean as the second argument.

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

You cannot write raw bytes to a PrintWriter. Print writers are designed for text output only.

java.io.PrintWriter 1.1

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 have used extensively. However, before JDK 5.0, the only game in town for processing text input was the BufferedReader method—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:

The FileReader class already converts bytes to Unicode characters. For other input sources, you need to use the InputStreamReader—unlike the PrintWriter, the InputStreamReader has no automatic convenience method to bridge the gap between bytes and Unicode characters.

BufferedReader in2 = new BufferedReader(new InputStreamReader(System.in));
BufferedReader in3 = new BufferedReader(new InputStreamReader(url.openStream()));

To read numbers from text input, you need to read a string first and then convert it.

String s = in.readLine();
double x = Double.parseDouble(s);

That works if there is a single number on each line. Otherwise, you must work harder and break up the input string, for example, by using the StringTokenizer utility class. We see an example of this later in this chapter.

Tip

Java has StringReader and StringWriter classes that allow you to treat a string as if it were a data stream. This can be quite convenient if you want to use the same code to parse both strings and data from a stream.

In this section, you learn how to store an array of Employee records in the time-honored delimited format. This means that 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.

Note

Especially on UNIX systems, an amazing number of files are stored in exactly this format. We have seen entire employee databases with thousands of records in this format, queried with nothing more than the UNIX awk, sort, and join utilities. (In the PC world, where desktop database programs are available at low cost, this kind of ad hoc storage is much less common.)

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 . Finally, in keeping with the idea that we want the class to be responsible for responding to messages, we add a method, writeData, 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. This is the topic of the next section, in which we use a utility class supplied with Java to make our job easier.

When reading a line of input, we get a single long string. We want to split it into individual strings. This means finding the | delimiters and then separating out the individual pieces, that is, the sequence of characters up to the next delimiter. (These are usually called tokens.) The StringTokenizer class in java.util is designed for exactly this purpose. It gives you an easy way to break up a large string that contains delimited text. The idea is that a string tokenizer object attaches to a string. When you construct the tokenizer object, you specify which characters are the delimiters. For example, we need to use

StringTokenizer tokenizer = new StringTokenizer(line, "|");

You can specify multiple delimiters in the string, for example:

StringTokenizer tokenizer = new StringTokenizer(line, "|,;");

This means that any of the characters in the string can serve as delimiters.

If you don’t specify a delimiter set, the default is " ", that is, all whitespace characters (space, tab, newline, and carriage return)

Once you have constructed a string tokenizer, you can use its methods to quickly extract the tokens from the string. The nextToken method returns the next unread token. The hasMoreTokens method returns true if more tokens are available. The following loop processes all tokens:

Note

An alternative to the StringTokenizer is the split method of the String class. The call line.split("[|,;]") returns a String[] array consisting of all tokens, using the delimiters inside the brackets. You can use any regular expression to describe delimiters—we will discuss regular expression on page 698.

java.util.StringTokenizer 1.0

Reading in an Employee record is simple. We simply read in a line of input with the readLine method of the BufferedReader class. Here is the code needed to read one record into a string.

BufferedReader in = new BufferedReader(new FileReader("employee.dat"));
. . .
String line = in.readLine();

Next, we need to extract the individual tokens. When we do this, we end up with strings, so we need to convert them to numbers.

Just as with the writeData method, we add a readData method of the Employee class. When you call

e.readData(in);

this method overwrites the previous contents of e. Note that the method may throw an IOException if the readLine method throws that exception. This method can do nothing if an IOException occurs, so we just let it propagate up the call chain.

Here is the code for this method:

public void readData(BufferedReader in) throws IOException
{
   String s = in.readLine();
   StringTokenizer t = new StringTokenizer(s, "|");
   name = t.nextToken();
   salary = Double.parseDouble(t.nextToken());
   int y = Integer.parseInt(t.nextToken());
   int m = Integer.parseInt(t.nextToken());
   int d = Integer.parseInt(t.nextToken());
   GregorianCalendar calendar = new GregorianCalendar(y, m - 1, d);
      // GregorianCalendar uses 0 = January
   hireDay = calendar.getTime();
}

Finally, in the code for a program that tests these methods, 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, as illustrated in Example 12–2.

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

When you process input, you often need to construct strings from individual characters or Unicode code units. It would be inefficient to use string concatenation for this purpose. Every time you append characters to a string, the string object needs to find new memory to hold the larger string: this is time consuming. Appending even more characters means the string needs to be relocated again and again. Using the StringBuilder class avoids this problem.

In contrast, a StringBuilder works much like an ArrayList. It manages a char[] array that can grow and shrink on demand. You can append, insert, or remove code units until the string builder holds the desired string. Then you use the toString method to convert the contents to an actual String object.

Note

The StringBuilder class was introduced in JDK 5.0. Its predecessor, StringBuffer, is slightly less efficient, but it allows multiple threads to add or remove characters. If all string editing happens in a single thread, you should use StringBuilder instead. The APIs of both classes are identical.

The following API notes contain the most important methods for the StringBuilder and StringBuffer classes.

java.lang.StringBuilder 5.0

java.lang.StringBuffer 1.0

If you have a large number of employee records of variable length, the storage technique used in the preceding section suffers from one limitation: it is not possible to read a record in the middle of the file without first reading all records that come before it. In this section, we make all records the same length. This lets us implement a random-access method for reading back the information by using the RandomAccessFile class that you saw earlier—we can use this to get at any record in the same amount of time.

We will store the numbers in the instance fields in our classes in a binary format. We do that with the writeInt and writeDouble methods of the DataOutput interface. (As we mentioned earlier, this is the common interface of the DataOutputStream and the RandomAccessFile classes.)

However, because the size of each record must remain constant, we need to make all the strings the same size when we save them. The variable-size UTF format does not do this, and the rest of the Java library provides no convenient means of accomplishing this. We need to write a bit of code to implement two helper methods to make the strings the same size. We will call the methods writeFixedString and readFixedString. These methods read and write Unicode strings that always have the same length.

The writeFixedString method takes the parameter size. Then, it 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.) Here is the code for the writeFixedString method:

static void writeFixedString(String s, int size, DataOutput out)
   throws IOException
{
   int i;
   for (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 should skip past the remaining zero values in the input field. For added efficiency, this method uses the StringBuilder class to read in a string.

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();
}

Note

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();
}

In our example, each employee record is 100 bytes long because we specified that the name field would always be written using 40 characters. This gives us a breakdown as indicated in the following:

As an example, suppose you want to position the file pointer to the third record. You can use the following version of the seek method:

long n = 3;
int RECORD_SIZE = 100;
in.seek((n - 1) * RECORD_SIZE);

Then you can read a record:

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 int nbytes = in.length(); // length in bytes
int nrecords = (int) (nbytes / RECORD_SIZE);

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

To save object data, you first need to open an ObjectOutputStream object:

ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream("employee.dat"));

Now, to save an object, you simply use the writeObject method of the ObjectOutputStream class as in the following fragment:

Employee harry = new Employee("Harry Hacker", 50000, 1989, 10, 1);
Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15);
out.writeObject(harry);
out.writeObject(boss);

To read the objects back in, first get an ObjectInputStream object:

ObjectInputStream in = new ObjectInputStream(new FileInputStream("employee.dat"));

Then, retrieve the objects in the same order in which they were written, using the readObject method.

Employee e1 = (Employee) in.readObject();
Employee e2 = (Employee) in.readObject();

When reading back objects, you must carefully keep track of the number of objects that were saved, their order, and their types. Each call to readObject reads in another object of the type Object. You therefore will need to cast it to its correct type.

If you don’t need the exact type or you don’t remember it, then you can cast it to any superclass or even leave it as type Object. For example, e2 is an Employee object variable even though it actually refers to a Manager object. If you need to dynamically query the type of the object, you can use the getClass method that we described in Chapter 5.

You can write and read only objects with the writeObject/readObject methods. For primitive type values, you use methods such as writeInt/readInt or writeDouble/readDouble. (The object stream classes implement the DataInput/DataOutput interfaces.) Of course, numbers inside objects (such as the salary field of an Employee object) are saved and restored automatically. Recall that, in Java, strings and arrays are objects and can, therefore, be processed with the writeObject/readObject methods.

There is, however, one change you need to make to any class that you want to save and restore in an object stream. The class must implement the Serializable interface:

class Employee implements Serializable { . . . }

The Serializable interface has no methods, so you don’t need to change your classes in any way. In this regard, it is similar to the Cloneable interface that we also discussed in Chapter 6. However, to make a class cloneable, you still had to override the clone method of the Object class. To make a class serializable, you do not need to do anything else.

Example 12–4 is a test program that writes an array containing two employees and one manager to disk and then restores it. Writing an array is done with a single operation:

Employee[] staff = new Employee[3];
. . .
out.writeObject(staff);

Similarly, reading in the result is done with a single operation. However, we must apply a cast to the return value of the readObject method:

Employee[] newStaff = (Employee[]) in.readObject();

Once the information is restored, we print each employee because you can easily distinguish employee and manager objects by their different toString results. This should convince you that we did restore the correct types.

  1. import java.io.*;
  2. import java.util.*;
  3.
  4. class ObjectFileTest
  5. {
  6.    public static void main(String[] args)
  7.    {
  8.       Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15);
  9.       boss.setBonus(5000);
 10.
 11.       Employee[] staff = new Employee[3];
 12.
 13.       staff[0] = boss;
 14.       staff[1] = new Employee("Harry Hacker", 50000, 1989, 10, 1);
 15.       staff[2] = new Employee("Tony Tester", 40000, 1990, 3, 15);
 16.
 17.       try
 18.       {
 19.          // save all employee records to the file employee.dat
 20.          ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream
("employee.dat"));
 21.          out.writeObject(staff);
 22.          out.close();
 23.
 24.          // retrieve all records into a new array
 25.          ObjectInputStream in =  new ObjectInputStream(new FileInputStream("employee
.dat"));
 26.          Employee[] newStaff = (Employee[]) in.readObject();
 27.          in.close();
 28.
 29.          // print the newly read employee records
 30.          for (Employee e : newStaff)
 31.             System.out.println(e);
 32.       }
 33.       catch (Exception e)
 34.       {
 35.          e.printStackTrace();
 36.       }
 37.    }
 38. }
 39.
 40. class Employee implements Serializable
 41. {
 42.    public Employee() {}
 43.
 44.    public Employee(String n, double s, int year, int month, int day)
 45.    {
 46.       name = n;
 47.       salary = s;
 48.       GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day);
 49.       hireDay = calendar.getTime();
 50.    }
 51.
 52.    public String getName()
 53.    {
 54.       return name;
 55.    }
 56.
 57.    public double getSalary()
 58.    {
 59.       return salary;
 60.    }
 61.
 62.    public Date getHireDay()
 63.    {
 64.       return hireDay;
 65.    }
 66.
 67.    public void raiseSalary(double byPercent)
 68.    {
 69.       double raise = salary * byPercent / 100;
 70.       salary += raise;
 71.    }
 72.
 73.    public String toString()
 74.    {
 75.       return getClass().getName()
 76.          + "[name=" + name
 77.          + ",salary=" + salary
 78.          + ",hireDay=" + hireDay
 79.          + "]";
 80.    }
 81.
 82.    private String name;
 83.    private double salary;
 84.    private Date hireDay;
 85. }
 86.
 87. class Manager extends Employee
 88. {
 89.    /**
 90.       @param n the employee's name
 91.       @param s the salary
 92.       @param year the hire year
 93.       @param month the hire month
 94.       @param day the hire day
 95.    */
 96.    public Manager(String n, double s, int year, int month, int day)
 97.    {
 98.       super(n, s, year, month, day);
 99.       bonus = 0;
100.    }
101.
102.    public double getSalary()
103.    {
104.       double baseSalary = super.getSalary();
105.       return baseSalary + bonus;
106.    }
107.
108.    public void setBonus(double b)
109.    {
110.       bonus = b;
111.    }
112.
113.    public String toString()
114.    {
115.       return super.toString()
116.         + "[bonus=" + bonus
117.         + "]";
118.    }
119.
120.    private double bonus;
121. }

java.io.ObjectOutputStream 1.1

java.io.ObjectInputStream 1.1

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. We did this by looking at hex dumps of various saved object files. However, the details are somewhat technical, so 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

Java gets the fingerprint by

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. SHA is a U.S. standard, recommended by the National Institute for Science and Technology (NIST). (For more details on SHA, see, for example, Cryptography and Network Security: Principles and Practice, by William Stallings [Prentice Hall, 2002].) However, Java 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 in any way.

Java can then check the class fingerprint to protect us from the following scenario: An object is saved to a disk file. Later, the designer of the class makes a change, for example, by removing a data field. Then, the old disk file is read in again. Now the data layout on the disk no longer matches the data layout in memory. If the data were read back in its old form, it could corrupt memory. Java takes great care to make such memory corruption close to impossible. Hence, it checks, using the fingerprint, that the class definition has not changed when it restores an object. It does this by comparing the fingerprint on disk with the fingerprint of the current class.

Note

Technically, as long as the data layout of a class has not changed, it ought to be safe to read objects back in. But Java is conservative and checks that the methods have not changed either. (After all, the methods describe the meaning of the stored data.) Of course, in practice, classes do evolve, and it may be necessary for a program to read in older versions of objects. We discuss this later in the section entitled “Versioning” on page 679.

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 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. (See Volume 2 for 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, then 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.

Of course, studying these codes can be about as exciting as reading the average phone book. 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.

We now know how to save objects that contain numbers, strings, or other simple objects. However, there is one important situation that we still need to consider. What happens when one object is shared by several objects as part of its state?

To illustrate the problem, let us make a slight modification to the Manager class. Let’s assume that each manager has a secretary, implemented as an instance variable secretary of type Employee. (It would make sense to derive a class Secretary from Employee for this purpose, but we don’t do that here.)

class Manager extends Employee
{
   . . .
   private Employee secretary;
}

Having done this, you must keep in mind that the Manager object now contains a reference to the Employee object that describes the secretary, not a separate copy of the object.

In particular, two managers can share the same secretary, as is the case in Figure 12–6 and the following code:

harry = new Employee("Harry Hacker", . . .);
Manager carl = new Manager("Carl Cracker", . . .);
carl.setSecretary(harry);
Manager tony = new Manager("Tony Tester", . . .);
tony.setSecretary(harry);

Now, suppose we write the employee data to disk. What we don’t want is for the Manager to save its information according to the following logic:

Then, the data for harry would be saved three times. When reloaded, the objects would have the configuration shown in Figure 12–7.

Figure 12–7. Here, Harry is saved three times

This is not what we want. Suppose the secretary gets a raise. We would not want to hunt for all other copies of that object and apply the raise as well. We want to save and restore only one copy of the secretary. To do this, we must copy and restore the original references to the objects. In other words, we want the object layout on disk to be exactly like the object layout in memory. This is called persistence in object-oriented circles.

Of course, we cannot save and restore the memory addresses for the secretary objects. When an object is reloaded, it will likely occupy a completely different memory address than it originally did.

Figure 12–6. Two managers can share a mutual employee

Instead, Java uses a serialization approach. Hence, the name object serialization for this mechanism. Here is the algorithm:

When reading back the objects, simply reverse the procedure. For each object that you load, note its sequence number and remember where you put it in memory. When you encounter the tag “same as previously saved object with serial number x,” you look up where you put the object with serial number x and set the object reference to that memory address.

Note that the objects need not be saved in any particular order. Figure 12–9 shows what happens when a manager occurs first in the staff array.

Figure 12–9. Objects saved in random order

All of this sounds confusing, and it is. Fortunately, when object streams are used, the process is also completely automatic. Object streams assign the serial numbers and keep track of duplicate objects. The exact numbering scheme is slightly different from that used in the figures—see the next section.

Note

In this chapter, we use serialization to save a collection of objects to a disk file and retrieve it exactly as we stored it. Another very important application is the transmittal of a collection of objects across a network connection to another computer. Just as raw memory addresses are meaningless in a file, they are also meaningless when communicating with a different processor. Because serialization replaces memory addresses with serial numbers, it permits the transport of object collections from one machine to another. We study that use of serialization when discussing remote method invocation in Volume 2.

Example 12–5 is a program that saves and reloads a network of Employee and Manager objects (some of which share the same employee as a secretary). Note that the secretary object is unique after reloading—when newStaff[1] gets a raise, that is reflected in the secretary fields of the managers.

  1. import java.io.*;
  2. import java.util.*;
  3.
  4. class ObjectRefTest
  5. {
  6.    public static void main(String[] args)
  7.    {
  8.       Employee harry = new Employee("Harry Hacker", 50000, 1989, 10, 1);
  9.       Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15);
 10.       boss.setSecretary(harry);
 11.
 12.       Employee[] staff = new Employee[3];
 13.
 14.       staff[0] = boss;
 15.       staff[1] = harry;
 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.          ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream
("employee.dat"));
 22.          out.writeObject(staff);
 23.          out.close();
 24.
 25.          // retrieve all records into a new array
 26.          ObjectInputStream in =  new ObjectInputStream(new FileInputStream("employee
.dat"));
 27.          Employee[] newStaff = (Employee[]) in.readObject();
 28.          in.close();
 29.
 30.          // raise secretary's salary
 31.          newStaff[1].raiseSalary(10);
 32.
 33.          // print the newly read employee records
 34.          for (Employee e : newStaff)
 35.             System.out.println(e);
 36.       }
 37.       catch (Exception e)
 38.       {
 39.          e.printStackTrace();
 40.       }
 41.    }
 42. }
 43.
 44. class Employee implements Serializable
 45. {
 46.    public Employee() {}
 47.
 48.    public Employee(String n, double s, int year, int month, int day)
 49.    {
 50.       name = n;
 51.       salary = s;
 52.       GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day);
 53.       hireDay = calendar.getTime();
 54.    }
 55.
 56.    public String getName()
 57.    {
 58.       return name;
 59.    }
 60.
 61.    public double getSalary()
 62.    {
 63.       return salary;
 64.    }
 65.
 66.    public Date getHireDay()
 67.    {
 68.       return hireDay;
 69.    }
 70.
 71.    public void raiseSalary(double byPercent)
 72.    {
 73.       double raise = salary * byPercent / 100;
 74.       salary += raise;
 75.    }
 76.
 77.    public String toString()
 78.    {
 79.       return getClass().getName()
 80.          + "[name=" + name
 81.          + ",salary=" + salary
 82.          + ",hireDay=" + hireDay
 83.          + "]";
 84.    }
 85.
 86.    private String name;
 87.    private double salary;
 88.    private Date hireDay;
 89. }
 90.
 91. class Manager extends Employee
 92. {
 93.    /**
 94.       Constructs a Manager without a secretary
 95.       @param n the employee's name
 96.       @param s the salary
 97.       @param year the hire year
 98.       @param month the hire month
 99.       @param day the hire day
100.    */
101.    public Manager(String n, double s, int year, int month, int day)
102.    {
103.       super(n, s, year, month, day);
104.       secretary = null;
105.    }
106.
107.    /**
108.       Assigns a secretary to the manager.
109.       @param s the secretary
110.    */
111.    public void setSecretary(Employee s)
112.    {
113.       secretary = s;
114.    }
115.
116.    public String toString()
117.    {
118.       return super.toString()
119.         + "[secretary=" + secretary
120.         + "]";
121.    }
122.
123.    private Employee secretary;
124. }

This section continues the discussion of the output format of object streams. If you skipped the previous discussion, you should skip this section as well.

All objects (including arrays and strings) and all class descriptors are given serial numbers as they are saved in the output file. This process is referred to as serialization because every saved object is assigned a serial number. (The count starts 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.

It is usually not important to know the exact file format (unless you are trying to create an evil effect by modifying the data). 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://developer.java.sun.com/developer/TechTips/txtarchive/Apr00_Stu.txt demonstrates that in the case of an employee class, using external reading and writing was about 35%–40% 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.

Note

For even more exotic variations of serialization, see http://www.absolutejava.com/serialization.

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 JDK 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.

In the previous sections, we showed you how to save relatively small collections of objects by means of an object stream. But those were just demonstration programs. With object streams, it helps to think big. Suppose you write a program that lets the user produce a document. This document contains paragraphs of text, tables, graphs, and so on. You can stream out the entire document object with a single call to writeObject:

out.writeObject(doc);

The paragraph, table, and graph objects are automatically streamed out as well. One user of your program can then give the output file to another user who also has a copy of your program, and that program loads the entire document with a single call to readObject:

doc = (Document) in.readObject();

This is very useful, but your program will inevitably change, and you will release a version 1.1. 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 12–10).

Figure 12–10. 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, then 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 12–11 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 12–12 shows the opposite scenario: a program using 1.0 objects reads a 2.0 object. The additional department field is ignored.

Figure 12–11. Reading an object with fewer data fields

Figure 12–12. 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 may 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 (and, occasionally, very useful) use for the serialization mechanism: it gives you an easy way to clone an object provided the class is serializable. (Recall from Chapter 6 that you need to do a bit of work to allow an object to be cloned.)

To clone a serializable object, 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 Example 12–6 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 (as you saw in Chapter 6).

 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 12–7 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

Example 12–8 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:

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

  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.
  8.    Usage: java NIOTest filename
  9. */
 10. public class NIOTest
 11. {
 12.    public static long checksumInputStream(String filename)
 13.       throws IOException
 14.    {
 15.       InputStream in = new FileInputStream(filename);
 16.       CRC32 crc = new CRC32();
 17.
 18.       int c;
 19.       while((c = in.read()) != -1)
 20.          crc.update(c);
 21.       return crc.getValue();
 22.    }
 23.
 24.    public static long checksumBufferedInputStream(String filename)
 25.       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)
 37.       throws IOException
 38.    {
 39.       RandomAccessFile file = new RandomAccessFile(filename, "r");
 40.       long length = file.length();
 41.       CRC32 crc = new CRC32();
 42.
 43.       for (long p = 0; p < length; p++)
 44.       {
 45.          file.seek(p);
 46.          int c = file.readByte();
 47.          crc.update(c);
 48.       }
 49.       return crc.getValue();
 50.    }
 51.
 52.    public static long checksumMappedFile(String filename)
 53.       throws IOException
 54.    {
 55.       FileInputStream in = new FileInputStream(filename);
 56.       FileChannel channel = in.getChannel();
 57.
 58.       CRC32 crc = new CRC32();
 59.       int length = (int) channel.size();
 60.       MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, length);
 61.
 62.       for (int p = 0; p < length; p++)
 63.       {
 64.          int c = buffer.get(p);
 65.          crc.update(c);
 66.       }
 67.       return crc.getValue();
 68.    }
 69.
 70.    public static void main(String[] args)
 71.       throws IOException
 72.    {
 73.       System.out.println("Input Stream:");
 74.       long start = System.currentTimeMillis();
 75.       long crcValue = checksumInputStream(args[0]);
 76.       long end = System.currentTimeMillis();
 77.       System.out.println(Long.toHexString(crcValue));
 78.       System.out.println((end - start) + " milliseconds");
 79.
 80.       System.out.println("Buffered Input Stream:");
 81.       start = System.currentTimeMillis();
 82.       crcValue = checksumBufferedInputStream(args[0]);
 83.       end = System.currentTimeMillis();
 84.       System.out.println(Long.toHexString(crcValue));
 85.       System.out.println((end - start) + " milliseconds");
 86.
 87.       System.out.println("Random Access File:");
 88.       start = System.currentTimeMillis();
 89.       crcValue = checksumRandomAccessFile(args[0]);
 90.       end = System.currentTimeMillis();
 91.       System.out.println(Long.toHexString(crcValue));
 92.       System.out.println((end - start) + " milliseconds");
 93.
 94.       System.out.println("Mapped File:");
 95.       start = System.currentTimeMillis();
 96.       crcValue = checksumMappedFile(args[0]);
 97.       end = System.currentTimeMillis();
 98.       System.out.println(Long.toHexString(crcValue));
 99.       System.out.println((end - start) + " milliseconds");
100.    }
101. }

java.io.FileInputStream 1.0

java.io.FileOutputStream 1.0

java.io.RandomAccessFile 1.0

java.nio.channels.FileChannel 1.4

java.nio.Buffer 1.4

java.nio.ByteBuffer 1.4

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. In practice, you will most commonly use ByteBuffer and CharBuffer. As shown in Figure 12–13, a buffer has

These values fulfill the condition

Figure 12–13. A buffer

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 re-read the buffer, use rewind or mark/reset—see the API notes for details.

java.nio.Buffer 1.4

java.nio.CharBuffer 1.4

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.

Frankly, 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 problems. If you store information in flat files and are worried about concurrent access, you may well 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

java.nio.channels.FileLock 1.4