Summary

Clarify the specification for java.text.SimpleDateFormat patterns regarding reserved letters.

Problem

The SimpleDateFormat specification defines certain pattern letters as 'reserved'. However, it is not explicitly defined what the behavior is, when these letters are used in a pattern. (Although it is reasonable to infer.) Thus, behavior regarding reserved characters can be interpreted as being deferred to implementers. For example, ignoring those characters, or copying them into output instead of throwing an exception.

Solution

Explicitly state that an IllegalArgumentException is thrown, if a reserved character is used in a pattern. This long standing JDK reference implementation behavior should be made normative to all implementations.

Specification

Amend the wording above the patterns table,

  * The following pattern letters are defined (all other characters from
  * {@code 'A'} to {@code 'Z'} and from {@code 'a'} to
- * {@code 'z'} are reserved):
+ * {@code 'z'} not in the table below are reserved). {@link #applyPattern(String)},
+ * {@link #applyLocalizedPattern(String)}, and the {@link #SimpleDateFormat(String)
+ * SimpleDateFormat constructors} throw {@code IllegalArgumentException} when
+ * passed a pattern containing an unquoted reserved character.