From 7b743ac87f174593f4cf3a9504b9d712cccec5f0 Mon Sep 17 00:00:00 2001 From: Todd Lipcon Date: Fri, 8 Jun 2012 19:54:42 +0000 Subject: [PATCH] HADOOP-8244. Improve comments on ByteBufferReadable.read. Contributed by Henry Robinson. (svn merge -c 1309625 from trunk) git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/branches/branch-2@1348209 13f79535-47bb-0310-9956-ffa450edef68 --- .../hadoop-common/CHANGES.txt | 3 +++ .../apache/hadoop/fs/ByteBufferReadable.java | 22 ++++++++++++++----- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/hadoop-common-project/hadoop-common/CHANGES.txt b/hadoop-common-project/hadoop-common/CHANGES.txt index fa46641f0b6..b8959479d8f 100644 --- a/hadoop-common-project/hadoop-common/CHANGES.txt +++ b/hadoop-common-project/hadoop-common/CHANGES.txt @@ -34,6 +34,9 @@ Release 2.0.1-alpha - UNRELEASED HADOOP-8358. Config-related WARN for dfs.web.ugi can be avoided. (harsh) + HADOOP-8244. Improve comments on ByteBufferReadable.read. (Henry Robinson + via atm) + BUG FIXES HADOOP-8372. NetUtils.normalizeHostName() incorrectly handles hostname diff --git a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ByteBufferReadable.java b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ByteBufferReadable.java index f47269c9c97..e18a1151499 100644 --- a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ByteBufferReadable.java +++ b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ByteBufferReadable.java @@ -28,18 +28,28 @@ public interface ByteBufferReadable { /** * Reads up to buf.remaining() bytes into buf. Callers should use * buf.limit(..) to control the size of the desired read. - * - * After the call, buf.position() should be unchanged, and therefore any data - * can be immediately read from buf. - * + *

+ * After a successful call, buf.position() and buf.limit() should be + * unchanged, and therefore any data can be immediately read from buf. + * buf.mark() may be cleared or updated. + *

+ * In the case of an exception, the values of buf.position() and buf.limit() + * are undefined, and callers should be prepared to recover from this + * eventuality. + *

* Many implementations will throw {@link UnsupportedOperationException}, so * callers that are not confident in support for this method from the * underlying filesystem should be prepared to handle that exception. + *

+ * Implementations should treat 0-length requests as legitimate, and must not + * signal an error upon their receipt. * * @param buf - * the ByteBuffer to receive the results of the read operation + * the ByteBuffer to receive the results of the read operation. Up to + * buf.limit() - buf.position() bytes may be read. * @return the number of bytes available to read from buf - * @throws IOException if there is some error performing the read + * @throws IOException + * if there is some error performing the read */ public int read(ByteBuffer buf) throws IOException; }