Object Streams
| Using a fixed-length record format is a good choice if you need to store data of the same type. However, objects that you create in an object-oriented program are rarely all of the same type. For example, you may have an array called staff that is nominally an array of Employee records but contains objects that are actually instances of a subclass such as Manager. If we want to save files that contain this kind of information, we must first save the type of each object and then the data that define the current state of the object. When we read this information back from a file, we must
It is entirely possible (if very tedious) to do this by hand, and in the first edition of this book we did exactly this. However, Sun Microsystems developed a powerful mechanism that allows this to be done with much less effort. As you will soon see, this mechanism, called object serialization, almost completely automates what was previously a very tedious process. (You see later in this chapter where the term "serialization" comes from.) Storing Objects of Variable TypeTo save object data, you first need to open an ObjectOutputStream object: ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream("employee.dat")); Now, to save an object, you simply use the writeObject method of the ObjectOutputStream class as in the following fragment: Employee harry = new Employee("Harry Hacker", 50000, 1989, 10, 1); Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15); out.writeObject(harry); out.writeObject(boss); To read the objects back in, first get an ObjectInputStream object: ObjectInputStream in = new ObjectInputStream(new FileInputStream("employee.dat")); Then, retrieve the objects in the same order in which they were written, using the readObject method. Employee e1 = (Employee) in.readObject(); Employee e2 = (Employee) in.readObject(); When reading back objects, you must carefully keep track of the number of objects that were saved, their order, and their types. Each call to readObject reads in another object of the type Object. You therefore will need to cast it to its correct type. If you don't need the exact type or you don't remember it, then you can cast it to any superclass or even leave it as type Object. For example, e2 is an Employee object variable even though it actually refers to a Manager object. If you need to dynamically query the type of the object, you can use the getClass method that we described in Chapter 5. You can write and read only objects with the writeObject/readObject methods. For primitive type values, you use methods such as writeInt/readInt or writeDouble/readDouble. (The object stream classes implement the DataInput/DataOutput interfaces.) Of course, numbers inside objects (such as the salary field of an Employee object) are saved and restored automatically. Recall that, in Java, strings and arrays are objects and can, therefore, be processed with the writeObject/readObject methods. There is, however, one change you need to make to any class that you want to save and restore in an object stream. The class must implement the Serializable interface: class Employee implements Serializable { . . . } The Serializable interface has no methods, so you don't need to change your classes in any way. In this regard, it is similar to the Cloneable interface that we also discussed in Chapter 6. However, to make a class cloneable, you still had to override the clone method of the Object class. To make a class serializable, you do not need to do anything else. Example 12-4 is a test program that writes an array containing two employees and one manager to disk and then restores it. Writing an array is done with a single operation: Employee[] staff = new Employee[3]; . . . out.writeObject(staff); Similarly, reading in the result is done with a single operation. However, we must apply a cast to the return value of the readObject method: Employee[] newStaff = (Employee[]) in.readObject(); Once the information is restored, we print each employee because you can easily distinguish employee and manager objects by their different toString results. This should convince you that we did restore the correct types. Example 12-4. ObjectFileTest.java 1. import java.io.*; 2. import java.util.*; 3. 4. class ObjectFileTest 5. { 6. public static void main(String[] args) 7. { 8. Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15); 9. boss.setBonus(5000); 10. 11. Employee[] staff = new Employee[3]; 12. 13. staff[0] = boss; 14. staff[1] = new Employee("Harry Hacker", 50000, 1989, 10, 1); 15. staff[2] = new Employee("Tony Tester", 40000, 1990, 3, 15); 16. 17. try 18. { 19. // save all employee records to the file employee.dat 20. ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream java.io.ObjectOutputStream 1.1
java.io.ObjectInputStream 1.1
Understanding the Object Serialization File FormatObject serialization saves object data in a particular file format. Of course, you can use the writeObject/readObject methods without having to know the exact sequence of bytes that represents objects in a file. Nonetheless, we found studying the data format to be extremely helpful for gaining insight into the object streaming process. We did this by looking at hex dumps of various saved object files. However, the details are somewhat technical, so feel free to skip this section if you are not interested in the implementation. Every file begins with the two-byte "magic number" AC ED followed by the version number of the object serialization format, which is currently 00 05 (We use hexadecimal numbers throughout this section to denote bytes.) Then, it contains a sequence of objects, in the order that they were saved. String objects are saved as
For example, the string "Harry" is saved as 74 00 05 Harry The Unicode characters of the string are saved in "modified UTF-8" format. When an object is saved, the class of that object must be saved as well. The class description contains
Java gets the fingerprint by
SHA is a fast algorithm that gives a "fingerprint" to a larger block of information. This fingerprint is always a 20-byte data packet, regardless of the size of the original data. It is created by a clever sequence of bit operations on the data that makes it essentially 100 percent certain that the fingerprint will change if the information is altered in any way. SHA is a U.S. standard, recommended by the National Institute for Science and Technology (NIST). (For more details on SHA, see, for example, Cryptography and Network Security: Principles and Practice, by William Stallings [Prentice Hall, 2002].) However, Java uses only the first 8 bytes of the SHA code as a class fingerprint. It is still very likely that the class fingerprint will change if the data fields or methods change in any way. Java can then check the class fingerprint to protect us from the following scenario: An object is saved to a disk file. Later, the designer of the class makes a change, for example, by removing a data field. Then, the old disk file is read in again. Now the data layout on the disk no longer matches the data layout in memory. If the data were read back in its old form, it could corrupt memory. Java takes great care to make such memory corruption close to impossible. Hence, it checks, using the fingerprint, that the class definition has not changed when it restores an object. It does this by comparing the fingerprint on disk with the fingerprint of the current class. NOTE
Here is how a class identifier is stored:
The flag byte is composed of three bit masks, defined in java.io.ObjectStreamConstants: static final byte SC_WRITE_METHOD = 1; // class has writeObject method that writes additional data static final byte SC_SERIALIZABLE = 2; // class implements Serializable interface static final byte SC_EXTERNALIZABLE = 4; // class implements Externalizable interface We discuss the Externalizable interface later in this chapter. Externalizable classes supply custom read and write methods that take over the output of their instance fields. The classes that we write implement the Serializable interface and will have a flag value of 02. The java.util.Date class defines its own readObject/writeObject methods and has a flag of 03. Each data field descriptor has the format:
The type code is one of the following:
When the type code is L, the field name is followed by the field type. Class and field name strings do not start with the string code 74, but field types do. Field types use a slightly different encoding of their names, namely, the format used by native methods. (See Volume 2 for native methods.) For example, the salary field of the Employee class is encoded as: D 00 06 salary Here is the complete class descriptor of the Employee class:
These descriptors are fairly long. If the same class descriptor is needed again in the file, then an abbreviated form is used:
The serial number refers to the previous explicit class descriptor. We discuss the numbering scheme later. An object is stored as
For example, here is how an Employee object is stored:
As you can see, the data file contains enough information to restore the Employee object. Arrays are saved in the following format:
The array class name in the class descriptor is in the same format as that used by native methods (which is slightly different from the class name used by class names in other class descriptors). In this format, class names start with an L and end with a semicolon. For example, an array of three Employee objects starts out like this:
Note that the fingerprint for an array of Employee objects is different from a fingerprint of the Employee class itself. Of course, studying these codes can be about as exciting as reading the average phone book. But it is still instructive to know that the object stream contains a detailed description of all the objects that it contains, with sufficient detail to allow reconstruction of both objects and arrays of objects. Solving the Problem of Saving Object ReferencesWe now know how to save objects that contain numbers, strings, or other simple objects. However, there is one important situation that we still need to consider. What happens when one object is shared by several objects as part of its state? To illustrate the problem, let us make a slight modification to the Manager class. Let's assume that each manager has a secretary, implemented as an instance variable secretary of type Employee. (It would make sense to derive a class Secretary from Employee for this purpose, but we don't do that here.) class Manager extends Employee { . . . private Employee secretary; } Having done this, you must keep in mind that the Manager object now contains a reference to the Employee object that describes the secretary, not a separate copy of the object. In particular, two managers can share the same secretary, as is the case in Figure 12-6 and the following code: harry = new Employee("Harry Hacker", . . .); Manager carl = new Manager("Carl Cracker", . . .); carl.setSecretary(harry); Manager tony = new Manager("Tony Tester", . . .); tony.setSecretary(harry); Now, suppose we write the employee data to disk. What we don't want is for the Manager to save its information according to the following logic:
Then, the data for harry would be saved three times. When reloaded, the objects would have the configuration shown in Figure 12-7. Figure 12-7. Here, Harry is saved three times
This is not what we want. Suppose the secretary gets a raise. We would not want to hunt for all other copies of that object and apply the raise as well. We want to save and restore only one copy of the secretary. To do this, we must copy and restore the original references to the objects. In other words, we want the object layout on disk to be exactly like the object layout in memory. This is called persistence in object-oriented circles. Of course, we cannot save and restore the memory addresses for the secretary objects. When an object is reloaded, it will likely occupy a completely different memory address than it originally did. Figure 12-6. Two managers can share a mutual employee Instead, Java uses a serialization approach. Hence, the name object serialization for this mechanism. Here is the algorithm:
When reading back the objects, simply reverse the procedure. For each object that you load, note its sequence number and remember where you put it in memory. When you encounter the tag "same as previously saved object with serial number x," you look up where you put the object with serial number x and set the object reference to that memory address. Note that the objects need not be saved in any particular order. Figure 12-9 shows what happens when a manager occurs first in the staff array. Figure 12-9. Objects saved in random order All of this sounds confusing, and it is. Fortunately, when object streams are used, the process is also completely automatic. Object streams assign the serial numbers and keep track of duplicate objects. The exact numbering scheme is slightly different from that used in the figures see the next section. NOTE
Example 12-5 is a program that saves and reloads a network of Employee and Manager objects (some of which share the same employee as a secretary). Note that the secretary object is unique after reloading when newStaff[1] gets a raise, that is reflected in the secretary fields of the managers. Example 12-5. ObjectRefTest.java 1. import java.io.*; 2. import java.util.*; 3. 4. class ObjectRefTest 5. { 6. public static void main(String[] args) 7. { 8. Employee harry = new Employee("Harry Hacker", 50000, 1989, 10, 1); 9. Manager boss = new Manager("Carl Cracker", 80000, 1987, 12, 15); 10. boss.setSecretary(harry); 11. 12. Employee[] staff = new Employee[3]; 13. 14. staff[0] = boss; 15. staff[1] = harry; 16. staff[2] = new Employee("Tony Tester", 40000, 1990, 3, 15); 17. 18. try 19. { 20. // save all employee records to the file employee.dat 21. ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream Understanding the Output Format for Object ReferencesThis section continues the discussion of the output format of object streams. If you skipped the previous discussion, you should skip this section as well. All objects (including arrays and strings) and all class descriptors are given serial numbers as they are saved in the output file. This process is referred to as serialization because every saved object is assigned a serial number. (The count starts at 00 7E 00 00.) We already saw that a full class descriptor for any given class occurs only once. Subsequent descriptors refer to it. For example, in our previous example, a repeated reference to the Date class was coded as 71 00 7E 00 08 The same mechanism is used for objects. If a reference to a previously saved object is written, it is saved in exactly the same way, that is, 71 followed by the serial number. It is always clear from the context whether the particular serial reference denotes a class descriptor or an object. Finally, a null reference is stored as 70 Here is the commented output of the ObjectRefTest program of the preceding section. If you like, run the program, look at a hex dump of its data file employee.dat, and compare it with the commented listing. The important lines toward the end of the output show the reference to a previously saved object.
It is usually not important to know the exact file format (unless you are trying to create an evil effect by modifying the data). What you should remember is this:
Modifying the Default Serialization MechanismCertain data fields should never be serialized, for example, integer values that store file handles or handles of windows that are only meaningful to native methods. Such information is guaranteed to be useless when you reload an object at a later time or transport it to a different machine. In fact, improper values for such fields can actually cause native methods to crash. Java has an easy mechanism to prevent such fields from ever being serialized. Mark them with the keyword TRansient. You also need to tag fields as TRansient if they belong to nonserializable classes. Transient fields are always skipped when objects are serialized. The serialization mechanism provides a way for individual classes to add validation or any other desired action to the default read and write behavior. A serializable class can define methods with the signature private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException; private void writeObject(ObjectOutputStream out) throws IOException; Then, the data fields are no longer automatically serialized, and these methods are called instead. Here is a typical example. A number of classes in the java.awt.geom package, such as Point2D.Double, are not serializable. Now suppose you want to serialize a class LabeledPoint that stores a String and a Point2D.Double. First, you need to mark the Point2D.Double field as TRansient to avoid a NotSerializableException. public class LabeledPoint implements Serializable { . . . private String label; private transient Point2D.Double point; } In the writeObject method, we first write the object descriptor and the String field, state, by calling the defaultWriteObject method. This is a special method of the ObjectOutputStream class that can only be called from within a writeObject method of a serializable class. Then we write the point coordinates, using the standard DataOutput calls. private void writeObject(ObjectOutputStream out) throws IOException { out.defaultWriteObject(); out.writeDouble(point.getX()); out.writeDouble(point.getY()); } In the readObject method, we reverse the process: private void readObject(ObjectInputStream in) throws IOException { in.defaultReadObject(); double x = in.readDouble(); double y = in.readDouble(); point = new Point2D.Double(x, y); } Another example is the java.util.Date class that supplies its own readObject and writeObject methods. These methods write the date as a number of milliseconds from the epoch (January 1, 1970, midnight UTC). The Date class has a complex internal representation that stores both a Calendar object and a millisecond count, to optimize lookups. The state of the Calendar is redundant and does not have to be saved. The readObject and writeObject methods only need to save and load their data fields. They should not concern themselves with superclass data or any other class information. Rather than letting the serialization mechanism save and restore object data, a class can define its own mechanism. To do this, a class must implement the Externalizable interface. This in turn requires it to define two methods: public void readExternal(ObjectInputStream in) throws IOException, ClassNotFoundException; public void writeExternal(ObjectOutputStream out) throws IOException; Unlike the readObject and writeObject methods that were described in the preceding section, these methods are fully responsible for saving and restoring the entire object, including the superclass data. The serialization mechanism merely records the class of the object in the stream. When reading an externalizable object, the object stream creates an object with the default constructor and then calls the readExternal method. Here is how you can implement these methods for the Employee class: public void readExternal(ObjectInput s) throws IOException { name = s.readUTF(); salary = s.readDouble(); hireDay = new Date(s.readLong()); } public void writeExternal(ObjectOutput s) throws IOException { s.writeUTF(name); s.writeDouble(salary); s.writeLong(hireDay.getTime()); } TIP
CAUTION
NOTE
Serializing Singletons and Typesafe EnumerationsYou have to pay particular attention when serializing and deserializing objects that are assumed to be unique. This commonly happens when you are implementing singletons and typesafe enumerations. If you use the enum construct of JDK 5.0, then you need not worry about serialization it just works. However, suppose you maintain legacy code that contains an enumerated type such as public class Orientation { public static final Orientation HORIZONTAL = new Orientation(1); public static final Orientation VERTICAL = new Orientation(2); private Orientation(int v) { value = v; } private int value; } This idiom was common before enumerations were added to the Java language. Note that the constructor is private. Thus, no objects can be created beyond Orientation.HORIZONTAL and Orientation.VERTICAL. In particular, you can use the == operator to test for object equality: if (orientation == Orientation.HORIZONTAL) . . . There is an important twist that you need to remember when a typesafe enumeration implements the Serializable interface. The default serialization mechanism is not appropriate. Suppose we write a value of type Orientation and read it in again: Orientation original = Orientation.HORIZONTAL; ObjectOutputStream out = . . .; out.write(value); out.close(); ObjectInputStream in = . . .; Orientation saved = (Orientation) in.read(); Now the test if (saved == Orientation.HORIZONTAL) . . . will fail. In fact, the saved value is a completely new object of the Orientation type and not equal to any of the predefined constants. Even though the constructor is private, the serialization mechanism can create new objects! To solve this problem, you need to define another special serialization method, called readResolve. If the readResolve method is defined, it is called after the object is deserialized. It must return an object that then becomes the return value of the readObject method. In our case, the readResolve method will inspect the value field and return the appropriate enumerated constant: protected Object readResolve() throws ObjectStreamException { if (value == 1) return Orientation.HORIZONTAL; if (value == 2) return Orientation.VERTICAL; return null; // this shouldn't happen } Remember to add a readResolve method to all typesafe enumerations in your legacy code and to all classes that follow the singleton design pattern. VersioningIn the previous sections, we showed you how to save relatively small collections of objects by means of an object stream. But those were just demonstration programs. With object streams, it helps to think big. Suppose you write a program that lets the user produce a document. This document contains paragraphs of text, tables, graphs, and so on. You can stream out the entire document object with a single call to writeObject: out.writeObject(doc); The paragraph, table, and graph objects are automatically streamed out as well. One user of your program can then give the output file to another user who also has a copy of your program, and that program loads the entire document with a single call to readObject: doc = (Document) in.readObject(); This is very useful, but your program will inevitably change, and you will release a version 1.1. Can version 1.1 read the old files? Can the users who still use 1.0 read the files that the new version is now producing? Clearly, it would be desirable if object files could cope with the evolution of classes. At first glance it seems that this would not be possible. When a class definition changes in any way, then its SHA fingerprint also changes, and you know that object streams will refuse to read in objects with different fingerprints. However, a class can indicate that it is compatible with an earlier version of itself. To do this, you must first obtain the fingerprint of the earlier version of the class. You use the stand-alone serialver program that is part of the JDK to obtain this number. For example, running serialver Employee prints Employee: static final long serialVersionUID = -1814239825517340645L; If you start the serialver program with the -show option, then the program brings up a graphical dialog box (see Figure 12-10). Figure 12-10. The graphical version of the serialver program
All later versions of the class must define the serialVersionUID constant to the same fingerprint as the original. class Employee implements Serializable // version 1.1 { . . . public static final long serialVersionUID = -1814239825517340645L; } When a class has a static data member named serialVersionUID, it will not compute the fingerprint manually but instead will use that value. Once that static data member has been placed inside a class, the serialization system is now willing to read in different versions of objects of that class. If only the methods of the class change, then there is no problem with reading the new object data. However, if data fields change, then you may have problems. For example, the old file object may have more or fewer data fields than the one in the program, or the types of the data fields may be different. In that case, the object stream makes an effort to convert the stream object to the current version of the class. The object stream compares the data fields of the current version of the class with the data fields of the version in the stream. Of course, the object stream considers only the nontransient and nonstatic data fields. If two fields have matching names but different types, then the object stream makes no effort to convert one type to the other the objects are incompatible. If the object in the stream has data fields that are not present in the current version, then the object stream ignores the additional data. If the current version has data fields that are not present in the streamed object, the added fields are set to their default (null for objects, zero for numbers, and false for Boolean values). Here is an example. Suppose we have saved a number of employee records on disk, using the original version (1.0) of the class. Now we change the Employee class to version 2.0 by adding a data field called department. Figure 12-11 shows what happens when a 1.0 object is read into a program that uses 2.0 objects. The department field is set to null. Figure 12-12 shows the opposite scenario: a program using 1.0 objects reads a 2.0 object. The additional department field is ignored. Figure 12-11. Reading an object with fewer data fields Figure 12-12. Reading an object with more data fields Is this process safe? It depends. Dropping a data field seems harmless the recipient still has all the data that it knew how to manipulate. Setting a data field to null may not be so safe. Many classes work hard to initialize all data fields in all constructors to non-null values, so that the methods don't have to be prepared to handle null data. It is up to the class designer to implement additional code in the readObject method to fix version incompatibilities or to make sure the methods are robust enough to handle null data. Using Serialization for CloningThere is an amusing (and, occasionally, very useful) use for the serialization mechanism: it gives you an easy way to clone an object provided the class is serializable. (Recall from Chapter 6 that you need to do a bit of work to allow an object to be cloned.) To clone a serializable object, simply serialize it to an output stream and then read it back in. The result is a new object that is a deep copy of the existing object. You don't have to write the object to a file you can use a ByteArrayOutputStream to save the data into a byte array. As Example 12-6 shows, to get clone for free, simply extend the SerialCloneable class, and you are done. You should be aware that this method, although clever, will usually be much slower than a clone method that explicitly constructs a new object and copies or clones the data fields (as you saw in Chapter 6). Example 12-6. SerialCloneTest.java 1. import java.io.*; 2. import java.util.*; 3. 4. public class SerialCloneTest 5. { 6. public static void main(String[] args) 7. { 8. Employee harry = new Employee("Harry Hacker", 35000, 1989, 10, 1); 9. // clone harry 10. Employee harry2 = (Employee) harry.clone(); 11. 12. // mutate harry 13. harry.raiseSalary(10); 14. 15. // now harry and the clone are different 16. System.out.println(harry); 17. System.out.println(harry2); 18. } 19. } 20. 21. /** 22. A class whose clone method uses serialization. 23. */ 24. class SerialCloneable implements Cloneable, Serializable 25. { 26. public Object clone() 27. { 28. try 29. { 30. // save the object to a byte array 31. ByteArrayOutputStream bout = new ByteArrayOutputStream(); 32. ObjectOutputStream out = new ObjectOutputStream(bout); 33. out.writeObject(this); 34. out.close(); 35. 36. // read a clone of the object from the byte array 37. ByteArrayInputStream bin = new ByteArrayInputStream(bout.toByteArray()); 38. ObjectInputStream in = new ObjectInputStream(bin); 39. Object ret = in.readObject(); 40. in.close(); 41. 42. return ret; 43. } 44. catch (Exception e) 45. { 46. return null; 47. } 48. } 49. } 50. 51. /** 52. The familiar Employee class, redefined to extend the 53. SerialCloneable class. 54. */ 55. class Employee extends SerialCloneable 56. { 57. public Employee(String n, double s, int year, int month, int day) 58. { 59. name = n; 60. salary = s; 61. GregorianCalendar calendar = new GregorianCalendar(year, month - 1, day); 62. hireDay = calendar.getTime(); 63. } 64. 65. public String getName() 66. { 67. return name; 68. } 69. 70. public double getSalary() 71. { 72. return salary; 73. } 74. 75. public Date getHireDay() 76. { 77. return hireDay; 78. } 79. 80. public void raiseSalary(double byPercent) 81. { 82. double raise = salary * byPercent / 100; 83. salary += raise; 84. } 85. 86. public String toString() 87. { 88. return getClass().getName() 89. + "[name=" + name 90. + ",salary=" + salary 91. + ",hireDay=" + hireDay 92. + "]"; 93. } 94. 95. private String name; 96. private double salary; 97. private Date hireDay; 98. } | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
("employee.dat")); 21. out.writeObject(staff); 22. out.close(); 23. 24. // retrieve all records into a new array 25. ObjectInputStream in = new ObjectInputStream(new FileInputStream("employee 
 |
EAN: 2147483647
Pages: 132