BufferedWriters 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 @@ public class BufferedWriter extends Writer {
/**
* Writes a portion of a String.
*
- * 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) {
diff --git a/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java b/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java
index ed27bbae314..773b59614d9 100644
--- a/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/CharArrayWriter.java
@@ -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 @@ class CharArrayWriter extends Writer {
* @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 @@ class CharArrayWriter extends Writer {
* @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) {
diff --git a/jdk/src/java.base/share/classes/java/io/FilterWriter.java b/jdk/src/java.base/share/classes/java/io/FilterWriter.java
index 303c674e0c0..8272b3cc8bf 100644
--- a/jdk/src/java.base/share/classes/java/io/FilterWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/FilterWriter.java
@@ -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 @@ public abstract class FilterWriter extends Writer {
* @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 @@ public abstract class FilterWriter extends Writer {
* @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);
diff --git a/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java b/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java
index 0d597e6bef4..4fdb148baaf 100644
--- a/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/OutputStreamWriter.java
@@ -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 @@ public class OutputStreamWriter extends Writer {
* @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 @@ public class OutputStreamWriter extends Writer {
* @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);
diff --git a/jdk/src/java.base/share/classes/java/io/PipedWriter.java b/jdk/src/java.base/share/classes/java/io/PipedWriter.java
index 02201fbec1a..a4534b8604c 100644
--- a/jdk/src/java.base/share/classes/java/io/PipedWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/PipedWriter.java
@@ -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 @@ public class PipedWriter extends Writer {
}
/**
- * Writes len characters from the specified character array
- * starting at offset off 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
- * IOException 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
- * broken,
+ *
+ * @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
+ * broken,
* {@link #connect(java.io.PipedReader) unconnected}, closed
* or an I/O error occurs.
*/
diff --git a/jdk/src/java.base/share/classes/java/io/PrintWriter.java b/jdk/src/java.base/share/classes/java/io/PrintWriter.java
index 662f930ef90..d516b8ef404 100644
--- a/jdk/src/java.base/share/classes/java/io/PrintWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/PrintWriter.java
@@ -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 @@ public class PrintWriter extends Writer {
* @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 @@ public class PrintWriter extends Writer {
* @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 {
diff --git a/jdk/src/java.base/share/classes/java/io/StringWriter.java b/jdk/src/java.base/share/classes/java/io/StringWriter.java
index 5d1babc3127..15022b353a8 100644
--- a/jdk/src/java.base/share/classes/java/io/StringWriter.java
+++ b/jdk/src/java.base/share/classes/java/io/StringWriter.java
@@ -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 @@ public class StringWriter extends Writer {
* @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 @@ public class StringWriter extends Writer {
* @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);
diff --git a/jdk/src/java.base/share/classes/java/io/Writer.java b/jdk/src/java.base/share/classes/java/io/Writer.java
index 5ad5e554fb3..17e8de3ef8a 100644
--- a/jdk/src/java.base/share/classes/java/io/Writer.java
+++ b/jdk/src/java.base/share/classes/java/io/Writer.java
@@ -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 @@ package java.io;
* 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 @@ public abstract class Writer implements Appendable, Closeable, Flushable {
* @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 @@ public abstract class Writer implements Appendable, Closeable, Flushable {
/**
* 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 @@ public abstract class Writer implements Appendable, Closeable, Flushable {
* 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