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

Duration.valueOf() javadoc & signature is missing thrown exceptions description

    Details

    • Type: Enhancement
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 8, 9
    • Fix Version/s: tbd
    • Component/s: javafx
    • Subcomponent:
    • CPU:
      x86
    • OS:
      other

      Description

      A DESCRIPTION OF THE REQUEST :
      The method valueOf() from the class javafx.util.Duration throws an IllegalArgumentException whenever the string passed as an argument fails to comply to the desired format. However the exception is not described in the javadoc or the method signature.

      Furthermore the method's documentation mentions that the method may raise a NullPointerException if the time parameter is null but fails to describe the exception with the proper javadoc tag. This exception is also absent from the method signature.



      JUSTIFICATION :
      As both are RuntimeException instances they are not required to be dealt with by the programmer. However the programmer still need to catch them and deal with them in places where durations creation is automated or when testing. I had to look at the source code to know that I needed to catch an IllegalArgumentException instead of another one (ie: I would have expected a NumberFormatException or something similar to be used instead).

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      Both IllegalArgumentException and NullPointerException should be described in the method signature and the accompanying documentation.


      ACTUAL -
      IllegalArgumentException is not mentioned in the documentation or present in the signature of the method.

      NullPointerException is mentionned in the description of the time parameter but not described with the appropriate javadoc tag and is not present in the signature of the method.

      ---------- BEGIN SOURCE ----------
      Look at the source code for the valueOf() method of the class javafx.util.Duration:


          /**
           * Factory method that returns a Duration instance for a specified
           * amount of time. The syntax is "[number][ms|s|m|h]".
           *
           * @param time A non-null string properly formatted. Leading or trailing
           * spaces will not parse correctly. Throws a NullPointerException if
           * time is null.
           * @return a Duration which is represented by the <code>time</code>
           */
          public static Duration valueOf(String time) {
              int index = -1;
              for (int i=0; i<time.length(); i++) {
                  char c = time.charAt(i);
                  if (!Character.isDigit(c) && c != '.' && c != '-') {
                      index = i;
                      break;
                  }
              }

              if (index == -1) {
                  // Never found the suffix!
                  throw new IllegalArgumentException("The time parameter must have a suffix of [ms|s|m|h]");
              }

              double value = Double.parseDouble(time.substring(0, index));
              String suffix = time.substring(index);
              if ("ms".equals(suffix)) {
                  return millis(value);
              } else if ("s".equals(suffix)) {
                  return seconds(value);
              } else if ("m".equals(suffix)) {
                  return minutes(value);
              } else if ("h".equals(suffix)) {
                  return hours(value);
              } else {
                  // Malformed suffix
                  throw new IllegalArgumentException("The time parameter must have a suffix of [ms|s|m|h]");
              }
          }

      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      Always provide a non-null string using the appropriate format.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated: