Thinking in Java, 3rd ed. Revision 4.0

Suppose you'd like to see a directory listing. The File object can be listed in two ways. If you call list( ) with no arguments, you'll get the full list that the File object contains. However, if you want a restricted list-for example, if you want all of the files with a n extension of .java-then you use a "directory filter," which is a class that tells how to select the File objects for display.

Here's the code for the example. Note that the result has been effortlessly sorted (alphabetically) using the java.utils.Arrays.sort( ) method and the AlphabeticComparator defined in Chapter 11:

//: c12:DirList.java
// Displays directory listing using regular expressions.
// {Args: "D.*\.java"}
import java.io.*;
import java.util.*;
import java.util.regex.*;
import com.bruceeckel.util.*;
 
public class DirList {
	public static void main(String[] args) {
		File path = new File(".");
		String[] list;
		if(args.length == 0)
			list = path.list();
		else
			list = path.list(new DirFilter(args[0]));
		Arrays.sort(list, new AlphabeticComparator());
		for(int i = 0; i < list.length; i++)
			System.out.println(list[i]);
	}
}
 
class DirFilter implements FilenameFilter {
	private Pattern pattern;
	public DirFilter(String regex) {
		pattern = Pattern.compile(regex);
	}
	public boolean accept(File dir, String name) {
		// Strip path information, search for regex:
		return pattern.matcher(
			new File(name).getName()).matches();
	}
} ///:~

The DirFilter class "implements" the interface FilenameFilter. It's useful to see how simple the FilenameFilter interface is:

public interface FilenameFilter {
	boolean accept(File dir, String name);
}

It says all that this type of object does is provide a method called accept( ). The whole reason behind the creation of this class is to provide the accept( ) method to the list( ) method so that list( ) can "call back" accept( ) to determine which file names should be included in the list. Thus, this structure is often referred to as a callback. More specifically, this is an example of the Strategy Pattern, because list( ) implements basic functionality, and you provide the Strategy in the form of a FilenameFilter in order to complete the algorithm necessary for list( ) to provide its service. Because list( ) takes a FilenameFilter object as its argument, it means that you can pass an object of any class that implements FilenameFilter to choose (even at run time) how the list( ) method will behave. The purpose of a callback is to provide flexibility in the behavior of code.

DirFilter shows that just because an interface contains only a set of methods, you're not restricted to writing only those methods. (You must at least provide definitions for all the methods in an interface, however.) In this case, the DirFilter constructor is also created.

The accept( ) method must accept a File object representing the directory that a particular file is found in, and a String containing the name of that file. You might choose to use or ignore either of these arguments, but you will probably at least use the file name. Remember that the list( ) method is calling accept( ) for each of the file names in the directory object to see which one should be included; this is indicated by the boolean result returned by accept( ).

To make sure the element you're working with is only the file name and contains no path information, all you have to do is take the String object and create a File object out of it, then call getName( ), which strips away all the path information (in a platform-independent way). Then accept( ) uses a regular expression matcher object to see if the regular expression regex matches the name of the file. Using accept( ), the list( ) method returns an array.

12-1-1-1. Anonymous inner classes▲

//: c12:DirList2.java
// Uses anonymous inner classes.
// {Args: "D.*\.java"}
import java.io.*;
import java.util.*;
import java.util.regex.*;
import com.bruceeckel.util.*;
 
public class DirList2 {
	public static FilenameFilter filter(final String regex) {
		// Creation of anonymous inner class:
		return new FilenameFilter() {
			private Pattern pattern = Pattern.compile(regex);
			public boolean accept(File dir, String name) {
				return pattern.matcher(
					new File(name).getName()).matches();
			}
		}; // End of anonymous inner class
	}
	public static void main(String[] args) {
		File path = new File(".");
		String[] list;
		if(args.length == 0)
			list = path.list();
		else
			list = path.list(filter(args[0]));
		Arrays.sort(list, new AlphabeticComparator());
		for(int i = 0; i < list.length; i++)
			System.out.println(list[i]);
	}
} ///:~

//: c12:DirList3.java
// Building the anonymous inner class "in-place."
// {Args: "D.*\.java"}
import java.io.*;
import java.util.*;
import java.util.regex.*;
import com.bruceeckel.util.*;
 
public class DirList3 {
	public static void main(final String[] args) {
		File path = new File(".");
		String[] list;
		if(args.length == 0)
			list = path.list();
		else
			list = path.list(new FilenameFilter() {
				private Pattern pattern = Pattern.compile(args[0]);
				public boolean accept(File dir, String name) {
					return pattern.matcher(
						new File(name).getName()).matches();
				}
			});
		Arrays.sort(list, new AlphabeticComparator());
		for(int i = 0; i < list.length; i++)
			System.out.println(list[i]);
	}
} ///:~

The File class is more than just a representation for an existing file or directory. You can also use a File object to create a new directory or an entire directory path if it doesn't exist. You can also look at the characteristics of files (size, last modification date, read/write), see whether a File object represents a file or a directory, and delete a file. This program shows some of the other methods available with the File class (see the HTML documentation from java.sun.com for the full set):

//: c12:MakeDirectories.java
// Demonstrates the use of the File class to
// create directories and manipulate files.
// {Args: MakeDirectoriesTest}
import com.bruceeckel.simpletest.*;
import java.io.*;
 
public class MakeDirectories {
	private static Test monitor = new Test();
	private static void usage() {
		System.err.println(
			"Usage:MakeDirectories path1 ...\n" +
			"Creates each path\n" +
			"Usage:MakeDirectories -d path1 ...\n" +
			"Deletes each path\n" +
			"Usage:MakeDirectories -r path1 path2\n" +
			"Renames from path1 to path2");
		System.exit(1);
	}
	private static void fileData(File f) {
		System.out.println(
			"Absolute path: " + f.getAbsolutePath() +
			"\n Can read: " + f.canRead() +
			"\n Can write: " + f.canWrite() +
			"\n getName: " + f.getName() +
			"\n getParent: " + f.getParent() +
			"\n getPath: " + f.getPath() +
			"\n length: " + f.length() +
			"\n lastModified: " + f.lastModified());
		if(f.isFile())
			System.out.println("It's a file");
		else if(f.isDirectory())
			System.out.println("It's a directory");
	}
	public static void main(String[] args) {
		if(args.length < 1) usage();
		if(args[0].equals("-r")) {
			if(args.length != 3) usage();
			File
				old = new File(args[1]),
				rname = new File(args[2]);
			old.renameTo(rname);
			fileData(old);
			fileData(rname);
			return; // Exit main
		}
		int count = 0;
		boolean del = false;
		if(args[0].equals("-d")) {
			count++;
			del = true;
		}
		count--;
		while(++count < args.length) {
			File f = new File(args[count]);
			if(f.exists()) {
				System.out.println(f + " exists");
				if(del) {
					System.out.println("deleting..." + f);
					f.delete();
				}
			}
			else { // Doesn't exist
				if(!del) {
					f.mkdirs();
					System.out.println("created " + f);
				}
			}
			fileData(f);
		}
		if(args.length == 1 &&
				args[0].equals("MakeDirectoriesTest"))
			monitor.expect(new String[] {
				"%% (MakeDirectoriesTest exists"+
				  "|created MakeDirectoriesTest)",
				"%% Absolute path: "
				  + "\\S+MakeDirectoriesTest",
				"%%  Can read: (true|false)",
				"%%  Can write: (true|false)",
				" getName: MakeDirectoriesTest",
				" getParent: null",
				" getPath: MakeDirectoriesTest",
				"%%  length: \\d+",
				"%%  lastModified: \\d+",
				"It's a directory"
			});
	}
} ///:~

In fileData( ) you can see various file investigation methods used to display information about the file or directory path.

The first method that's exercised by main( ) is renameTo( ), which allows you to rename (or move) a file to an entirely new path represented by the argument, which is another File object. This also works with directories of any length.

If you experiment with the preceding program, you'll find that you can make a directory path of any complexity, because mkdirs( ) will do all the work for you.

InputStream's job is to represent classes that produce input from different sources. These sources can be:

• An array of bytes.
• A String object.
• A file.
• A "pipe," which works like a physical pipe: You put things in at one end and they come out the other.
• A sequence of other streams, so you can collect them together into a single stream.
• Other sources, such as an Internet connection. (This is covered in Thinking in Enterprise Java.)

Each of these has an associated subclass of InputStream. In addition, the FilterInputStream is also a type of InputStream, to provide a base class for "decorator" classes that attach attributes or useful interfaces to input streams. This is discussed later.

Table 12-1. Types of InputStream

This category includes the classes that decide where your output will go: an array of bytes (no String, however; presumably, you can create one using the array of bytes), a file, or a "pipe."

In addition, the FilterOutputStream provides a base class for "decorator" classes that attach attributes or useful interfaces to output streams. This is discussed later.

Table 12-2. Types of OutputStream

The FilterInputStream classes accomplish two significantly different things. DataInputStream allows you to read different types of primitive data as well as String objects. (All the methods start with "read," such as readByte( ), readFloat( ), etc.) This, along with its companion DataOutputStream, allows you to move primitive data from one place to another via a stream. These "places" are determined by the classes in Table 12-1.

The remaining classes modify the way an InputStream behaves internally: whether it's buffered or unbuffered, if it keeps track of the lines it's reading (allowing you to ask for line numbers or set the line number), and whether you can push back a single character. The last two classes look a lot like support for building a compiler (that is, they were probably added to support the construction of the Java compiler), so you probably won't use them in general programming.

You'll need to buffer your input almost every time, regardless of the I/O device you're connecting to, so it would have made more sense for the I/O library to make a special case (or simply a method call) for unbuffered input rather than buffered input.

Table 12-3. Types of FilterInputStream

The complement to DataInputStream is DataOutputStream, which formats each of the primitive types and String objects onto a stream in such a way that any DataInputStream, on any machine, can read them. All the methods start with "write," such as writeByte( ), writeFloat( ), etc.

The original intent of PrintStream was to print all of the primitive data types and String objects in a viewable format. This is different from DataOutputStream, whose goal is to put data elements on a stream in a way that DataInputStream can portably reconstruct them.

The two important methods in PrintStream are print( ) and println( ), which are overloaded to print all the various types. The difference between print( ) and println( ) is that the latter adds a newline when it's done.

PrintStream can be problematic because it traps all IOExceptions (You must explicitly test the error status with checkError( ), which returns true if an error has occurred). Also, PrintStream doesn't internationalize properly and doesn't handle line breaks in a platform-independent way (these problems are solved with PrintWriter, described later).

BufferedOutputStream is a modifier and tells the stream to use buffering so you don't get a physical write every time you write to the stream. You'll probably always want to use this when doing output.

Table 12-4. Types of FilterOutputStream

Almost all of the original Java I/O stream classes have corresponding Reader and Writer classes to provide native Unicode manipulation. However, there are some places where the byte-oriented InputStreams and OutputStreams are the correct solution;in particular, the java.util.zip libraries are byte-oriented rather than char-oriented. So the most sensible approach to take is to try to use the Reader and Writer classes whenever you can, and you'll discover the situations when you have to use the byte-oriented libraries, because your code won't compile.

Here is a table that shows the correspondence between the sources and sinks of information (that is, where the data physically comes from or goes to) in the two hierarchies.

In general, you'll find that the interfaces for the two different hierarchies are similar if not identical.

For InputStreams and OutputStreams, streams were adapted for particular needs using "decorator" subclasses of FilterInputStream and FilterOutputStream. The Reader and Writer class hierarchies continue the use of this idea-but not exactly.

In the following table, the correspondence is a rougher approximation than in the previous table. The difference is because of the class organization; although BufferedOutputStream is a subclass of FilterOutputStream, BufferedWriter is not a subclass of FilterWriter (which, even though it is abstract, has no subclasses and so appears to have been put in either as a placeholder or simply so you wouldn't wonder where it was). However, the interfaces to the classes are quite a close match.

There's one direction that's quite clear: Whenever you want to use readLine( ), you shouldn't do it with a DataInputStream (this is met with a deprecation message at compile time), but instead use a BufferedReader. Other than this, DataInputStream is still a "preferred" member of the I/O library.

To make the transition to using a PrintWriter easier, it has constructors that take any OutputStream object as well as Writer objects. However, PrintWriter has no more support for formatting than PrintStream does; the interfaces are virtually the same.

The PrintWriter constructor also has an option to perform automatic flushing, which happens after every println( ) if the constructor flag is set.

Some classes were left unchanged between Java 1.0 and Java 1.1:

DataOutputStream, in particular, is used without change, so for storing and retrieving data in a transportable format, you use the InputStream and OutputStream hierarchies.

Parts 1 through 4 demonstrate the creation and use of input streams. Part 4 also shows the simple use of an output stream.

12-6-1-1. Buffered input file (1)▲

12-6-1-2. Input from memory (2)▲

12-6-1-3. Formatted memory input (3)▲

//: c12:TestEOF.java
// Testing for end of file while reading a byte at a time.
import java.io.*;
 
public class TestEOF {
	// Throw exceptions to console:
	public static void main(String[] args)
	throws IOException {
		DataInputStream in = new DataInputStream(
			new BufferedInputStream(
				new FileInputStream("TestEOF.java")));
		while(in.available() != 0)
			System.out.print((char)in.readByte());
	}
} ///:~

12-6-1-4. File output (4)▲

The two primary kinds of output streams are separated by the way they write data; one writes it for human consumption, and the other writes it to be reacquired by a DataInputStream. The RandomAccessFile stands alone, although its data format is compatible with the DataInputStream and DataOutputStream.

12-6-2-1. Storing and recovering data (5)▲

12-6-2-2. Reading and writing random access files (6)▲

The PipedInputStream, PipedOutputStream, PipedReader and PipedWriter have been mentioned only briefly in this chapter. This is not to suggest that they aren't useful, but their value is not apparent until you begin to understand multithreading, since the piped streams are used to communicate between threads. This is covered along with an example in Chapter 13.

Following the standard I/O model, Java has System.in, System.out, and System.err. Throughout this book, you've seen how to write to standard output using System.out, which is already prewrapped as a PrintStream object. System.err is likewise a PrintStream, but System.in is a raw InputStream with no wrapping. This means that although you can use System.out and System.err right away, System.in must be wrapped before you can read from it.

Typically, you'll want to read input a line at a time using readLine( ), so you'll want to wrap System.in in a BufferedReader. To do this, you must convert System.in to a Reader using InputStreamReader. Here's an example that simply echoes each line that you type in:

//: c12:Echo.java
// How to read from standard input.
// {RunByHand}
import java.io.*;
 
public class Echo {
	public static void main(String[] args)
	throws IOException {
		BufferedReader in = new BufferedReader(
			new InputStreamReader(System.in));
		String s;
		while((s = in.readLine()) != null && s.length() != 0)
			System.out.println(s);
		// An empty line or Ctrl-Z terminates the program
	}
} ///:~

The reason for the exception specification is that readLine( ) can throw an IOException. Note that System.in should usually be buffered, as with most streams.

System.out is a PrintStream, which is an OutputStream. PrintWriter has a constructor that takes an OutputStream as an argument. Thus, if you want, you can convert System.out into a PrintWriter using that constructor:

//: c12:ChangeSystemOut.java
// Turn System.out into a PrintWriter.
import com.bruceeckel.simpletest.*;
import java.io.*;
 
public class ChangeSystemOut {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		PrintWriter out = new PrintWriter(System.out, true);
		out.println("Hello, world");
		monitor.expect(new String[] {
			"Hello, world"
		});
	}
} ///:~

It's important to use the two-argument version of the PrintWriter constructor and to set the second argument to true in order to enable automatic flushing; otherwise, you may not see the output.

The Java System class allows you to redirect the standard input, output, and error I/O streams using simple static method calls:

setIn(InputStream)
setOut(PrintStream)
setErr(PrintStream)

Redirecting output is especially useful if you suddenly start creating a large amount of output on your screen, and it's scrolling past faster than you can read it. (64) Redirecting input is valuable for a command-line program in which you want to test a particular user-input sequence repeatedly. Here's a simple example that shows the use of these methods:

//: c12:Redirecting.java
// Demonstrates standard I/O redirection.
// {Clean: test.out}
import java.io.*;
 
public class Redirecting {
	// Throw exceptions to console:
	public static void main(String[] args)
	throws IOException {
		PrintStream console = System.out;
		BufferedInputStream in = new BufferedInputStream(
			new FileInputStream("Redirecting.java"));
		PrintStream out = new PrintStream(
			new BufferedOutputStream(
				new FileOutputStream("test.out")));
		System.setIn(in);
		System.setOut(out);
		System.setErr(out);
		BufferedReader br = new BufferedReader(
			new InputStreamReader(System.in));
		String s;
		while((s = br.readLine()) != null)
			System.out.println(s);
		out.close(); // Remember this!
		System.setOut(console);
	}
} ///:~

This program attaches standard input to a file and redirects standard output and standard error to another file.

I/O redirection manipulates streams of bytes, not streams of characters, thus InputStreams and OutputStreams are used rather than Readers and Writers.

If you look back at GetChannel.java, you'll notice that, to print the information in the file, we are pulling the data out one byte at a time and casting each byte to a char. This seems a bit primitive-if you look at the java.nio.CharBuffer class, you'll see that it has a toString( ) method that says: "Returns a string containing the characters in this buffer." Since a ByteBuffer can be viewed as a CharBuffer with the asCharBuffer( ) method, why not use that? As you can see from the first line in the expect( ) statement below, this doesn't work out:

//: c12:BufferToText.java
// Converting text to and from ByteBuffers
// {Clean: data2.txt}
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
import java.nio.charset.*;
import com.bruceeckel.simpletest.*;
 
public class BufferToText {
	private static Test monitor = new Test();
	private static final int BSIZE = 1024;
	public static void main(String[] args) throws Exception {
		FileChannel fc =
			new FileOutputStream("data2.txt").getChannel();
		fc.write(ByteBuffer.wrap("Some text".getBytes()));
		fc.close();
		fc = new FileInputStream("data2.txt").getChannel();
		ByteBuffer buff = ByteBuffer.allocate(BSIZE);
		fc.read(buff);
		buff.flip();
		// Doesn't work:
		System.out.println(buff.asCharBuffer());
		// Decode using this system's default Charset:
		buff.rewind();
		String encoding = System.getProperty("file.encoding");
		System.out.println("Decoded using " + encoding + ": " 
			+ Charset.forName(encoding).decode(buff));
		// Or, we could encode with something that will print:
		fc = new FileOutputStream("data2.txt").getChannel();
		fc.write(ByteBuffer.wrap(
			"Some text".getBytes("UTF-16BE")));
		fc.close();
		// Now try reading again:
		fc = new FileInputStream("data2.txt").getChannel();
		buff.clear();
		fc.read(buff);
		buff.flip();
		System.out.println(buff.asCharBuffer());
		// Use a CharBuffer to write through:
		fc = new FileOutputStream("data2.txt").getChannel();
		buff = ByteBuffer.allocate(24); // More than needed
		buff.asCharBuffer().put("Some text");
		fc.write(buff);
		fc.close();
		// Read and display:
		fc = new FileInputStream("data2.txt").getChannel();
		buff.clear();
		fc.read(buff);
		buff.flip();
		System.out.println(buff.asCharBuffer());
		monitor.expect(new String[] {
			"????",
			"%% Decoded using [A-Za-z0-9_\\-]+: Some text",
			"Some text",
			"Some text\0\0\0"
		});
	}
} ///:~

The buffer contains plain bytes, and to turn these into characters we must either encode them as we put them in (so that they will be meaningful when they come out) or decode them as they come out of the buffer. This can be accomplished using the java.nio.charset.Charset class, which provides tools for encoding into many different types of character sets:

//: c12:AvailableCharSets.java
// Displays Charsets and aliases
import java.nio.charset.*;
import java.util.*;
import com.bruceeckel.simpletest.*;
 
public class AvailableCharSets {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		Map charSets = Charset.availableCharsets();
		Iterator it = charSets.keySet().iterator();
		while(it.hasNext()) {
			String csName = (String)it.next();
			System.out.print(csName);
			Iterator aliases = ((Charset)charSets.get(csName))
				.aliases().iterator();
			if(aliases.hasNext())
				System.out.print(": ");
			while(aliases.hasNext()) {
				System.out.print(aliases.next());
				if(aliases.hasNext())
					System.out.print(", ");
			}
			System.out.println();
		}
		monitor.expect(new String[] {
			"Big5: csBig5",
			"Big5-HKSCS: big5-hkscs, Big5_HKSCS, big5hkscs",
			"EUC-CN",
			"EUC-JP: eucjis, x-eucjp, csEUCPkdFmtjapanese, " +
			"eucjp, Extended_UNIX_Code_Packed_Format_for" +
			"_Japanese, x-euc-jp, euc_jp",
			"euc-jp-linux: euc_jp_linux",
			"EUC-KR: ksc5601, 5601, ksc5601_1987, ksc_5601, " +
			"ksc5601-1987, euc_kr, ks_c_5601-1987, " +
			"euckr, csEUCKR",
			"EUC-TW: cns11643, euc_tw, euctw",
			"GB18030: gb18030-2000",
			"GBK: GBK",
			"ISCII91: iscii, ST_SEV_358-88, iso-ir-153, " +
			"csISO153GOST1976874",
			"ISO-2022-CN-CNS: ISO2022CN_CNS",
			"ISO-2022-CN-GB: ISO2022CN_GB",
			"ISO-2022-KR: ISO2022KR, csISO2022KR",
			"ISO-8859-1: iso-ir-100, 8859_1, ISO_8859-1, " +
			"ISO8859_1, 819, csISOLatin1, IBM-819, " +
			"ISO_8859-1:1987, latin1, cp819, ISO8859-1, " +
			"IBM819, ISO_8859_1, l1",
			"ISO-8859-13",
			"ISO-8859-15: 8859_15, csISOlatin9, IBM923, cp923," +
			" 923, L9, IBM-923, ISO8859-15, LATIN9, " +
			"ISO_8859-15, LATIN0, csISOlatin0, " +
			"ISO8859_15_FDIS, ISO-8859-15",
			"ISO-8859-2", "ISO-8859-3", "ISO-8859-4",
			"ISO-8859-5", "ISO-8859-6", "ISO-8859-7",
			"ISO-8859-8", "ISO-8859-9", 
			"JIS0201: X0201, JIS_X0201, csHalfWidthKatakana",
			"JIS0208: JIS_C6626-1983, csISO87JISX0208, x0208, " +
			"JIS_X0208-1983, iso-ir-87",
			"JIS0212: jis_x0212-1990, x0212, iso-ir-159, " +
			"csISO159JISC02121990",
			"Johab: ms1361, ksc5601_1992, ksc5601-1992",
			"KOI8-R",
			"Shift_JIS: shift-jis, x-sjis, ms_kanji, " +
			"shift_jis, csShiftJIS, sjis, pck",
			"TIS-620",
			"US-ASCII: IBM367, ISO646-US, ANSI_X3.4-1986, " +
			"cp367, ASCII, iso_646.irv:1983, 646, us, iso-ir-6,"+
			" csASCII, ANSI_X3.4-1968, ISO_646.irv:1991",
			"UTF-16: UTF_16",
			"UTF-16BE: X-UTF-16BE, UTF_16BE, ISO-10646-UCS-2",
			"UTF-16LE: UTF_16LE, X-UTF-16LE",
			"UTF-8: UTF8", "windows-1250", "windows-1251",
			"windows-1252: cp1252",
			"windows-1253", "windows-1254", "windows-1255",
			"windows-1256", "windows-1257", "windows-1258",
			"windows-936: ms936, ms_936",
			"windows-949: ms_949, ms949", "windows-950: ms950",
		});
	}
} ///:~

So, returning to BufferToText.java, if you rewind( ) the buffer (to go back to the beginning of the data) and then use that platform's default character set to decode( ) the data, the resulting CharBuffer will print to the console just fine. To discover the default character set, use System.getProperty("file.encoding"), which produces the string that names the character set. Passing this to Charset.forName( ) produces the Charset object that can be used to decode the string.

Another alternative is to encode( ) using a character set that will result in something printable when the file is read, as you see in the third part of BufferToText.java. Here, UTF-16BE is used to write the text into the file, and when it is read, all you have to do is convert it to a CharBuffer, and it produces the expected text.

Finally, you see what happens if you write to the ByteBuffer through a CharBuffer (you'll learn more about this later). Note that 24 bytes are allocated for the ByteBuffer. Since each char requires two bytes, this is enough for 12 chars, but "Some text" only has 9. The remaining zero bytes still appear in the representation of the CharBuffer produced by its toString( ), as you can see in the output.

Although a ByteBuffer only holds bytes, it contains methods to produce each of the different types of primitive values from the bytes it contains. This example shows the insertion and extraction of various values using these methods:

//: c12:GetData.java
// Getting different representations from a ByteBuffer
import java.nio.*;
import com.bruceeckel.simpletest.*;
 
public class GetData {
	private static Test monitor = new Test();
	private static final int BSIZE = 1024;
	public static void main(String[] args) {
		ByteBuffer bb = ByteBuffer.allocate(BSIZE);
		// Allocation automatically zeroes the ByteBuffer:
		int i = 0;
		while(i++ < bb.limit())
			if(bb.get() != 0)
				System.out.println("nonzero");
		System.out.println("i = " + i);
		bb.rewind();
		// Store and read a char array:
		bb.asCharBuffer().put("Howdy!");
		char c;
		while((c = bb.getChar()) != 0)
			System.out.print(c + " ");
		System.out.println();
		bb.rewind();
		// Store and read a short:
		bb.asShortBuffer().put((short)471142);
		System.out.println(bb.getShort());
		bb.rewind();
		// Store and read an int:
		bb.asIntBuffer().put(99471142);
		System.out.println(bb.getInt());
		bb.rewind();
		// Store and read a long:
		bb.asLongBuffer().put(99471142);
		System.out.println(bb.getLong());
		bb.rewind();
		// Store and read a float:
		bb.asFloatBuffer().put(99471142);
		System.out.println(bb.getFloat());
		bb.rewind();
		// Store and read a double:
		bb.asDoubleBuffer().put(99471142);
		System.out.println(bb.getDouble());
		bb.rewind();
		monitor.expect(new String[] {
			"i = 1025",
			"H o w d y ! ",
			"12390", // Truncation changes the value
			"99471142",
			"99471142",
			"9.9471144E7",
			"9.9471142E7"
		});
	}
} ///:~

After a ByteBuffer is allocated, its values are checked to see whether buffer allocation automatically zeroes the contents-and it does. All 1,024 values are checked (up to the limit( ) of the buffer), and all are zero.

The easiest way to insert primitive values into a ByteBuffer is to get the appropriate "view" on that buffer using asCharBuffer( ), asShortBuffer( ), etc., and then to use that view's put( ) method. You can see this is the process used for each of the primitive data types. The only one of these that is a little odd is the put( ) for the ShortBuffer, which requires a cast (note that the cast truncates and changes the resulting value). All the other view buffers do not require casting in their put( ) methods.

A "view buffer" allows you to look at an underlying ByteBuffer through the window of a particular primitive type. The ByteBuffer is still the actual storage that's "backing" the view, so any changes you make to the view are reflected in modifications to the data in the ByteBuffer. As seen in the previous example, this allows you to conveniently insert primitive types into a ByteBuffer. A view also allows you to read primitive values from a ByteBuffer, either one at a time (as ByteBuffer allows) or in batches (into arrays). Here's an example that manipulates ints in a ByteBuffer via an IntBuffer:

//: c12:IntBufferDemo.java
// Manipulating ints in a ByteBuffer with an IntBuffer
import java.nio.*;
import com.bruceeckel.simpletest.*;
import com.bruceeckel.util.*;
 
public class IntBufferDemo {
	private static Test monitor = new Test();
	private static final int BSIZE = 1024;
	public static void main(String[] args) {
		ByteBuffer bb = ByteBuffer.allocate(BSIZE);
		IntBuffer ib = bb.asIntBuffer();
		// Store an array of int:
		ib.put(new int[] { 11, 42, 47, 99, 143, 811, 1016 });
		// Absolute location read and write:
		System.out.println(ib.get(3));
		ib.put(3, 1811);
		ib.rewind();
		while(ib.hasRemaining()) {
			int i = ib.get();
			if(i == 0) break; // Else we'll get the entire buffer
			System.out.println(i);
		}
		monitor.expect(new String[] {
			"99",
			"11",
			"42",
			"47",
			"1811",
			"143",
			"811",
			"1016"
		});
	}
} ///:~

The overloaded put( ) method is first used to store an array of int. The following get( ) and put( ) method calls directly access an int location in the underlying ByteBuffer. Note that these absolute location accesses are available for primitive types by talking directly to a ByteBuffer, as well.

Once the underlying ByteBuffer is filled with ints or some other primitive type via a view buffer, then that ByteBuffer can be written directly to a channel. You can just as easily read from a channel and use a view buffer to convert everything to a particular type of primitive. Here's an example that interprets the same sequence of bytes as short, int, float, long, and double by producing different view buffers on the same ByteBuffer:

//: c12:ViewBuffers.java
import java.nio.*;
import com.bruceeckel.simpletest.*;
 
public class ViewBuffers {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		ByteBuffer bb = ByteBuffer.wrap(
			new byte[]{ 0, 0, 0, 0, 0, 0, 0, 'a' });
		bb.rewind();
		System.out.println("Byte Buffer");
		while(bb.hasRemaining())
			System.out.println(bb.position()+ " -> " + bb.get());
		CharBuffer cb =
			((ByteBuffer)bb.rewind()).asCharBuffer();
		System.out.println("Char Buffer");
		while(cb.hasRemaining())
			System.out.println(cb.position()+ " -> " + cb.get());
		FloatBuffer fb =
			((ByteBuffer)bb.rewind()).asFloatBuffer();
		System.out.println("Float Buffer");
		while(fb.hasRemaining())
			System.out.println(fb.position()+ " -> " + fb.get());
		IntBuffer ib =
			((ByteBuffer)bb.rewind()).asIntBuffer();
		System.out.println("Int Buffer");
		while(ib.hasRemaining())
			System.out.println(ib.position()+ " -> " + ib.get());
		LongBuffer lb =
			((ByteBuffer)bb.rewind()).asLongBuffer();
		System.out.println("Long Buffer");
		while(lb.hasRemaining())
			System.out.println(lb.position()+ " -> " + lb.get());
		ShortBuffer sb =
			((ByteBuffer)bb.rewind()).asShortBuffer();
		System.out.println("Short Buffer");
		while(sb.hasRemaining())
			System.out.println(sb.position()+ " -> " + sb.get());
		DoubleBuffer db =
			((ByteBuffer)bb.rewind()).asDoubleBuffer();
		System.out.println("Double Buffer");
		while(db.hasRemaining())
			System.out.println(db.position()+ " -> " + db.get());
		monitor.expect(new String[] {
			"Byte Buffer",
			"0 -> 0",
			"1 -> 0",
			"2 -> 0",
			"3 -> 0",
			"4 -> 0",
			"5 -> 0",
			"6 -> 0",
			"7 -> 97",
			"Char Buffer",
			"0 -> \0",
			"1 -> \0",
			"2 -> \0",
			"3 -> a",
			"Float Buffer",
			"0 -> 0.0",
			"1 -> 1.36E-43",
			"Int Buffer",
			"0 -> 0",
			"1 -> 97",
			"Long Buffer",
			"0 -> 97",
			"Short Buffer",
			"0 -> 0",
			"1 -> 0",
			"2 -> 0",
			"3 -> 97",
			"Double Buffer",
			"0 -> 4.8E-322"
		});
	}
} ///:~

The ByteBuffer is produced by "wrapping" an eight-byte array, which is then displayed via view buffers of all the different primitive types. You can see in the following diagram the way the data appears differently when read from the different types of buffers:

This corresponds to the output from the program.

12-9-3-1. Endians▲

Different machines may use different byte-ordering approaches to store data. "Big endian" places the most significant byte in the lowest memory address, and "little endian" places the most significant byte in the highest memory address. When storing a quantity that is greater than one byte, like int, float, etc.,you may need to consider the byte ordering. A ByteBuffer stores data in big endian form, and data sent over a network always uses big endian order. You can change the endian-ness of a ByteBuffer using order( ) with an argument of ByteOrder.BIG_ENDIAN or ByteOrder.LITTLE_ENDIAN.

Consider a ByteBuffer containing the following two bytes:

If you read the data as a short (ByteBuffer.asShortBuffer( )), you will get the number 97 (00000000 01100001), but if you change to little endian, you will get the number 24832 (01100001 00000000).

Here's an example that shows how byte ordering is changed in characters depending on the endian setting:

 

Sélectionnez

//: c12:Endians.java
// Endian differences and data storage.
import java.nio.*;
import com.bruceeckel.simpletest.*;
import com.bruceeckel.util.*;
 
public class Endians {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		ByteBuffer bb = ByteBuffer.wrap(new byte[12]);
		bb.asCharBuffer().put("abcdef");
		System.out.println(Arrays2.toString(bb.array()));
		bb.rewind();
		bb.order(ByteOrder.BIG_ENDIAN);
		bb.asCharBuffer().put("abcdef");
		System.out.println(Arrays2.toString(bb.array()));
		bb.rewind();
		bb.order(ByteOrder.LITTLE_ENDIAN);
		bb.asCharBuffer().put("abcdef");
		System.out.println(Arrays2.toString(bb.array()));
		monitor.expect(new String[]{
			"[0, 97, 0, 98, 0, 99, 0, 100, 0, 101, 0, 102]",
			"[0, 97, 0, 98, 0, 99, 0, 100, 0, 101, 0, 102]",
			"[97, 0, 98, 0, 99, 0, 100, 0, 101, 0, 102, 0]"
		});
	} 
} ///:~

The ByteBuffer is given enough space to hold all the bytes in charArray as an external buffer so that that array( ) method can be called to display the underlying bytes. The array( ) method is "optional," and you can only call it on a buffer that is backed by an array; otherwise, you'll get an UnsupportedOperationException.

charArray is inserted into the ByteBuffer via a CharBuffer view. When the underlying bytes are displayed, you can see that the default ordering is the same as the subsequent big endian order, whereas the little endian order swaps the bytes.

The diagram here illustrates the relationships between the nio classes, so that you can see how to move and convert data. For example, if you wish to write a byte array to a file, then you wrap the byte array using the ByteBuffer.wrap( ) method, open a channel on the FileOutputStream using the getChannel( ) method, and then write data into FileChannel from this ByteBuffer.

Note that ByteBuffer is the only way to move data in and out of channels, and that you can only create a standalone primitive-typed buffer, or get one from a ByteBuffer using an "as" method. That is, you cannot convert a primitive-typed buffer to a ByteBuffer. However, since you are able to move primitive data into and out of a ByteBuffer via a view buffer, this is not really a restriction.

A Buffer consists of data and four indexes to access and manipulate this data efficiently: mark, position, limit and capacity. There are methods to set and reset these indexes and to query their value.

Methods that insert and extract data from the buffer update these indexes to reflect the changes.

This example uses a very simple algorithm (swapping adjacent characters) to scramble and unscramble characters in a CharBuffer:

//: c12:UsingBuffers.java
import java.nio.*;
import com.bruceeckel.simpletest.*;
 
public class UsingBuffers {
	private static Test monitor = new Test();
	private static void symmetricScramble(CharBuffer buffer){
		while(buffer.hasRemaining()) {
			buffer.mark();
			char c1 = buffer.get();
			char c2 = buffer.get();
			buffer.reset();
			buffer.put(c2).put(c1);
		}
	}
	public static void main(String[] args) {
		char[] data = "UsingBuffers".toCharArray();
		ByteBuffer bb = ByteBuffer.allocate(data.length * 2);
		CharBuffer cb = bb.asCharBuffer();
		cb.put(data);
		System.out.println(cb.rewind());
		symmetricScramble(cb);
		System.out.println(cb.rewind());
		symmetricScramble(cb);
		System.out.println(cb.rewind());
		monitor.expect(new String[] {
			"UsingBuffers",
			"sUniBgfuefsr",
			"UsingBuffers"
		});
	}
} ///:~

Although you could produce a CharBuffer directly by calling wrap( ) with a char array, an underlying ByteBuffer is allocated instead, and a CharBuffer is produced as a view on the ByteBuffer. This emphasizes that fact that the goal is always to manipulate a ByteBuffer, since that is what interacts with a channel.

Here's what the buffer looks like after the put( ):

The position points to the first element in the buffer, and the capacity and limit point to the last element.

In symmetricScramble( ), the while loop iterates until position is equivalent to limit. The position of the buffer changes when a relative get( ) or put( ) function is called on it. You can also call absolute get( ) and put( ) methods that include an index argument, which is the location where the get( ) or put( ) takes place. These methods do not modify the value of the buffer's position.

When the control enters the while loop, the value of mark is set using mark( ) call. The state of the buffer then:

The two relative get( ) calls save the value of the first two characters in variables c1 and c2. After these two calls, the buffer looks like this:

To perform the swap, we need to write c2 at position = 0 and c1 at position = 1. We can either use the absolute put method to achieve this, or set the value of position to mark, which is what reset( ) does:

The two put( ) methods write c2 and then c1:

During the next iteration of the loop, mark is set to the current value of position:

The process continues until the entire buffer is traversed. At the end of the while loop, position is at the end of the buffer. If you print the buffer, only the characters between the position and limit are printed. Thus, if you want to show the entire contents of the buffer you must set position to the start of the buffer using rewind( ). Here is the state of buffer after the rewind( ) call (the value of mark becomes undefined):

When the function symmetricScramble( ) is called again, the CharBuffer undergoes the same process and is restored to its original state.

Memory-mapped files allow you to create and modify files that are too big to bring into memory. With a memory-mapped file, you can pretend that the entire file is in memory and that you can access it by simply treating it as a very large array. This approach greatly simplifies the code you write in order to modify the file. Here's a small example:

//: c12:LargeMappedFiles.java
// Creating a very large file using mapping.
// {RunByHand}
// {Clean: test.dat}
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
 
public class LargeMappedFiles {
	static int length = 0x8FFFFFF; // 128 Mb
	public static void main(String[] args) throws Exception {
		MappedByteBuffer out = 
			new RandomAccessFile("test.dat", "rw").getChannel()
				.map(FileChannel.MapMode.READ_WRITE, 0, length);
		for(int i = 0; i < length; i++)
			out.put((byte)'x');
		System.out.println("Finished writing");
		for(int i = length/2; i < length/2 + 6; i++)
			System.out.print((char)out.get(i));
	}
} ///:~

To do both writing and reading, we start with a RandomAccessFile, get a channel for that file, and then call map( ) to produce a MappedByteBuffer, which is a particular kind of direct buffer. Note that you must specify the starting point and the length of the region that you want to map in the file; this means that you have the option to map smaller regions of a large file.

MappedByteBuffer is inherited from ByteBuffer, so it has all of ByteBuffer's methods. Only the very simple uses of put( ) and get( ) are shown here, but you can also use things like asCharBuffer( ), etc.

The file created with the preceding program is 128 MB long, which is probably larger than the space your OS will allow. The file appears to be accessible all at once because only portions of it are brought into memory, and other parts are swapped out. This way a very large file (up to 2 GB) can easily be modified. Note that the file-mapping facilities of the underlying operating system are used to maximize performance.

12-9-6-1. Performance▲

//: c12:MappedIO.java
// {Clean: temp.tmp}
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
 
public class MappedIO {
	private static int numOfInts = 4000000;
	private static int numOfUbuffInts = 200000;
	private abstract static class Tester {
		private String name;
		public Tester(String name) { this.name = name; }
		public long runTest() {
			System.out.print(name + ": ");
			try {
				long startTime = System.currentTimeMillis();
				test();
				long endTime = System.currentTimeMillis();
				return (endTime - startTime);
			} catch (IOException e) {
				throw new RuntimeException(e);
			}
		}
		public abstract void test() throws IOException;
	}
	private static Tester[] tests = { 
		new Tester("Stream Write") {
			public void test() throws IOException {
				DataOutputStream dos = new DataOutputStream(
					new BufferedOutputStream(
						new FileOutputStream(new File("temp.tmp"))));
				for(int i = 0; i < numOfInts; i++)
					dos.writeInt(i);
				dos.close();
			}
		}, 
		new Tester("Mapped Write") {
			public void test() throws IOException {
				FileChannel fc = 
					new RandomAccessFile("temp.tmp", "rw")
						.getChannel();
				IntBuffer ib = fc.map(
					FileChannel.MapMode.READ_WRITE, 0, fc.size())
					.asIntBuffer();
				for(int i = 0; i < numOfInts; i++)
					ib.put(i);
				fc.close();
			}
		}, 
		new Tester("Stream Read") {
			public void test() throws IOException {
				DataInputStream dis = new DataInputStream(
					new BufferedInputStream(
						new FileInputStream("temp.tmp")));
				for(int i = 0; i < numOfInts; i++)
					dis.readInt();
				dis.close();
			}
		}, 
		new Tester("Mapped Read") {
			public void test() throws IOException {
				FileChannel fc = new FileInputStream(
					new File("temp.tmp")).getChannel();
				IntBuffer ib = fc.map(
					FileChannel.MapMode.READ_ONLY, 0, fc.size())
				.asIntBuffer();
				while(ib.hasRemaining())
					ib.get();
				fc.close();
			}
		}, 
		new Tester("Stream Read/Write") {
			public void test() throws IOException {
				RandomAccessFile raf = new RandomAccessFile(
					new File("temp.tmp"), "rw");
				raf.writeInt(1);
				for(int i = 0; i < numOfUbuffInts; i++) {
					raf.seek(raf.length() - 4);
					raf.writeInt(raf.readInt());
				}
				raf.close();
			}
		}, 
		new Tester("Mapped Read/Write") {
			public void test() throws IOException {
				FileChannel fc = new RandomAccessFile(
					new File("temp.tmp"), "rw").getChannel();
				IntBuffer ib = fc.map(
					FileChannel.MapMode.READ_WRITE, 0, fc.size())
					.asIntBuffer();
				ib.put(0);
				for(int i = 1; i < numOfUbuffInts; i++)
					ib.put(ib.get(i - 1));
				fc.close();
			}
		}
	};
	public static void main(String[] args) {
		for(int i = 0; i < tests.length; i++)
			System.out.println(tests[i].runTest());
	}
} ///:~

Stream Write: 1719
Mapped Write: 359
Stream Read: 750
Mapped Read: 125
Stream Read/Write: 5188
Mapped Read/Write: 16

File locking, introduced in JDK 1.4, allows you to synchronize access to a file as a shared resource. However, the two threads that contend for the same file may be in different JVMs, or one may be a Java thread and the other some native thread in the operating system. The file locks are visible to other operating system processes because Java file locking maps directly to the native operating system locking facility.

Here is a simple example of file locking.

//: c12:FileLocking.java
// {Clean: file.txt}
import java.io.FileOutputStream;
import java.nio.channels.*;
 
public class FileLocking {
	public static void main(String[] args) throws Exception {
		FileOutputStream fos= new FileOutputStream("file.txt");
		FileLock fl = fos.getChannel().tryLock();
		if(fl != null) {
			System.out.println("Locked File");
			Thread.sleep(100);
			fl.release();
			System.out.println("Released Lock");
		}
		fos.close();
	}
} ///:~

You get a FileLock on the entire file by calling either tryLock( ) or lock( ) on a FileChannel. (SocketChannel, DatagramChannel, and ServerSocketChannel do not need locking since they are inherently single-process entities; you don't generally share a network socket between two processes.) tryLock( ) is non-blocking. It tries to grab the lock, but if it cannot (when some other process already holds the same lock and it is not shared), it simply returns from the method call. lock( ) blocks until the lock is acquired, or the thread that invoked lock( ) is interrupted, or the channel on which the lock( ) method is called is closed. A lock is released using FileLock.release( ).

It is also possible to lock a part of the file by using

tryLock(long position, long size, boolean shared)

or

lock(long position, long size, boolean shared)

which locks the region (size - position). The third argument specifies whether this lock is shared.

Although the zero-argument locking methods adapt to changes in the size of a file, locks with a fixed size do not change if the file size changes. If a lock is acquired for a region from position to position+size and the file increases beyond position+size, then the section beyond position+size is not locked. The zero-argument locking methods lock the entire file, even if it grows.

Support for exclusive or shared locks must be provided by the underlying operating system. If the operating system does not support shared locks and a request is made for one, an exclusive lock is used instead. The type of lock (shared or exclusive) can be queried using FileLock.isShared( ).

12-9-7-1. Locking portions of a mapped file▲

//: c12:LockingMappedFiles.java
// Locking portions of a mapped file.
// {RunByHand}
// {Clean: test.dat}
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
 
public class LockingMappedFiles {
	static final int LENGTH = 0x8FFFFFF; // 128 Mb
	static FileChannel fc;
	public static void main(String[] args) throws Exception {
		fc = 
			new RandomAccessFile("test.dat", "rw").getChannel();
		MappedByteBuffer out = 
			fc.map(FileChannel.MapMode.READ_WRITE, 0, LENGTH);
		for(int i = 0; i < LENGTH; i++)
			out.put((byte)'x');
		new LockAndModify(out, 0, 0 + LENGTH/3);
		new LockAndModify(out, LENGTH/2, LENGTH/2 + LENGTH/4);
	}
	private static class LockAndModify extends Thread {
		private ByteBuffer buff;
		private int start, end;
		LockAndModify(ByteBuffer mbb, int start, int end) {
			this.start = start;
			this.end = end;
			mbb.limit(end);
			mbb.position(start);
			buff = mbb.slice();
			start();
		}    
		public void run() {
			try {
				// Exclusive lock with no overlap:
				FileLock fl = fc.lock(start, end, false);
				System.out.println("Locked: "+ start +" to "+ end);
				// Perform modification:
				while(buff.position() < buff.limit() - 1)
					buff.put((byte)(buff.get() + 1));
				fl.release();
				System.out.println("Released: "+start+" to "+ end);
			} catch(IOException e) {
				throw new RuntimeException(e);
			}
		}
	}
} ///:~

The GZIP interface is simple and thus is probably more appropriate when you have a single stream of data that you want to compress (rather than a container of dissimilar pieces of data). Here's an example that compresses a single file:

//: c12:GZIPcompress.java
// {Args: GZIPcompress.java}
// {Clean: test.gz}
import com.bruceeckel.simpletest.*;
import java.io.*;
import java.util.zip.*;
 
public class GZIPcompress {
	private static Test monitor = new Test();
	// Throw exceptions to console:
	public static void main(String[] args)
			throws IOException {
		if(args.length == 0) {
			System.out.println(
				"Usage: \nGZIPcompress file\n" +
				"\tUses GZIP compression to compress " +
				"the file to test.gz");
			System.exit(1);
		}
		BufferedReader in = new BufferedReader(
			new FileReader(args[0]));
		BufferedOutputStream out = new BufferedOutputStream(
			new GZIPOutputStream(
				new FileOutputStream("test.gz")));
		System.out.println("Writing file");
		int c;
		while((c = in.read()) != -1)
			out.write(c);
		in.close();
		out.close();
		System.out.println("Reading file");
		BufferedReader in2 = new BufferedReader(
			new InputStreamReader(new GZIPInputStream(
				new FileInputStream("test.gz"))));
		String s;
		while((s = in2.readLine()) != null)
			System.out.println(s);
		monitor.expect(new String[] {
			"Writing file",
			"Reading file"
		}, args[0]);
	}
} ///:~

The use of the compression classes is straightforward; you simply wrap your output stream in a GZIPOutputStream or ZipOutputStream, and your input stream in a GZIPInputStream or ZipInputStream. All else is ordinary I/O reading and writing. This is an example of mixing the char-oriented streams with the byte-oriented streams; in uses the Reader classes, whereas GZIPOutputStream's constructor can accept only an OutputStream object, not a Writer object. When the file is opened, the GZIPInputStream is converted to a Reader.

The library that supports the Zip format is much more extensive. With it you can easily store multiple files, and there's even a separate class to make the process of reading a Zip file easy. The library uses the standard Zip format so that it works seamlessly with all the tools currently downloadable on the Internet. The following example has the same form as the previous example, but it handles as many command-line arguments as you want. In addition, it shows the use of the Checksum classes to calculate and verify the checksum for the file. There are two Checksum types: Adler32 (which is faster) and CRC32 (which is slower but slightly more accurate).

//: c12:ZipCompress.java
// Uses Zip compression to compress any
// number of files given on the command line.
// {Args: ZipCompress.java}
// {Clean: test.zip}
import com.bruceeckel.simpletest.*;
import java.io.*;
import java.util.*;
import java.util.zip.*;
 
public class ZipCompress {
	private static Test monitor = new Test();
	// Throw exceptions to console:
	public static void main(String[] args)
	throws IOException {
		FileOutputStream f = new FileOutputStream("test.zip");
		CheckedOutputStream csum =
			new CheckedOutputStream(f, new Adler32());
		ZipOutputStream zos = new ZipOutputStream(csum);
		BufferedOutputStream out =
			new BufferedOutputStream(zos);
		zos.setComment("A test of Java Zipping");
		// No corresponding getComment(), though.
		for(int i = 0; i < args.length; i++) {
			System.out.println("Writing file " + args[i]);
			BufferedReader in =
				new BufferedReader(new FileReader(args[i]));
			zos.putNextEntry(new ZipEntry(args[i]));
			int c;
			while((c = in.read()) != -1)
				out.write(c);
			in.close();
		}
		out.close();
		// Checksum valid only after the file has been closed!
		System.out.println("Checksum: " +
			csum.getChecksum().getValue());
		// Now extract the files:
		System.out.println("Reading file");
		FileInputStream fi = new FileInputStream("test.zip");
		CheckedInputStream csumi =
			new CheckedInputStream(fi, new Adler32());
		ZipInputStream in2 = new ZipInputStream(csumi);
		BufferedInputStream bis = new BufferedInputStream(in2);
		ZipEntry ze;
		while((ze = in2.getNextEntry()) != null) {
			System.out.println("Reading file " + ze);
			int x;
			while((x = bis.read()) != -1)
				System.out.write(x);
		}
		if(args.length == 1)
			monitor.expect(new String[] {
				"Writing file " + args[0],
				"%% Checksum: \\d+",
				"Reading file",
				"Reading file " + args[0]}, args[0]);
		System.out.println("Checksum: " +
			csumi.getChecksum().getValue());
		bis.close();
		// Alternative way to open and read zip files:
		ZipFile zf = new ZipFile("test.zip");
		Enumeration e = zf.entries();
		while(e.hasMoreElements()) {
			ZipEntry ze2 = (ZipEntry)e.nextElement();
			System.out.println("File: " + ze2);
			// ... and extract the data as before
		}
		if(args.length == 1)
			monitor.expect(new String[] {
				"%% Checksum: \\d+",
				"File: " + args[0]
			});
	}
} ///:~

For each file to add to the archive, you must call putNextEntry( ) and pass it a ZipEntry object. The ZipEntry object contains an extensive interface that allows you to get and set all the data available on that particular entry in your Zip file: name, compressed and uncompressed sizes, date, CRC checksum, extra field data, comment, compression method, and whether it's a directory entry. However, even though the Zip format has a way to set a password, this is not supported in Java's Zip library. And although CheckedInputStream and CheckedOutputStream support both Adler32 and CRC32 checksums, the ZipEntry class supports only an interface for CRC. This is a restriction of the underlying Zip format, but it might limit you from using the faster Adler32.

To extract files, ZipInputStream has a getNextEntry( ) method that returns the next ZipEntry if there is one. As a more succinct alternative, you can read the file using a ZipFile object, which has a method entries( ) to return an Enumeration to the ZipEntries.

In order to read the checksum, you must somehow have access to the associated Checksum object. Here, a reference to the CheckedOutputStream and CheckedInputStream objects is retained, but you could also just hold onto a reference to the Checksum object.

A baffling method in Zip streams is setComment( ). As shown in ZipCompress.java, you can set a comment when you're writing a file, but there's no way to recover the comment in the ZipInputStream. Comments appear to be supported fully on an entry-by-entry basis only via ZipEntry.

Of course, you are not limited to files when using the GZIP or Zip libraries-you can compress anything, including data to be sent through a network connection.

The Zip format is also used in the JAR (Java ARchive) file format, which is a way to collect a group of files into a single compressed file, just like Zip. However, like everything else in Java, JAR files are cross-platform, so you don't need to worry about platform issues. You can also include audio and image files as well as class files.

JAR files are particularly helpful when you deal with the Internet. Before JAR files, your Web browser would have to make repeated requests of a Web server in order to download all of the files that make up an applet. In addition, each of these files was uncompressed. By combining all of the files for a particular applet into a single JAR file, only one server request is necessary and the transfer is faster because of compression. And each entry in a JAR file can be digitally signed for security (see Chapter 14 for an example of signing).

A JAR file consists of a single file containing a collection of zipped files along with a "manifest" that describes them. (You can create your own manifest file; otherwise, the jar program will do it for you.) You can find out more about JAR manifests in the JDK documentation.

The jar utility that comes with Sun's JDK automatically compresses the files of your choice. You invoke it on the command line:

jar [options] destination [manifest] inputfile(s)

The options are simply a collection of letters (no hyphen or any other indicator is necessary). Unix/Linux users will note the similarity to the tar options. These are:

If a subdirectory is included in the files to be put into the JAR file, that subdirectory is automatically added, including all of its subdirectories, etc. Path information is also preserved.

Here are some typical ways to invoke jar:

jar cf myJarFile.jar *.class

This creates a JAR file called myJarFile.jar that contains all of the class files in the current directory, along with an automatically generated manifest file.

jar cmf myJarFile.jar myManifestFile.mf *.class

Like the previous example, but adding a user-created manifest file called myManifestFile.mf.

jar tf myJarFile.jar

Produces a table of contents of the files in myJarFile.jar.

jar tvf myJarFile.jar

Adds the "verbose" flag to give more detailed information about the files in myJarFile.jar.

jar cvf myApp.jar audio classes image

Assuming audio, classes, and image are subdirectories, this combines all of the subdirectories into the file myApp.jar. The "verbose" flag is also included to give extra feedback while the jar program is working.

If you create a JAR file using the 0 (zero) option, that file can be placed in your CLASSPATH:

CLASSPATH="lib1.jar;lib2.jar;"

Then Java can search lib1.jar and lib2.jar for class files.

The jar tool isn't as useful as a zip utility. For example, you can't add or update files to an existing JAR file; you can create JAR files only from scratch. Also, you can't move files into a JAR file, erasing them as they are moved. However, a JAR file created on one platform will be transparently readable by the jar tool on any other platform (a problem that sometimes plagues zip utilities).

As you will see in Chapter 14, JAR files are also used to package JavaBeans.

You might wonder what's necessary for an object to be recovered from its serialized state. For example, suppose you serialize an object and send it as a file or through a network to another machine. Could a program on the other machine reconstruct the object using only the contents of the file?

The best way to answer this question is (as usual) by performing an experiment. The following file goes in the subdirectory for this chapter:

//: c12:Alien.java
// A serializable class.
import java.io.*;
public class Alien implements Serializable {} ///:~

The file that creates and serializes an Alien object goes in the same directory:

//: c12:FreezeAlien.java
// Create a serialized output file.
// {Clean: X.file}
import java.io.*;
 
public class FreezeAlien {
	// Throw exceptions to console:
	public static void main(String[] args) throws Exception {
		ObjectOutput out = new ObjectOutputStream(
			new FileOutputStream("X.file"));
		Alien zorcon = new Alien();
		out.writeObject(zorcon);
	}
} ///:~

Rather than catching and handling exceptions, this program takes the quick-and-dirty approach of passing the exceptions out of main( ), so they'll be reported on the console.

Once the program is compiled and run, it produces a file called X.file in the c12 directory. The following code is in a subdirectory called xfiles:

//: c12:xfiles:ThawAlien.java
// Try to recover a serialized file without the
// class of object that's stored in that file.
// {ThrowsException}
import java.io.*;
 
public class ThawAlien {
	public static void main(String[] args) throws Exception {
		ObjectInputStream in = new ObjectInputStream(
			new FileInputStream(new File("..", "X.file")));
		Object mystery = in.readObject();
		System.out.println(mystery.getClass());
	}
} ///:~

Even opening the file and reading in the object mystery requires the Class object for Alien; the JVM cannot find Alien.class (unless it happens to be in the Classpath, which it shouldn't be in this example). You'll get a ClassNotFoundException. (Once again, all evidence of alien life vanishes before proof of its existence can be verified!) The JVM must be able to find the associated .class file.

As you can see, the default serialization mechanism is trivial to use. But what if you have special needs? Perhaps you have special security issues and you don't want to serialize portions of your object, or perhaps it just doesn't make sense for one subobject to be serialized if that part needs to be created anew when the object is recovered.

You can control the process of serialization by implementing the Externalizable interface instead of the Serializable interface. The Externalizable interface extends the Serializable interface and adds two methods, writeExternal( ) and readExternal( ), that are automatically called for your object during serialization and deserialization so that you can perform your special operations.

The following example shows simple implementations of the Externalizable interface methods. Note that Blip1 and Blip2 are nearly identical except for a subtle difference (see if you can discover it by looking at the code):

//: c12:Blips.java
// Simple use of Externalizable & a pitfall.
// {Clean: Blips.out}
import com.bruceeckel.simpletest.*;
import java.io.*;
import java.util.*;
 
class Blip1 implements Externalizable {
	public Blip1() {
		System.out.println("Blip1 Constructor");
	}
	public void writeExternal(ObjectOutput out)
			throws IOException {
		System.out.println("Blip1.writeExternal");
	}
	public void readExternal(ObjectInput in)
			throws IOException, ClassNotFoundException {
		System.out.println("Blip1.readExternal");
	}
}
 
class Blip2 implements Externalizable {
	Blip2() {
		System.out.println("Blip2 Constructor");
	}
	public void writeExternal(ObjectOutput out)
			throws IOException {
		System.out.println("Blip2.writeExternal");
	}
	public void readExternal(ObjectInput in)
			throws IOException, ClassNotFoundException {
		System.out.println("Blip2.readExternal");
	}
}
 
public class Blips {
	private static Test monitor = new Test();
	// Throw exceptions to console:
	public static void main(String[] args)
			throws IOException, ClassNotFoundException {
		System.out.println("Constructing objects:");
		Blip1 b1 = new Blip1();
		Blip2 b2 = new Blip2();
		ObjectOutputStream o = new ObjectOutputStream(
			new FileOutputStream("Blips.out"));
		System.out.println("Saving objects:");
		o.writeObject(b1);
		o.writeObject(b2);
		o.close();
		// Now get them back:
		ObjectInputStream in = new ObjectInputStream(
			new FileInputStream("Blips.out"));
		System.out.println("Recovering b1:");
		b1 = (Blip1)in.readObject();
		// OOPS! Throws an exception:
//! System.out.println("Recovering b2:");
//! b2 = (Blip2)in.readObject();
		monitor.expect(new String[] {
			"Constructing objects:",
			"Blip1 Constructor",
			"Blip2 Constructor",
			"Saving objects:",
			"Blip1.writeExternal",
			"Blip2.writeExternal",
			"Recovering b1:",
			"Blip1 Constructor",
			"Blip1.readExternal"
		});
	}
} ///:~

The reason that the Blip2 object is not recovered is that trying to do so causes an exception. Can you see the difference between Blip1 and Blip2? The constructor for Blip1 is public, while the constructor for Blip2 is not, and that causes the exception upon recovery. Try making Blip2's constructor public and removing the //! comments to see the correct results.

When b1 is recovered, the Blip1 default constructor is called. This is different from recovering a Serializable object, in which the object is constructed entirely from its stored bits, with no constructor calls. With an Externalizable object, all the normal default construction behavior occurs (including the initializations at the point of field definition), and then readExternal( ) is called. You need to be aware of this-in particular, the fact that all the default construction always takes place-to produce the correct behavior in your Externalizable objects.

Here's an example that shows what you must do to fully store and retrieve an Externalizable object:

//: c12:Blip3.java
// Reconstructing an externalizable object.
import com.bruceeckel.simpletest.*;
import java.io.*;
import java.util.*;
 
public class Blip3 implements Externalizable {
	private static Test monitor = new Test();
	private int i;
	private String s; // No initialization
	public Blip3() {
		System.out.println("Blip3 Constructor");
		// s, i not initialized
	}
	public Blip3(String x, int a) {
		System.out.println("Blip3(String x, int a)");
		s = x;
		i = a;
		// s & i initialized only in nondefault constructor.
	}
	public String toString() { return s + i; }
	public void writeExternal(ObjectOutput out)
			throws IOException {
		System.out.println("Blip3.writeExternal");
		// You must do this:
		out.writeObject(s);
		out.writeInt(i);
	}
	public void readExternal(ObjectInput in)
			throws IOException, ClassNotFoundException {
		System.out.println("Blip3.readExternal");
		// You must do this:
		s = (String)in.readObject();
		i = in.readInt();
	}
	public static void main(String[] args)
			throws IOException, ClassNotFoundException {
		System.out.println("Constructing objects:");
		Blip3 b3 = new Blip3("A String ", 47);
		System.out.println(b3);
		ObjectOutputStream o = new ObjectOutputStream(
			new FileOutputStream("Blip3.out"));
		System.out.println("Saving object:");
		o.writeObject(b3);
		o.close();
		// Now get it back:
		ObjectInputStream in = new ObjectInputStream(
			new FileInputStream("Blip3.out"));
		System.out.println("Recovering b3:");
		b3 = (Blip3)in.readObject();
		System.out.println(b3);
		monitor.expect(new String[] {
			"Constructing objects:",
			"Blip3(String x, int a)",
			"A String 47",
			"Saving object:",
			"Blip3.writeExternal",
			"Recovering b3:",
			"Blip3 Constructor",
			"Blip3.readExternal",
			"A String 47"
		});
	}
} ///:~

The fields s and i are initialized only in the second constructor, but not in the default constructor. This means that if you don't initialize s and i in readExternal( ), s will be null and i will be zero (since the storage for the object gets wiped to zero in the first step of object creation). If you comment out the two lines of code following the phrases "You must do this" and run the program, you'll see that when the object is recovered, s is null and i is zero.

If you are inheriting from an Externalizable object, you'll typically call the base-class versions of writeExternal( ) and readExternal( ) to provide proper storage and retrieval of the base-class components.

So to make things work correctly you must not only write the important data from the object during the writeExternal( ) method (there is no default behavior that writes any of the member objects for an Externalizable object), but you must also recover that data in the readExternal( ) method. This can be a bit confusing at first because the default construction behavior for an Externalizable object can make it seem like some kind of storage and retrieval takes place automatically. It does not.

12-11-2-1. The transient keyword▲

//: c12:Logon.java
// Demonstrates the "transient" keyword.
// {Clean: Logon.out}
import java.io.*;
import java.util.*;
 
public class Logon implements Serializable {
	private Date date = new Date();
	private String username;
	private transient String password;
	public Logon(String name, String pwd) {
		username = name;
		password = pwd;
	}
	public String toString() {
		String pwd = (password == null) ? "(n/a)" : password;
		return "logon info: \n   username: " + username +
			"\n   date: " + date + "\n   password: " + pwd;
	}
	public static void main(String[] args) throws Exception {
		Logon a = new Logon("Hulk", "myLittlePony");
		System.out.println( "logon a = " + a);
		ObjectOutputStream o = new ObjectOutputStream(
			new FileOutputStream("Logon.out"));
		o.writeObject(a);
		o.close();
		Thread.sleep(1000); // Delay for 1 second
		// Now get them back:
		ObjectInputStream in = new ObjectInputStream(
			new FileInputStream("Logon.out"));
		System.out.println("Recovering object at "+new Date());
		a = (Logon)in.readObject();
		System.out.println("logon a = " + a);
	}
} ///:~

logon a = logon info:
	username: Hulk
	date: Mon Oct 21 12:10:13 MDT 2002
	password: myLittlePony
Recovering object at Mon Oct 21 12:10:14 MDT 2002
logon a = logon info:
	username: Hulk
	date: Mon Oct 21 12:10:13 MDT 2002
	password: (n/a)

12-11-2-2. An alternative to Externalizable▲

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

//: c12:SerialCtl.java
// Controlling serialization by adding your own
// writeObject() and readObject() methods.
import com.bruceeckel.simpletest.*;
import java.io.*;
 
public class SerialCtl implements Serializable {
	private static Test monitor = new Test();
	private String a;
	private transient String b;
	public SerialCtl(String aa, String bb) {
		a = "Not Transient: " + aa;
		b = "Transient: " + bb;
	}
	public String toString() { return a + "\n" + b; }
	private void writeObject(ObjectOutputStream stream)
			throws IOException {
		stream.defaultWriteObject();
		stream.writeObject(b);
	}
	private void readObject(ObjectInputStream stream)
			throws IOException, ClassNotFoundException {
		stream.defaultReadObject();
		b = (String)stream.readObject();
	}
	public static void main(String[] args)
			throws IOException, ClassNotFoundException {
		SerialCtl sc = new SerialCtl("Test1", "Test2");
		System.out.println("Before:\n" + sc);
		ByteArrayOutputStream buf= new ByteArrayOutputStream();
		ObjectOutputStream o = new ObjectOutputStream(buf);
		o.writeObject(sc);
		// Now get it back:
		ObjectInputStream in = new ObjectInputStream(
			new ByteArrayInputStream(buf.toByteArray()));
		SerialCtl sc2 = (SerialCtl)in.readObject();
		System.out.println("After:\n" + sc2);
		monitor.expect(new String[] {
			"Before:",
			"Not Transient: Test1",
			"Transient: Test2",
			"After:",
			"Not Transient: Test1",
			"Transient: Test2"
		});
	}
} ///:~

o.writeObject(sc);

12-11-2-3. Versioning▲

It's quite appealing to use serialization technology to store some of the state of your program so that you can easily restore the program to the current state later. But before you can do this, some questions must be answered. What happens if you serialize two objects that both have a reference to a third object? When you restore those two objects from their serialized state, do you get only one occurrence of the third object? What if you serialize your two objects to separate files and deserialize them in different parts of your code?

Here's an example that shows the problem:

//: c12:MyWorld.java
import java.io.*;
import java.util.*;
 
class House implements Serializable {}
 
class Animal implements Serializable {
	private String name;
	private House preferredHouse;
	Animal(String nm, House h) {
		name = nm;
		preferredHouse = h;
	}
	public String toString() {
		return name + "[" + super.toString() +
			"], " + preferredHouse + "\n";
	}
}
 
public class MyWorld {
	public static void main(String[] args)
			throws IOException, ClassNotFoundException {
		House house = new House();
		List animals = new ArrayList();
		animals.add(new Animal("Bosco the dog", house));
		animals.add(new Animal("Ralph the hamster", house));
		animals.add(new Animal("Fronk the cat", house));
		System.out.println("animals: " + animals);
		ByteArrayOutputStream buf1 =
			new ByteArrayOutputStream();
		ObjectOutputStream o1 = new ObjectOutputStream(buf1);
		o1.writeObject(animals);
		o1.writeObject(animals); // Write a 2nd set
		// Write to a different stream:
		ByteArrayOutputStream buf2 =
			new ByteArrayOutputStream();
		ObjectOutputStream o2 = new ObjectOutputStream(buf2);
		o2.writeObject(animals);
		// Now get them back:
		ObjectInputStream in1 = new ObjectInputStream(
			new ByteArrayInputStream(buf1.toByteArray()));
		ObjectInputStream in2 = new ObjectInputStream(
			new ByteArrayInputStream(buf2.toByteArray()));
		List
			animals1 = (List)in1.readObject(),
			animals2 = (List)in1.readObject(),
			animals3 = (List)in2.readObject();
		System.out.println("animals1: " + animals1);
		System.out.println("animals2: " + animals2);
		System.out.println("animals3: " + animals3);
	}
} ///:~

One thing that's interesting here is that it's possible to use object serialization to and from a byte array as a way of doing a "deep copy" of any object that's Serializable. (A deep copy means that you're duplicating the entire web of objects, rather than just the basic object and its references.) Object copying is covered in depth in Appendix A.

Animal objects contain fields of type House. In main( ), a List of these Animals is created and it is serialized twice to one stream and then again to a separate stream. When these are deserialized and printed, you see the following results for one run (the objects will be in different memory locations each run):

animals: [Bosco the dog[Animal@1cde100], House@16f0472
, Ralph the hamster[Animal@18d107f], House@16f0472
, Fronk the cat[Animal@360be0], House@16f0472
]
animals1: [Bosco the dog[Animal@e86da0], House@1754ad2
, Ralph the hamster[Animal@1833955], House@1754ad2
, Fronk the cat[Animal@291aff], House@1754ad2
]
animals2: [Bosco the dog[Animal@e86da0], House@1754ad2
, Ralph the hamster[Animal@1833955], House@1754ad2
, Fronk the cat[Animal@291aff], House@1754ad2
]
animals3: [Bosco the dog[Animal@ab95e6], House@fe64b9
, Ralph the hamster[Animal@186db54], House@fe64b9
, Fronk the cat[Animal@a97b0b], House@fe64b9
]

Of course you expect that the deserialized objects have different addresses from their originals. But notice that in animals1 and animals2, the same addresses appear, including the references to the House object that both share. On the other hand, when animals3 is recovered, the system has no way of knowing that the objects in this other stream are aliases of the objects in the first stream, so it makes a completely different web of objects.

As long as you're serializing everything to a single stream, you'll be able to recover the same web of objects that you wrote, with no accidental duplication of objects. Of course, you can change the state of your objects in between the time you write the first and the last, but that's your responsibility; the objects will be written in whatever state they are in (and with whatever connections they have to other objects) at the time you serialize them.

The safest thing to do if you want to save the state of a system is to serialize as an "atomic" operation. If you serialize some things, do some other work, and serialize some more, etc., then you will not be storing the system safely. Instead, put all the objects that comprise the state of your system in a single container and simply write that container out in one operation. Then you can restore it with a single method call as well.

The following example is an imaginary computer-aided design (CAD) system that demonstrates the approach. In addition, it throws in the issue of static fields; if you look at the JDK documentation you'll see that Class is Serializable, so it should be easy to store the static fields by simply serializing the Class object. That seems like a sensible approach, anyway.

//: c12:CADState.java
// Saving and restoring the state of a pretend CAD system.
// {Clean: CADState.out}
//package c12;
import java.io.*;
import java.util.*;
 
abstract class Shape implements Serializable {
	public static final int RED = 1, BLUE = 2, GREEN = 3;
	private int xPos, yPos, dimension;
	private static Random r = new Random();
	private static int counter = 0;
	public abstract void setColor(int newColor);
	public abstract int getColor();
	public Shape(int xVal, int yVal, int dim) {
		xPos = xVal;
		yPos = yVal;
		dimension = dim;
	}
	public String toString() {
		return getClass() +
			"color[" + getColor() + "] xPos[" + xPos +
			"] yPos[" + yPos + "] dim[" + dimension + "]\n";
	}
	public static Shape randomFactory() {
		int xVal = r.nextInt(100);
		int yVal = r.nextInt(100);
		int dim = r.nextInt(100);
		switch(counter++ % 3) {
			default:
			case 0: return new Circle(xVal, yVal, dim);
			case 1: return new Square(xVal, yVal, dim);
			case 2: return new Line(xVal, yVal, dim);
		}
	}
}
 
class Circle extends Shape {
	private static int color = RED;
	public Circle(int xVal, int yVal, int dim) {
		super(xVal, yVal, dim);
	}
	public void setColor(int newColor) { color = newColor; }
	public int getColor() { return color; }
}
 
class Square extends Shape {
	private static int color;
	public Square(int xVal, int yVal, int dim) {
		super(xVal, yVal, dim);
		color = RED;
	}
	public void setColor(int newColor) { color = newColor; }
	public int getColor() { return color; }
}
 
class Line extends Shape {
	private static int color = RED;
	public static void
	serializeStaticState(ObjectOutputStream os)
	throws IOException { os.writeInt(color); }
	public static void
	deserializeStaticState(ObjectInputStream os)
	throws IOException { color = os.readInt(); }
	public Line(int xVal, int yVal, int dim) {
		super(xVal, yVal, dim);
	}
	public void setColor(int newColor) { color = newColor; }
	public int getColor() { return color; }
}
 
public class CADState {
	public static void main(String[] args) throws Exception {
		List shapeTypes, shapes;
		if(args.length == 0) {
			shapeTypes = new ArrayList();
			shapes = new ArrayList();
			// Add references to the class objects:
			shapeTypes.add(Circle.class);
			shapeTypes.add(Square.class);
			shapeTypes.add(Line.class);
			// Make some shapes:
			for(int i = 0; i < 10; i++)
				shapes.add(Shape.randomFactory());
			// Set all the static colors to GREEN:
			for(int i = 0; i < 10; i++)
				((Shape)shapes.get(i)).setColor(Shape.GREEN);
			// Save the state vector:
			ObjectOutputStream out = new ObjectOutputStream(
				new FileOutputStream("CADState.out"));
			out.writeObject(shapeTypes);
			Line.serializeStaticState(out);
			out.writeObject(shapes);
		} else { // There's a command-line argument
			ObjectInputStream in = new ObjectInputStream(
				new FileInputStream(args[0]));
			// Read in the same order they were written:
			shapeTypes = (List)in.readObject();
			Line.deserializeStaticState(in);
			shapes = (List)in.readObject();
		}
		// Display the shapes:
		System.out.println(shapes);
	}
} ///:~

The Shape class implements Serializable, so anything that is inherited from Shape is automatically Serializable as well. Each Shape contains data, and each derived Shape class contains a static field that determines the color of all of those types of Shapes. (Placing a static field in the base class would result in only one field, since static fields are not duplicated in derived classes.) Methods in the base class can be overridden to set the color for the various types (static methods are not dynamically bound, so these are normal methods). The randomFactory( ) method creates a different Shape each time you call it, using random values for the Shape data.

Circle and Square are straightforward extensions of Shape; the only difference is that Circle initializes color at the point of definition and Square initializes it in the constructor. We'll leave the discussion of Line for later.

In main( ), one ArrayList is used to hold the Class objects and the other to hold the shapes. If you don't provide a command-line argument, the shapeTypes ArrayList is created and the Class objects are added, and then the shapes ArrayList is created and Shape objects are added. Next, all the static color values are set to GREEN, and everything is serialized to the file CADState.out.

If you provide a command-line argument (presumably CADState.out), that file is opened and used to restore the state of the program. In both situations, the resulting ArrayList of Shapes is printed. The results from one run are:

$ java CADState
[class Circlecolor[3] xPos[71] yPos[82] dim[44]
, class Squarecolor[3] xPos[98] yPos[21] dim[49]
, class Linecolor[3] xPos[16] yPos[80] dim[37]
, class Circlecolor[3] xPos[51] yPos[74] dim[7]
, class Squarecolor[3] xPos[7] yPos[78] dim[98]
, class Linecolor[3] xPos[38] yPos[79] dim[93]
, class Circlecolor[3] xPos[84] yPos[12] dim[62]
, class Squarecolor[3] xPos[16] yPos[51] dim[94]
, class Linecolor[3] xPos[51] yPos[0] dim[73]
, class Circlecolor[3] xPos[47] yPos[6] dim[49]
]
 
$ java CADState CADState.out
[class Circlecolor[1] xPos[71] yPos[82] dim[44]
, class Squarecolor[0] xPos[98] yPos[21] dim[49]
, class Linecolor[3] xPos[16] yPos[80] dim[37]
, class Circlecolor[1] xPos[51] yPos[74] dim[7]
, class Squarecolor[0] xPos[7] yPos[78] dim[98]
, class Linecolor[3] xPos[38] yPos[79] dim[93]
, class Circlecolor[1] xPos[84] yPos[12] dim[62]
, class Squarecolor[0] xPos[16] yPos[51] dim[94]
, class Linecolor[3] xPos[51] yPos[0] dim[73]
, class Circlecolor[1] xPos[47] yPos[6] dim[49]
]

You can see that the values of xPos, yPos, and dim were all stored and recovered successfully, but there's something wrong with the retrieval of the static information. It's all "3" going in, but it doesn't come out that way. Circles have a value of 1 (RED, which is the definition), and Squares have a value of 0 (remember, they are initialized in the constructor). It's as if the statics didn't get serialized at all! That's right-even though class Class is Serializable, it doesn't do what you expect. So if you want to serialize statics, you must do it yourself.

This is what the serializeStaticState( ) and deserializeStaticState( ) static methods in Line are for. You can see that they are explicitly called as part of the storage and retrieval process. (Note that the order of writing to the serialize file and reading back from it must be maintained.) Thus to make CADState.java run correctly, you must:

• Add a serializeStaticState( ) and deserializeStaticState( ) to the shapes.
• Remove the ArrayList shapeTypes and all code related to it.
• Add calls to the new serialize and deserialize static methods in the shapes.

Another issue you might have to think about is security, since serialization also saves private data. If you have a security issue, those fields should be marked as transient. But then you have to design a secure way to store that information so that when you do a restore you can reset those private variables.

You can begin learning regular expressions with a useful subset of the possible constructs. A complete list of constructs for building regular expressions can be found in the javadocs for the Pattern class for package java.util.regex.

The power of regular expressions begins to appear when defining character classes. Here are some typical ways to create character classes, and some predefined classes:

If you have any experience with regular expressions in other languages, you'll immediately notice a difference in the way backslashes are handled. In other languages, "\\" means "I want to insert a plain old (literal) backslash in the regular expression. Don't give it any special meaning." In Java, "\\" means "I'm inserting a regular expression backslash, so the following character has special meaning." For example, if you want to indicate one or more word characters, your regular expression string will be "\\w+". If you want to insert a literal backslash, you say "\\\\". However, things like newlines and tabs just use a single backslash: "\n\t".

What's shown here is only a sampling; you'll want to have the java.util.regex.Pattern JDK documentation page bookmarked or on your "Start" menu so you can easily access all the possible regular expression patterns.

As an example, each of the following represent valid regular expressions, and all will successfully match the character sequence "Rudolph":

Rudolph
[rR]udolph
[rR][aeiou][a-z]ol.*
R.*

A quantifier describes the way that a pattern absorbs input text:

• Greedy: Quantifiers are greedy unless otherwise altered. A greedy expression finds as many possible matches for the pattern as possible. A typical cause of problems is to assume that your pattern will only match the first possible group of characters, when it's actually greedy and will keep going.
• Reluctant: Specified with a question mark, this quantifier matches the minimum necessary number of characters to satisfy the pattern. Also called lazy, minimal matching, non-greedy,or ungreedy.
• Possessive: Currently only available in Java (not in other languages), and it is more advanced, so you probably won't use it right away. As a regular expression is applied to a string, it generates many states so that it can backtrack if the match fails. Possessive quantifiers do not keep those intermediate states, and thus prevent backtracking. They can be used to prevent a regular expression from running away and also to make it execute more efficiently.

You should be very aware that the expression 'X' will often need to be surrounded in parentheses for it to work the way you desire. For example:

abc+

Might seem like it would match the sequence 'abc' one or more times, and if you apply it to the input string 'abcabcabc', you will in fact get three matches. However, the expression actually says "match 'ab' followed by one or more occurrences of 'c'." To match the entire string 'abc' one or more times, you must say:

(abc)+

You can easily be fooled when using regular expressions; it's a new language, on top of Java.

12-13-2-1. CharSequence▲

interface CharSequence {
	charAt(int i);
	length();
	subSequence(int start, int end);
	toString();
}

As a first example, the following class can be used to test regular expressions against an input string. The first argument is the input string to match against, followed by one or more regular expressions to be applied to the input. Under Unix/Linux, the regular expressions must be quoted on the command line.

This program can be useful in testing regular expressions as you construct them to see that they produce your intended matching behavior.

//: c12:TestRegularExpression.java
// Allows you to easly try out regular expressions.
// {Args: abcabcabcdefabc "abc+" "(abc)+" "(abc){2,}" }
import java.util.regex.*;
 
public class TestRegularExpression {
	public static void main(String[] args) {
		if(args.length < 2) {
			System.out.println("Usage:\n" +
				"java TestRegularExpression " +
				"characterSequence regularExpression+");
			System.exit(0);
		}
		System.out.println("Input: \"" + args[0] + "\"");
		for(int i = 1; i < args.length; i++) {
			System.out.println(
				"Regular expression: \"" + args[i] + "\"");
			Pattern p = Pattern.compile(args[i]);
			Matcher m = p.matcher(args[0]);
			while(m.find()) {
				System.out.println("Match \"" + m.group() +
					"\" at positions " +
					m.start() + "-" + (m.end() - 1));
			}
		}
	}
} ///:~

Regular expressions are implemented in Java through the Pattern and Matcher classes in the package java.util.regex. A Pattern object represents a compiled version of a regular expression. The static compile( ) method compiles a regular expression string into a Pattern object. As seen in the preceding example, you can use the matcher( ) method and the input string to produce a Matcher object from the compiled Pattern object. Pattern also has a

static boolean ( regex,  input)

for quickly discerning if regex can be found in input, and a split( ) method that produces an array of String that has been broken around matches of the regex.

A Matcher object is generated by calling Pattern.matcher( ) with the input string as an argument. The Matcher object is then used to access the results, using methods to evaluate the success or failure of different types of matches:

boolean matches()
boolean lookingAt()
boolean find()
boolean find(int start)

The matches( ) method is successful if the pattern matches the entire input string, while lookingAt( ) is successful if the input string, starting at the beginning, is a match to the pattern.

12-13-3-1. find( )▲

//: c12:FindDemo.java
import java.util.regex.*;
import com.bruceeckel.simpletest.*;
import java.util.*;
 
public class FindDemo {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		Matcher m = Pattern.compile("\\w+")
			.matcher("Evening is full of the linnet's wings");
		while(m.find())
			System.out.println(m.group());
		int i = 0;
		while(m.find(i)) {
			System.out.print(m.group() + " ");
			i++;
		}
		monitor.expect(new String[] {
			"Evening",
			"is",
			"full",
			"of",
			"the",
			"linnet",
			"s",
			"wings",
			"Evening vening ening ning ing ng g is is s full " +
			"full ull ll l of of f the the he e linnet linnet " +
			"innet nnet net et t s s wings wings ings ngs gs s "
		});
	}
} ///:~

12-13-3-2. Groups▲

A(B(C))D

//: c12:Groups.java
import java.util.regex.*;
import com.bruceeckel.simpletest.*;
 
public class Groups {
	private static Test monitor = new Test();
	static public final String poem =
		"Twas brillig, and the slithy toves\n" +
		"Did gyre and gimble in the wabe.\n" +
		"All mimsy were the borogoves,\n" +
		"And the mome raths outgrabe.\n\n" +
		"Beware the Jabberwock, my son,\n" +
		"The jaws that bite, the claws that catch.\n" +
		"Beware the Jubjub bird, and shun\n" +
		"The frumious Bandersnatch.";
	public static void main(String[] args) {
		Matcher m =
			Pattern.compile("(?m)(\\S+)\\s+((\\S+)\\s+(\\S+))$")
				.matcher(poem);
		while(m.find()) {
			for(int j = 0; j <= m.groupCount(); j++)
				System.out.print("[" + m.group(j) + "]");
			System.out.println();
		}
		monitor.expect(new String[]{
			"[the slithy toves]" +
			"[the][slithy toves][slithy][toves]",
			"[in the wabe.][in][the wabe.][the][wabe.]",
			"[were the borogoves,]" +
			"[were][the borogoves,][the][borogoves,]",
			"[mome raths outgrabe.]" +
			"[mome][raths outgrabe.][raths][outgrabe.]",
			"[Jabberwock, my son,]" +
			"[Jabberwock,][my son,][my][son,]",
			"[claws that catch.]" +
			"[claws][that catch.][that][catch.]",
			"[bird, and shun][bird,][and shun][and][shun]",
			"[The frumious Bandersnatch.][The]" +
			"[frumious Bandersnatch.][frumious][Bandersnatch.]"
		});
	}
} ///:~

12-13-3-3. start( ) and end( )▲

//: c12:StartEnd.java
import java.util.regex.*;
import com.bruceeckel.simpletest.*;
 
public class StartEnd {
	private static Test monitor = new Test();
	public static void main(String[] args) {
		String[] input = new String[] {
			"Java has regular expressions in 1.4",
			"regular expressions now expressing in Java",
			"Java represses oracular expressions"
		};
		Pattern
			p1 = Pattern.compile("re\\w*"),
			p2 = Pattern.compile("Java.*");
		for(int i = 0; i < input.length; i++) {
			System.out.println("input " + i + ": " + input[i]);
			Matcher
				m1 = p1.matcher(input[i]),
				m2 = p2.matcher(input[i]);
			while(m1.find())
				System.out.println("m1.find() '" + m1.group() +
					"' start = "+ m1.start() + " end = " + m1.end());
			while(m2.find())
				System.out.println("m2.find() '" + m2.group() +
					"' start = "+ m2.start() + " end = " + m2.end());
			if(m1.lookingAt()) // No reset() necessary
				System.out.println("m1.lookingAt() start = "
					+ m1.start() + " end = " + m1.end());
			if(m2.lookingAt())
				System.out.println("m2.lookingAt() start = "
					+ m2.start() + " end = " + m2.end());
			if(m1.matches()) // No reset() necessary
				System.out.println("m1.matches() start = "
					+ m1.start() + " end = " + m1.end());
			if(m2.matches())
				System.out.println("m2.matches() start = "
					+ m2.start() + " end = " + m2.end());
		}
		monitor.expect(new String[] {
			"input 0: Java has regular expressions in 1.4",
			"m1.find() 'regular' start = 9 end = 16",
			"m1.find() 'ressions' start = 20 end = 28",
			"m2.find() 'Java has regular expressions in 1.4'" +
			" start = 0 end = 35",
			"m2.lookingAt() start = 0 end = 35",
			"m2.matches() start = 0 end = 35",
			"input 1: regular expressions now " +
			"expressing in Java",
			"m1.find() 'regular' start = 0 end = 7",
			"m1.find() 'ressions' start = 11 end = 19",
			"m1.find() 'ressing' start = 27 end = 34",
			"m2.find() 'Java' start = 38 end = 42",
			"m1.lookingAt() start = 0 end = 7",
			"input 2: Java represses oracular expressions",
			"m1.find() 'represses' start = 5 end = 14",
			"m1.find() 'ressions' start = 27 end = 35",
			"m2.find() 'Java represses oracular expressions' " +
			"start = 0 end = 35",
			"m2.lookingAt() start = 0 end = 35",
			"m2.matches() start = 0 end = 35"
		});
	}
} ///:~