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.