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

java.util.Formatter throws wrong exception for mismatched flags in %% conversion

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      This is a documentation change to match existing behavior. There is no major compatibility risk.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The specification in java.util.Formatter states that given a percent (%) character in a formatting string, only a dash (-) character flag is allowed as an applicable conversion. If any other flag is provided, the documents state that FormatFlagsConversionMismatchException will be thrown. In actual behavior, IllegalFormatFlagsException is thrown instead. This CSR proposes changing the specification to match the behavior as it is the long-standing behavior of the implementation and makes more intuitive sense.

      Problem

      The specification in java.util.Formatter the percent (%) section incorrectly describes the exception thrown if an invalid conversion flag is provided.

      Solution

      Change the specification to match the behavior. This behavior is well-established and the exception thrown in practice better describes the corresponding error (an invalid flag) in the specification (formatting flags conversion mismatch). Changing the specification achieves consistency with existing behavior while not risking breakages due to a behavioral change.

      Note: both exceptions are subclasses of java.util.IllegalFormatException.

      Specification

      diff --git a/src/java.base/share/classes/java/util/Formatter.java b/src/java.base/share/classes/java/util/Formatter.java
      index e5934b28e78..c4dc4c0b85d 100644
      --- a/src/java.base/share/classes/java/util/Formatter.java
      +++ b/src/java.base/share/classes/java/util/Formatter.java
      @@ -1832,7 +1832,7 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
        *
        * <p> The {@code '-'} flag defined for <a href="#dFlags">General
        * conversions</a> applies.  If any other flags are provided, then a
      - * {@link FormatFlagsConversionMismatchException} will be thrown.
      + * {@link IllegalFormatFlagsException } will be thrown.
        *
        * <p> The precision is not applicable.  If the precision is specified an
        * {@link IllegalFormatPrecisionException} will be thrown.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              igraves Ian Graves
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Stuart Marks
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: