[jdom-interest] TODO subclassing [eg]

[Joseph Bowbeer]

Tweaking JDOM for subclassing is a TODO topic in itself.

1. There are some specific things we can avoid, such as never calling
overridable methods from constructors and "pseudo-constructors" (clone and
readObject).  Note: "overridable" means not final and either protected or
public.

Rationale [quoted from Effective Java by Josh Bloch]:

Constructor: "The superclass constructor runs before the subclass
constructor, so the overriding method in the subclass will get invoked
before the subclass constructor has run."

clone: "If clone invokes an overridden method, this method will execute
before the subclass in which it is defined has had a chance to fix its state
in the clone ..."

readObject: "... the overriding method will run before the subclass's state
has been deserialized."


2. There are also some design/documentation issues concerning what
subclasses are allowed to do.

Here's what Effective Java advises:

"The class must document precisely the effects of overriding any method.
[...]  In other words, the class must document its self-use of overridable
methods: for each public or protected method, the documentation must
indicate which overridable methods are invoked by that method, in what
sequence they are invoked, and how the results of each invocation affect
subsequent processing. By convention, this description is placed at the end
of the javadoc comment for each method, and begins with the phrase _This
implementation_."

The java.util.AbstractCollection javadoc is good a example.

--
Joe Bowbeer