These methods are invoked when the object is serialized and deserialized, respectively. They are normal
public methods, so the exact type of the object determines which implementation will be used. Subclasses of
an externalizable class will often need to invoke their superclass's implementation before serializing or
deserializing their own statein contrast to classes that use normal serialization.
You should note that the methods of the interface are public and so can be invoked by anyone at anytime. In
particular, a malicious program might invoke readExternal to make an object overwrite its state from
some serialized stream, possibly with invented content. If you are designing classes where such security
counts you have to take this into account either by not using Externalizable or by writing your
readExternal method to be only invoked once, and never at all if the object was created via one of your
constructors.
20.8.8. Documentation Comment Tags
As you can see from the Rectangle code, the serialized form of an object can be an important thing,
separate from its runtime form. This can happen over time due to evolution, or by initial design when the
runtime form is not a good serialized form. When you write serializable classes that others will reimplement,
you should document the persistent form so that other programmer's can properly re-implement the serialized
form as well as the runtime behavior. You do this with the special javadoc tags @serial, @serialField,
and @serialData.
Use @serial to document fields that use default serialization. For example, the original Rectangle class
could have looked like this:
/** X-coordinate of one corner.
- @serial */
private double x1;
/** Y-coordinate of one corner. - @serial */
private double y1;
/** X-coordinate of opposite corner. - @serial */
private double x2;
/** Y-coordinate of opposite corner. - @serial */
private double y2;
The @serial tag can include a description of the meaning of the field. If none is given (as above), then the
description of the runtime field will be used. The javadoc tool will add all @serial information to a page,
known as the serialized form page.
The @serial tag can also be applied to a class or package with the single argument include or
exclude, to control whether serialization information is documented for that class or package. By default
public and protected types are included, otherwise they are excluded. A class level @serial tag overrides a
package level @serial tag.
The @serialField tag documents fields that are created by GetField and PutField invocations, such
as those in our Rectangle example. The tag takes first the field name, then its type, and then a description.
For example:
/ @serialField x1 double X-coordinate of one corner. */
/* @serialField y1 double Y-coordinate of one corner. /
/ @serialField x2 double X-coordinate of other corner. */
/* @serialField y2 double Y-coordinate of other corner. /
private transient double x, y, width, height;