changeset 16425:a20f2cf90762 jdk-9+152

8169480: Inconsistencies across Format class hierarchy in their API spec and actual implementation of Exceptions Reviewed-by: naoto Contributed-by: nishit.jain@oracle.com
author nishjain
date Mon, 09 Jan 2017 14:06:32 +0530
parents d257d5a41c58
children d93e93939378 8be0bb1aa238 c01830a9d230
files src/java.base/share/classes/java/text/ChoiceFormat.java src/java.base/share/classes/java/text/DateFormat.java src/java.base/share/classes/java/text/DecimalFormat.java src/java.base/share/classes/java/text/MessageFormat.java src/java.base/share/classes/java/text/NumberFormat.java src/java.base/share/classes/java/text/SimpleDateFormat.java
diffstat 6 files changed, 64 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/text/ChoiceFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/ChoiceFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -172,6 +172,8 @@
     /**
      * Sets the pattern.
      * @param newPattern See the class description.
+     * @exception NullPointerException if {@code newPattern}
+     *            is {@code null}
      */
     public void applyPattern(String newPattern) {
         StringBuffer[] segments = new StringBuffer[2];
@@ -309,6 +311,8 @@
      * Constructs with limits and corresponding formats based on the pattern.
      *
      * @param newPattern the new pattern string
+     * @exception NullPointerExcpetion if {@code newPattern} is
+     *            {@code null}
      * @see #applyPattern
      */
     public ChoiceFormat(String newPattern)  {
@@ -320,6 +324,8 @@
      *
      * @param limits limits in ascending order
      * @param formats corresponding format strings
+     * @exception NullPointerException if {@code limits} or {@code formats}
+     *            is {@code null}
      * @see #setChoices
      */
     public ChoiceFormat(double[] limits, String[] formats) {
@@ -339,6 +345,8 @@
      * When formatting with object Y,
      * if the object is a NumberFormat, then ((NumberFormat) Y).format(X)
      * is called. Otherwise Y.toString() is called.
+     * @exception NullPointerException if {@code limits} or
+     *            {@code formats} is {@code null}
      */
     public void setChoices(double[] limits, String formats[]) {
         if (limits.length != formats.length) {
@@ -386,6 +394,8 @@
      * @param number number to be formatted and substituted.
      * @param toAppendTo where text is appended.
      * @param status ignore no useful status is returned.
+     * @exception NullPointerException if {@code toAppendTo}
+     *            is {@code null}
      */
    public StringBuffer format(double number, StringBuffer toAppendTo,
                                FieldPosition status) {
@@ -414,6 +424,9 @@
      * status.index is unchanged and status.errorIndex is set to the
      * first index of the character that caused the parse to fail.
      * @return A Number representing the value of the number parsed.
+     * @exception NullPointerException if {@code status} is {@code null}
+     *            or if {@code text} is {@code null} and the list of
+     *            choice strings is not empty.
      */
     public Number parse(String text, ParsePosition status) {
         // find the best number (defined as the one with the longest parse)
--- a/src/java.base/share/classes/java/text/DateFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/DateFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -141,6 +141,25 @@
  * If multiple threads access a format concurrently, it must be synchronized
  * externally.
  *
+ * @implSpec
+ * <ul><li>The {@link #format(Date, StringBuffer, FieldPosition)} and
+ * {@link #parse(String, ParsePosition)} methods may throw
+ * {@code NullPointerException}, if any of their parameter is {@code null}.
+ * The subclass may provide its own implementation and specification about
+ * {@code NullPointerException}.</li>
+ * <li>The {@link #setCalendar(Calendar)}, {@link
+ * #setNumberFormat(NumberFormat)} and {@link #setTimeZone(TimeZone)} methods
+ * do not throw {@code NullPointerException} when their parameter is
+ * {@code null}, but any subsequent operations on the same instance may throw
+ * {@code NullPointerException}.</li>
+ * <li>The {@link #getCalendar()}, {@link #getNumberFormat()} and
+ * {@link getTimeZone()} methods may return {@code null}, if the respective
+ * values of this instance is set to {@code null} through the corresponding
+ * setter methods. For Example: {@link #getTimeZone()} may return {@code null},
+ * if the {@code TimeZone} value of this instance is set as
+ * {@link #setTimeZone(java.util.TimeZone) setTimeZone(null)}.</li>
+ * </ul>
+ *
  * @see          Format
  * @see          NumberFormat
  * @see          SimpleDateFormat
@@ -296,6 +315,8 @@
      * the begin index and end index of fieldPosition will be set to
      * 5 and 8, respectively, for the first occurrence of the timezone
      * pattern character 'z'.
+     * @exception IllegalArgumentException if the {@code Format} cannot format
+     *            the given {@code obj}.
      * @see java.text.Format
      */
     public final StringBuffer format(Object obj, StringBuffer toAppendTo,
--- a/src/java.base/share/classes/java/text/DecimalFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/DecimalFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -514,6 +514,8 @@
      * @param result    where the text is to be appended
      * @param fieldPosition    On input: an alignment field, if desired.
      * On output: the offsets of the alignment field.
+     * @exception NullPointerException if {@code result} or
+     *            {@code fieldPosition} is {@code null}
      * @exception ArithmeticException if rounding is needed with rounding
      *            mode being set to RoundingMode.UNNECESSARY
      * @return The formatted number string
@@ -632,6 +634,8 @@
      * @param result    where the text is to be appended
      * @param fieldPosition    On input: an alignment field, if desired.
      * On output: the offsets of the alignment field.
+     * @exception       NullPointerException if {@code result} or
+     *                  {@code fieldPosition} is {@code null}
      * @exception       ArithmeticException if rounding is needed with rounding
      *                  mode being set to RoundingMode.UNNECESSARY
      * @return The formatted number string
--- a/src/java.base/share/classes/java/text/MessageFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/MessageFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -356,6 +356,8 @@
      *
      * @param pattern the pattern for this message format
      * @exception IllegalArgumentException if the pattern is invalid
+     * @exception NullPointerException if {@code pattern} is
+     *            {@code null}
      */
     public MessageFormat(String pattern) {
         this.locale = Locale.getDefault(Locale.Category.FORMAT);
@@ -373,6 +375,8 @@
      * @param pattern the pattern for this message format
      * @param locale the locale for this message format
      * @exception IllegalArgumentException if the pattern is invalid
+     * @exception NullPointerException if {@code pattern} is
+     *            {@code null}
      * @since 1.4
      */
     public MessageFormat(String pattern, Locale locale) {
@@ -420,6 +424,8 @@
      *
      * @param pattern the pattern for this message format
      * @exception IllegalArgumentException if the pattern is invalid
+     * @exception NullPointerException if {@code pattern} is
+     *            {@code null}
      */
     @SuppressWarnings("fallthrough") // fallthrough in switch is expected, suppress it
     public void applyPattern(String pattern) {
@@ -814,6 +820,7 @@
      * @exception IllegalArgumentException if an argument in the
      *            <code>arguments</code> array is not of the type
      *            expected by the format element(s) that use it.
+     * @exception NullPointerException if {@code result} is {@code null}
      */
     public final StringBuffer format(Object[] arguments, StringBuffer result,
                                      FieldPosition pos)
@@ -835,6 +842,7 @@
      *            or if an argument in the <code>arguments</code> array
      *            is not of the type expected by the format element(s)
      *            that use it.
+     * @exception NullPointerException if {@code pattern} is {@code null}
      */
     public static String format(String pattern, Object ... arguments) {
         MessageFormat temp = new MessageFormat(pattern);
@@ -858,6 +866,7 @@
      * @exception IllegalArgumentException if an argument in the
      *            <code>arguments</code> array is not of the type
      *            expected by the format element(s) that use it.
+     * @exception NullPointerException if {@code result} is {@code null}
      */
     public final StringBuffer format(Object arguments, StringBuffer result,
                                      FieldPosition pos)
@@ -947,6 +956,8 @@
      * @param source the string to parse
      * @param pos    the parse position
      * @return an array of parsed objects
+     * @exception NullPointerException if {@code pos} is {@code null}
+     *            for a non-null {@code source} string.
      */
     public Object[] parse(String source, ParsePosition pos) {
         if (source == null) {
--- a/src/java.base/share/classes/java/text/NumberFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/NumberFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -174,6 +174,13 @@
  * If multiple threads access a format concurrently, it must be synchronized
  * externally.
  *
+ * @implSpec The {@link #format(double, StringBuffer, FieldPosition)},
+ * {@link #format(long, StringBuffer, FieldPosition)} and
+ * {@link #parse(String, ParsePosition)} methods may throw
+ * {@code NullPointerException}, if any of their parameter is {@code null}.
+ * The subclass may provide its own implementation and specification about
+ * {@code NullPointerException}.
+ *
  * @see          DecimalFormat
  * @see          ChoiceFormat
  * @author       Mark Davis
--- a/src/java.base/share/classes/java/text/SimpleDateFormat.java	Sun Jan 08 23:15:57 2017 -0800
+++ b/src/java.base/share/classes/java/text/SimpleDateFormat.java	Mon Jan 09 14:06:32 2017 +0530
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -905,6 +905,7 @@
      * @param startDate During parsing, two digit years will be placed in the range
      * <code>startDate</code> to <code>startDate + 100 years</code>.
      * @see #get2DigitYearStart
+     * @throws NullPointerException if {@code startDate} is {@code null}.
      * @since 1.2
      */
     public void set2DigitYearStart(Date startDate) {
@@ -933,7 +934,7 @@
      * @param pos the formatting position. On input: an alignment field,
      * if desired. On output: the offsets of the alignment field.
      * @return the formatted date-time string.
-     * @exception NullPointerException if the given {@code date} is {@code null}.
+     * @exception NullPointerException if any of the parameters is {@code null}.
      */
     @Override
     public StringBuffer format(Date date, StringBuffer toAppendTo,