Summary

Add an implementation and API note regarding the inconsistent behavior of creating a ChoiceFormat with an incorrect pattern.

Problem

Using an incorrect pattern to create a ChoiceFormat has inconsistent behavior. Sometimes an (expected) IllegalArgumentException is thrown, an (unexpected) NumberFormatException is thrown, the ChoiceFormat is constructed using up to the correct portion of the incorrect pattern, or a ChoiceFormat is constructed that will throw an ArrayIndexOutOfBoundsException when format is invoked.

Solution

Clarify the behavior for creating a ChoiceFormat with an incorrect pattern using an implNote tag. This behavior is not desirable (and hard to concretely specify all the possible conditions for the behavior), and should be informative. Additionally, add an apiSpec tag that recommends subclasses implement their own more consistent error handling, if desired.

Ideally a fix could be done that standardizes the behavior so an exception is thrown for all incorrect cases. However, the benefit of consistent error handling does not outweigh the risk of breaking applications that are using the "expected" incorrect behavior. Especially since besides the original bug report, there have been no further bugs filed regarding this behavior.

For example, fixing the inconsistent behavior would break the following,

// Ideally, an IAE is thrown here
// will throw an AIOOBE if later, format() is invoked with the current empty pattern
var c = new ChoiceFormat("");
// do things, get the value for validPatternString
c.applyPattern(validPatternString);

This is potentially a valid use case by users to simply initialize the choiceFormat and set the pattern later. In fact the JDK has existing tests that have occurrences of this.

Only the most egregious bug related to incorrect patterns is being fixed, handled in JDK-8325898.

Specification

Update the patterns section,

+ * @apiNote A subclass could perform more consistent pattern validation by
+ * throwing an {@code IllegalArgumentException} for all incorrect cases.
+ * @implNote Given an incorrect pattern, this implementation may either
+ * throw an exception or succeed and discard the incorrect portion. A {@code
+ * NumberFormatException} is thrown if a {@code limit} can not be
+ * parsed as a numeric value and an {@code IllegalArgumentException} is thrown
+ * if a {@code SubPattern} is missing, or the intervals are not ascending.
+ * Discarding the incorrect portion may result in a ChoiceFormat with
+ * empty {@code limits} and {@code formats}.
+ *

For context, the final sentence is sufficient, as it is already specified that empty {@code limits} and {@code formats} will throw an AIOOBE when formatting.

Update the wording for both the constructor and applyPattern method to mention "error caveats",

     /**
-     * Apply the given pattern to this ChoiceFormat object. The syntax
-     * for the ChoiceFormat pattern can be seen in the {@linkplain ##patterns
-     * Patterns} section.
+     * Apply the given pattern to this ChoiceFormat object. The syntax and error
+     * related caveats for the ChoiceFormat pattern can be found in the
+     * {@linkplain ##patterns Patterns} section