JDK-8199763 : Behavior of null arguments not specified in Java Sound
  • Type: CSR
  • Component: client-libs
  • Sub-Component: javax.sound
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 11
  • Submitted: 2018-03-18
  • Updated: 2019-05-31
  • Resolved: 2018-03-22
Related Reports
CSR :  
Description
Summary
-------

Most Java Sound methods and constructors do not specify the behavior when passing null as one or more of the arguments.

Solution
--------

Java API's should, specify what can happens, if null is passed as argument.

Specification
-------------

    src/java.desktop/share/classes/javax/sound/midi/package-info.java

    + * Please note: In the {@code javax.sound.midi} APIs, a {@code null} reference
    + * parameter to methods is incorrect unless explicitly documented on the method
    + * as having a meaningful interpretation. Usage to the contrary is incorrect
    + * coding and may result in a run time exception either immediately or at some
    + * later time. {@code NullPointerException} is an example of typical and
    + * acceptable run time exception for such cases.
      *
      * @since 1.3
      */
     package javax.sound.midi;
.....

     src/java.desktop/share/classes/javax/sound/midi/spi/package-info.java

     + * Please note: In the {@code javax.sound.midi.spi} APIs, a {@code null}
     + * reference parameter to methods is incorrect unless explicitly documented on
     + * the method as having a meaningful interpretation. Usage to the contrary is
     + * incorrect coding and may result in a run time exception either immediately or
     + * at some later time. {@code NullPointerException} is an example of typical and
     + * acceptable run time exception for such cases.
       *
       * @since 1.3
       */
      package javax.sound.midi.spi;
....

      src/java.desktop/share/classes/javax/sound/sampled/package-info.java
      
      + * Please note: In the {@code javax.sound.sampled} APIs, a {@code null}
      + * reference parameter to methods is incorrect unless explicitly documented on
      + * the method as having a meaningful interpretation. Usage to the contrary is
      + * incorrect coding and may result in a run time exception either immediately or
      + * at some later time. {@code NullPointerException} is an example of typical and
      + * acceptable run time exception for such cases.
        *
        * @since 1.3
        */
       package javax.sound.sampled;
....

       src/java.desktop/share/classes/javax/sound/sampled/spi/package-info.java

       + * Please note: In the {@code javax.sound.sampled.spi} APIs, a {@code null}
       + * reference parameter to methods is incorrect unless explicitly documented on
       + * the method as having a meaningful interpretation. Usage to the contrary is
       + * incorrect coding and may result in a run time exception either immediately or
       + * at some later time. {@code NullPointerException} is an example of typical and
       + * acceptable run time exception for such cases.
         *
         * @since 1.3
         */
        package javax.sound.sampled.spi;

Comments
Okay; double-checking the history of the javax.print package docs, I see that the disclaimer has been there since at least since the start of the OpenJDK sources in 2007. I'm moving this change to Approved, but if there is not such an RFE already, I recommend filing a follow-up RFE to document more specific null-handling behavior in the affected packages.
22-03-2018

The same text is used in some other packages in java.desktop module, for example(see the end of the page): https://docs.oracle.com/javase/7/docs/api/javax/print/package-summary.html More strict text like "Throws an NPE unless otherwise specified..." is not used because our implementations is not consistent about NPE. Long term I expect that all API in these packages will throw NPE on null, but for now we just highlight that null is not welcome. The intentions of this fix is to notify the users that if some method accept unspecified "null", then it does not mean that it will do this always, this may be changed in the future by some other change.
20-03-2018

This is much weaker and less specific wording that usually used to specify null handing, including as used in the existing subtasks of this issue. Is there a reason the usual wording "Throws an NPE unless otherwise specified..." is not used? Marking the request as pended until this is resolved.
20-03-2018