From 58bb6555e783e4627f57c3c8281183c474d581c9 Mon Sep 17 00:00:00 2001 From: Brian Burkhalter Date: Tue, 27 Jun 2023 15:28:01 +0000 Subject: [PATCH] 8222329: Readable read(CharBuffer) does not specify that 0 is returned when there is no remaining space in buffer Reviewed-by: rriggs, lancea, alanb --- src/java.base/share/classes/java/io/Reader.java | 12 ++++++++---- src/java.base/share/classes/java/lang/Readable.java | 12 ++++++++---- .../share/classes/java/nio/X-Buffer.java.template | 11 +++++++---- 3 files changed, 23 insertions(+), 12 deletions(-) diff --git a/src/java.base/share/classes/java/io/Reader.java b/src/java.base/share/classes/java/io/Reader.java index b29a8c05f97..5dbe4ab5fae 100644 --- a/src/java.base/share/classes/java/io/Reader.java +++ b/src/java.base/share/classes/java/io/Reader.java @@ -189,14 +189,18 @@ public abstract class Reader implements Readable, Closeable { * Attempts to read characters into the specified character buffer. * The buffer is used as a repository of characters as-is: the only * changes made are the results of a put operation. No flipping or - * rewinding of the buffer is performed. + * rewinding of the buffer is performed. If the {@linkplain + * java.nio.CharBuffer#length length} of the specified character + * buffer is zero, then no characters will be read and zero will be + * returned. * * @param target the buffer to read characters into - * @return The number of characters added to the buffer, or - * -1 if this source of characters is at its end + * @return The number of characters added to the buffer, + * possibly zero, or -1 if this source of characters is at its end * @throws IOException if an I/O error occurs * @throws NullPointerException if target is null - * @throws java.nio.ReadOnlyBufferException if target is a read only buffer + * @throws java.nio.ReadOnlyBufferException if target is a read only buffer, + * even if its length is zero * @since 1.5 */ public int read(CharBuffer target) throws IOException { diff --git a/src/java.base/share/classes/java/lang/Readable.java b/src/java.base/share/classes/java/lang/Readable.java index 2cc40c0db02..2f33cf04827 100644 --- a/src/java.base/share/classes/java/lang/Readable.java +++ b/src/java.base/share/classes/java/lang/Readable.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2023, 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 @@ -40,14 +40,18 @@ public interface Readable { * Attempts to read characters into the specified character buffer. * The buffer is used as a repository of characters as-is: the only * changes made are the results of a put operation. No flipping or - * rewinding of the buffer is performed. + * rewinding of the buffer is performed. If the {@linkplain + * java.nio.CharBuffer#length length} of the specified character + * buffer is zero, then no characters will be read and zero will be + * returned. * * @param cb the buffer to read characters into * @return The number of {@code char} values added to the buffer, - * or -1 if this source of characters is at its end + * possibly zero, or -1 if this source of characters is at its end * @throws IOException if an I/O error occurs * @throws NullPointerException if cb is null - * @throws java.nio.ReadOnlyBufferException if cb is a read only buffer + * @throws java.nio.ReadOnlyBufferException if cb is a read only buffer, + * even if its length is zero */ public int read(java.nio.CharBuffer cb) throws IOException; } diff --git a/src/java.base/share/classes/java/nio/X-Buffer.java.template b/src/java.base/share/classes/java/nio/X-Buffer.java.template index 0120ed421c5..1339b6ef468 100644 --- a/src/java.base/share/classes/java/nio/X-Buffer.java.template +++ b/src/java.base/share/classes/java/nio/X-Buffer.java.template @@ -471,13 +471,16 @@ public abstract sealed class $Type$Buffer * Attempts to read characters into the specified character buffer. * The buffer is used as a repository of characters as-is: the only * changes made are the results of a put operation. No flipping or - * rewinding of the buffer is performed. + * rewinding of the buffer is performed. If the {@linkplain #length + * length} of the specified character buffer is zero, then no characters + * will be read and zero will be returned. * * @param target the buffer to read characters into - * @return The number of characters added to the buffer, or - * -1 if this source of characters is at its end + * @return The number of characters added to the buffer, + * possibly zero, or -1 if this source of characters is at its end * @throws IOException if an I/O error occurs - * @throws ReadOnlyBufferException if target is a read only buffer + * @throws ReadOnlyBufferException if target is a read only buffer, + * even if its length is zero * @since 1.5 */ public int read(CharBuffer target) throws IOException {