Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4088316

implementing interface API, compareTo, throwing whateverException

    XMLWordPrintable

    Details

    • Subcomponent:
    • Resolved In Build:
      1.1
    • CPU:
      generic
    • OS:
      solaris_2.6
    • Verification:
      Verified

      Backports

        Description

        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

          Attachments

            Issue Links

              Activity

                People

                Assignee:
                rleesunw Rosanna Lee (Inactive)
                Reporter:
                bprestonsunw Brian Preston (Inactive)
                Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                  Dates

                  Created:
                  Updated:
                  Resolved:
                  Imported:
                  Indexed: