4247235: (spec str) StringBuffer.insert(int, char[]) specification is inconsistent

Summary: Add blanket null-handling statement to StringBuilder and StringBuffer
Reviewed-by: mduigou

src/share/classes/java/lang/AbstractStringBuilder.java

@@ -35,6 +35,10 @@ import java.util.Arrays;
  * particular sequence of characters, but the length and content of the
  * sequence can be changed through certain method calls.
  *
+ * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
+ * or method in this class will cause a {@link NullPointerException} to be
+ * thrown.
+ *
  * @author      Michael McCloskey
  * @author      Martin Buchholz
  * @author      Ulf Zibis
@@ -334,8 +338,6 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
      * @param      srcEnd     stop copying at this offset.
      * @param      dst        the array to copy the data into.
      * @param      dstBegin   offset into {@code dst}.
-     * @throws     NullPointerException if {@code dst} is
-     *             {@code null}.
      * @throws     IndexOutOfBoundsException  if any of the following is true:
      *             <ul>
      *             <li>{@code srcBegin} is negative
@@ -1282,8 +1284,6 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
      *          object, then the index of the first character of the first
      *          such substring is returned; if it does not occur as a
      *          substring, {@code -1} is returned.
-     * @throws  java.lang.NullPointerException if {@code str} is
-     *          {@code null}.
      */
     public int indexOf(String str) {
         return indexOf(str, 0);
@@ -1303,8 +1303,6 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
      * @param   fromIndex   the index from which to start the search.
      * @return  the index within this string of the first occurrence of the
      *          specified substring, starting at the specified index.
-     * @throws  java.lang.NullPointerException if {@code str} is
-     *            {@code null}.
      */
     public int indexOf(String str, int fromIndex) {
         return String.indexOf(value, 0, count, str, fromIndex);
@@ -1325,8 +1323,6 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
      *          within this object, then the index of the first character of
      *          the last such substring is returned. If it does not occur as
      *          a substring, {@code -1} is returned.
-     * @throws  java.lang.NullPointerException  if {@code str} is
-     *          {@code null}.
      */
     public int lastIndexOf(String str) {
         return lastIndexOf(str, count);
@@ -1346,8 +1342,6 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
      * @param   fromIndex   the index to start the search from.
      * @return  the index within this sequence of the last occurrence of the
      *          specified substring.
-     * @throws  java.lang.NullPointerException if {@code str} is
-     *          {@code null}.
      */
     public int lastIndexOf(String str, int fromIndex) {
         return String.lastIndexOf(value, 0, count, str, fromIndex);

src/share/classes/java/lang/String.java

@@ -33,6 +33,7 @@ import java.util.Arrays;
 import java.util.Comparator;
 import java.util.Formatter;
 import java.util.Locale;
+import java.util.Objects;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.regex.PatternSyntaxException;
@@ -871,6 +872,8 @@ public final class String
         if (srcBegin > srcEnd) {
             throw new StringIndexOutOfBoundsException(srcEnd - srcBegin);
         }
+        Objects.requireNonNull(dst);
+
         int j = dstBegin;
         int n = srcEnd;
         int i = srcBegin;
@@ -2112,7 +2115,6 @@ public final class String
      *
      * @param s the sequence to search for
      * @return true if this string contains {@code s}, false otherwise
-     * @throws NullPointerException if {@code s} is {@code null}
      * @since 1.5
      */
     public boolean contains(CharSequence s) {
@@ -2219,8 +2221,6 @@ public final class String
      * @param  target The sequence of char values to be replaced
      * @param  replacement The replacement sequence of char values
      * @return  The resulting string
-     * @throws NullPointerException if {@code target} or
-     *         {@code replacement} is {@code null}.
      * @since 1.5
      */
     public String replace(CharSequence target, CharSequence replacement) {
@@ -2833,9 +2833,6 @@ public final class String
      *          href="../util/Formatter.html#detail">Details</a> section of the
      *          formatter class specification.
      *
-     * @throws  NullPointerException
-     *          If the {@code format} is {@code null}
-     *
      * @return  A formatted string
      *
      * @see  java.util.Formatter
@@ -2865,8 +2862,8 @@ public final class String
      *         limited by the maximum dimension of a Java array as defined by
      *         <cite>The Java&trade; Virtual Machine Specification</cite>.
      *         The behaviour on a
-     *         {@code null} argument depends on the <a
-     *         href="../util/Formatter.html#syntax">conversion</a>.
+     *         {@code null} argument depends on the
+     *         <a href="../util/Formatter.html#syntax">conversion</a>.
      *
      * @throws  java.util.IllegalFormatException
      *          If a format string contains an illegal syntax, a format
@@ -2877,9 +2874,6 @@ public final class String
      *          href="../util/Formatter.html#detail">Details</a> section of the
      *          formatter class specification
      *
-     * @throws  NullPointerException
-     *          If the {@code format} is {@code null}
-     *
      * @return  A formatted string
      *
      * @see  java.util.Formatter

src/share/classes/java/lang/StringBuffer.java

@@ -77,7 +77,11 @@ package java.lang;
  * the capacity, it is not necessary to allocate a new internal
  * buffer array. If the internal buffer overflows, it is
  * automatically made larger.
- *
+ * <p>
+ * Unless otherwise noted, passing a {@code null} argument to a constructor
+ * or method in this class will cause a {@link NullPointerException} to be
+ * thrown.
+ * <p>
  * As of  release JDK 5, this class has been supplemented with an equivalent
  * class designed for use by a single thread, {@link StringBuilder}.  The
  * {@code StringBuilder} class should generally be used in preference to
@@ -123,7 +127,6 @@ package java.lang;
      * {@code 16} plus the length of the string argument.
      *
      * @param   str   the initial contents of the buffer.
-     * @exception NullPointerException if {@code str} is {@code null}
      */
     public StringBuffer(String str) {
         super(str.length() + 16);
@@ -141,7 +144,6 @@ package java.lang;
      * {@code 16} is returned.
      *
      * @param      seq   the sequence to copy.
-     * @exception NullPointerException if {@code seq} is {@code null}
      * @since 1.5
      */
     public StringBuffer(CharSequence seq) {
@@ -228,7 +230,6 @@ package java.lang;
     }
 
     /**
-     * @throws NullPointerException {@inheritDoc}
      * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     @Override
@@ -584,7 +585,6 @@ package java.lang;
     }
 
     /**
-     * @throws NullPointerException {@inheritDoc}
      * @since      1.4
      */
     @Override
@@ -594,7 +594,6 @@ package java.lang;
     }
 
     /**
-     * @throws NullPointerException {@inheritDoc}
      * @since      1.4
      */
     @Override
@@ -603,7 +602,6 @@ package java.lang;
     }
 
     /**
-     * @throws NullPointerException {@inheritDoc}
      * @since      1.4
      */
     @Override
@@ -613,7 +611,6 @@ package java.lang;
     }
 
     /**
-     * @throws NullPointerException {@inheritDoc}
      * @since      1.4
      */
     @Override

src/share/classes/java/lang/StringBuilder.java

@@ -64,6 +64,10 @@ package java.lang;
  * use by multiple threads. If such synchronization is required then it is
  * recommended that {@link java.lang.StringBuffer} be used.
  *
+ * <p>Unless otherwise noted, passing a {@code null} argument to a constructor
+ * or method in this class will cause a {@link NullPointerException} to be
+ * thrown.
+ *
  * @author      Michael McCloskey
  * @see         java.lang.StringBuffer
  * @see         java.lang.String
@@ -103,7 +107,6 @@ public final class StringBuilder
      * {@code 16} plus the length of the string argument.
      *
      * @param   str   the initial contents of the buffer.
-     * @throws    NullPointerException if {@code str} is {@code null}
      */
     public StringBuilder(String str) {
         super(str.length() + 16);
@@ -117,7 +120,6 @@ public final class StringBuilder
      * {@code CharSequence} argument.
      *
      * @param      seq   the sequence to copy.
-     * @throws    NullPointerException if {@code seq} is {@code null}
      */
     public StringBuilder(CharSequence seq) {
         this(seq.length() + 16);
@@ -373,33 +375,21 @@ public final class StringBuilder
         return this;
     }
 
-    /**
-     * @throws NullPointerException {@inheritDoc}
-     */
     @Override
     public int indexOf(String str) {
         return super.indexOf(str);
     }
 
-    /**
-     * @throws NullPointerException {@inheritDoc}
-     */
     @Override
     public int indexOf(String str, int fromIndex) {
         return super.indexOf(str, fromIndex);
     }
 
-    /**
-     * @throws NullPointerException {@inheritDoc}
-     */
     @Override
     public int lastIndexOf(String str) {
         return super.lastIndexOf(str);
     }
 
-    /**
-     * @throws NullPointerException {@inheritDoc}
-     */
     @Override
     public int lastIndexOf(String str, int fromIndex) {
         return super.lastIndexOf(str, fromIndex);