Interface functionalities like java.naming.Name should include an example
of implementing code and be paired with a helper class that
provides an implementation that complies with the API. Otherwise,
the interface cannot be tested and noncomplying implementations
can be created without violating the specification.

Note in the "Java Class Specification Requirements" doc:

"Each class description must include:
4.A description of any aspect of this object
that may vary by implementation.
This description should not include information
about current JavaSoft implementation bugs. "

Method java.naming.Name.compareTo(java.lang.Object)
describes a process that is essentially design-by-contract.
Nothing in the actual class contains code implementing these
actions, only extending classes contain it. The actual
operation may be too specific to include in Name code, but
irregardless this should be explained. It is therefore
impossible to write a Name class that actually does what Name
API describes, even if the method was adequately explained,
which it is not.


Method APIs for java.naming.Name.get*() state the parameter constraints
but do not state the implications of failing to comply with
these constraints (i.e. "will throw a NullPointerException"). See
the paragraph in "Java Class Specification Requirements"
that begins with:

"In addition to the class specific requirements,
there are overall Java API documentation requirements with respect to
handling unchecked exceptions..."

See also implementing classes of java.naming.Name

brian.preston@eng 1997-10-23