8130679: Writer/StringWriter.write methods do not specify index out bounds
Summary: Add throws tag indicating IndexOutOfBoundsExcepion to write() methods which have an index parameter.
Reviewed-by: chegar, prappo, rriggs
--- a/jdk/src/java.base/share/classes/java/io/BufferedWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/BufferedWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -153,13 +153,18 @@
* needed. If the requested length is at least as large as the buffer,
* however, then this method will flush the buffer and write the characters
* directly to the underlying stream. Thus redundant
- * <code>BufferedWriter</code>s will not copy data unnecessarily.
+ * {@code BufferedWriter}s will not copy data unnecessarily.
*
* @param cbuf A character array
* @param off Offset from which to start reading characters
* @param len Number of characters to write
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(char cbuf[], int off, int len) throws IOException {
synchronized (lock) {
@@ -195,17 +200,24 @@
/**
* Writes a portion of a String.
*
- * <p> If the value of the {@code len} parameter is negative then no
- * characters are written. This is contrary to the specification of this
- * method in the {@linkplain java.io.Writer#write(java.lang.String,int,int)
- * superclass}, which requires that an {@link IndexOutOfBoundsException} be
- * thrown.
+ * @implSpec
+ * While the specification of this method in the
+ * {@linkplain java.io.Writer#write(java.lang.String,int,int) superclass}
+ * recommends that an {@link IndexOutOfBoundsException} be thrown
+ * if {@code len} is negative or {@code off + len} is negative,
+ * the implementation in this class does not throw such an exception in
+ * these cases but instead simply writes no characters.
*
* @param s String to be written
* @param off Offset from which to start reading characters
* @param len Number of characters to be written
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative,
+ * or {@code off + len} is greater than the length
+ * of the given string
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(String s, int off, int len) throws IOException {
synchronized (lock) {
--- a/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -91,6 +91,11 @@
* @param c the data to be written
* @param off the start offset in the data
* @param len the number of chars that are written
+ *
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
*/
public void write(char c[], int off, int len) {
if ((off < 0) || (off > c.length) || (len < 0) ||
@@ -114,6 +119,11 @@
* @param str String to be written from
* @param off Offset from which to start reading characters
* @param len Number of characters to be written
+ *
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given string
*/
public void write(String str, int off, int len) {
synchronized (lock) {
--- a/jdk/src/java.base/share/classes/java/io/FilterWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/FilterWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -72,7 +72,12 @@
* @param off Offset from which to start reading characters
* @param len Number of characters to be written
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If the values of the {@code off} and {@code len} parameters
+ * cause the corresponding method of the underlying {@code Writer}
+ * to throw an {@code IndexOutOfBoundsException}
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(char cbuf[], int off, int len) throws IOException {
out.write(cbuf, off, len);
@@ -85,7 +90,12 @@
* @param off Offset from which to start reading characters
* @param len Number of characters to be written
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If the values of the {@code off} and {@code len} parameters
+ * cause the corresponding method of the underlying {@code Writer}
+ * to throw an {@code IndexOutOfBoundsException}
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(String str, int off, int len) throws IOException {
out.write(str, off, len);
--- a/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -202,7 +202,12 @@
* @param off Offset from which to start writing characters
* @param len Number of characters to write
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(char cbuf[], int off, int len) throws IOException {
se.write(cbuf, off, len);
@@ -215,7 +220,12 @@
* @param off Offset from which to start writing characters
* @param len Number of characters to write
*
- * @exception IOException If an I/O error occurs
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given string
+ *
+ * @throws IOException If an I/O error occurs
*/
public void write(String str, int off, int len) throws IOException {
se.write(str, off, len);
--- a/jdk/src/java.base/share/classes/java/io/PipedWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/PipedWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -125,19 +125,25 @@
}
/**
- * Writes <code>len</code> characters from the specified character array
- * starting at offset <code>off</code> to this piped output stream.
+ * Writes {@code len} characters from the specified character array
+ * starting at offset {@code off} to this piped output stream.
* This method blocks until all the characters are written to the output
* stream.
* If a thread was reading data characters from the connected piped input
* stream, but the thread is no longer alive, then an
- * <code>IOException</code> is thrown.
+ * {@code IOException} is thrown.
*
* @param cbuf the data.
* @param off the start offset in the data.
* @param len the number of characters to write.
- * @exception IOException if the pipe is
- * <a href=PipedOutputStream.html#BROKEN> <code>broken</code></a>,
+ *
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
+ *
+ * @throws IOException if the pipe is
+ * <a href=PipedOutputStream.html#BROKEN><code>broken</code></a>,
* {@link #connect(java.io.PipedReader) unconnected}, closed
* or an I/O error occurs.
*/
--- a/jdk/src/java.base/share/classes/java/io/PrintWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/PrintWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -410,6 +410,11 @@
* @param buf Array of characters
* @param off Offset from which to start writing characters
* @param len Number of characters to write
+ *
+ * @throws IndexOutOfBoundsException
+ * If the values of the {@code off} and {@code len} parameters
+ * cause the corresponding method of the underlying {@code Writer}
+ * to throw an {@code IndexOutOfBoundsException}
*/
public void write(char buf[], int off, int len) {
try {
@@ -440,6 +445,11 @@
* @param s A String
* @param off Offset from which to start writing characters
* @param len Number of characters to write
+ *
+ * @throws IndexOutOfBoundsException
+ * If the values of the {@code off} and {@code len} parameters
+ * cause the corresponding method of the underlying {@code Writer}
+ * to throw an {@code IndexOutOfBoundsException}
*/
public void write(String s, int off, int len) {
try {
--- a/jdk/src/java.base/share/classes/java/io/StringWriter.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/StringWriter.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -83,6 +83,11 @@
* @param cbuf Array of characters
* @param off Offset from which to start writing characters
* @param len Number of characters to write
+ *
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
*/
public void write(char cbuf[], int off, int len) {
if ((off < 0) || (off > cbuf.length) || (len < 0) ||
@@ -107,6 +112,11 @@
* @param str String to be written
* @param off Offset from which to start writing characters
* @param len Number of characters to write
+ *
+ * @throws IndexOutOfBoundsException
+ * If {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given string
*/
public void write(String str, int off, int len) {
buf.append(str, off, off + len);
--- a/jdk/src/java.base/share/classes/java/io/Writer.java Tue May 17 22:28:00 2016 +0300
+++ b/jdk/src/java.base/share/classes/java/io/Writer.java Tue May 17 16:04:53 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2016, 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
@@ -32,12 +32,11 @@
* Most subclasses, however, will override some of the methods defined here in
* order to provide higher efficiency, additional functionality, or both.
*
- * @see Writer
* @see BufferedWriter
* @see CharArrayWriter
* @see FilterWriter
* @see OutputStreamWriter
- * @see FileWriter
+ * @see FileWriter
* @see PipedWriter
* @see PrintWriter
* @see StringWriter
@@ -139,6 +138,12 @@
* @param len
* Number of characters to write
*
+ * @throws IndexOutOfBoundsException
+ * Implementations should throw this exception
+ * if {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
+ * of the given array
+ *
* @throws IOException
* If an I/O error occurs
*/
@@ -160,6 +165,11 @@
/**
* Writes a portion of a string.
*
+ * @implSpec
+ * The implementation in this class throws an
+ * {@code IndexOutOfBoundsException} for the indicated conditions;
+ * overriding methods may choose to do otherwise.
+ *
* @param str
* A String
*
@@ -170,8 +180,9 @@
* Number of characters to write
*
* @throws IndexOutOfBoundsException
- * If {@code off} is negative, or {@code len} is negative,
- * or {@code off+len} is negative or greater than the length
+ * Implementations should throw this exception
+ * if {@code off} is negative, or {@code len} is negative,
+ * or {@code off + len} is negative or greater than the length
* of the given string
*
* @throws IOException