Summary

Document the inconsistency between ChoiceFormat::applyPattern and ChoiceFormat::setChoices for this implementation when creating ChoiceFormat objects.

Problem

The mentioned methods are both used to create ChoiceFormat objects. However, setChoices() imposes no limitations on the order of limits, whereas applyPattern() will throw an exception if the limits are not in ascending order.

For example, attempting to create the following equivalent ChoiceFormats

// allowed, but formatting with this object produces wrong results
new ChoiceFormat("").setChoices(new double[]{1,1}, new String[]{"foo","bar"})
new ChoiceFormat("").applyPattern("1#foo|1#bar") // throws IllegalArgumentException

This blurs the line of what is acceptable as a correct ChoiceFormat. Since using one method can create a ChoiceFormat that formats incorrectly, but the other does not. This is not obvious behavior, and should be emphasized.

Solution

Update applyPattern() to distinguish the difference in behavior for non-ascending limits between the two mentioned methods. setChoices already warns about the repercussions of non-ascending limit arrays when formatting, so no new specification is needed there. The decision to not use an implSpec tag was a result of the discussion in JDK-8318191, as this class is likely not sub-classed in practice, this update can apply to the general API specification.

Specification

Update ChoiceFormat::applyPattern

     /**
      * Apply the given pattern to this ChoiceFormat object. The syntax
      * for the ChoiceFormat pattern can be seen in the {@linkplain ##patterns
-     * Patterns} section.
-     *
+     * Patterns} section. Unlike {@link #setChoices(double[], String[])} this
+     * method will throw an {@code IllegalArgumentException} if the {@code
+     * limits} are not in ascending order.
      * @param newPattern a pattern string
      * @throws    NullPointerException if {@code newPattern}
      *            is {@code null}