[jdom-interest] TODO summary [eg]

[Joseph Bowbeer]

JDOM'ers -- Thanks for dealing with my many TODO suggestions so
thoughtfully.

I summarize the current state of these suggestions below (as I see it).

Note: The serialization issues are still under discussion and in fact I add
some new material in #5 and #7 below.


SUBCLASSING

1. Strive to avoid calling overridable methods from constructors, or clone,
or readObject.  Document when we can't abide.

2. Document the implementation for the benefit of subclassers.


CLONEABLE

3. Resolved: Our classes are Cloneable and our clone implementations do not
declare CloneNotSupportedException.  However, in our clone implementations
we should throw InternalError if we ever catch(CloneNotSupportedException).


SERIALIZATION

4. Resolved: Our classes are Serializable (or Externalizable).

The priorities have been clarified.  Serialization for the purposes of
efficient transmission is more important than serialization for long-term
persistence.

5. A custom serialized form is needed.

Why?  We want a compact, efficient serialized form for transmission, and the
default serialized form is neither. In fact, the default form is prone to
stack overflows...

Also, we don't want implementation details such as List representations to
leak-out into the serialized form.  For example, one should be able to
transmit serialized documents between two different implementations of JDOM,
as long as both JDOM's pass the compatibility tests.  (In this respect,
transmission and persistence have similar requirements.)

6. Add explicit serialVersionUID definitions and document the serialized
form with @serial and @serialData comments.  The serialized form is part of
the JDOM API.

7. The question remains whether we implement Externalizable or Serializable.
Externalizable is less work for us and has less overhead.  Serializable is
more work for us (e.g., marking all the fields transient), but is also more
extensible (via defaultWriteObject) and is friendlier to subclassers.

By the way, Externalizable is also less secure, if that matters.  I quote
from the spec:

"Note - The writeExternal and readExternal methods are public and raise the
risk that a client may be able to write or read information in the object
other than by using its methods and fields. These methods must be used only
when the information held by the object is not sensitive or when exposing it
does not present a security risk."

(I favor Serializable.)

--
Joe Bowbeer