From 8b574f66c6e77b31ec8d544319a116f5c19804b9 Mon Sep 17 00:00:00 2001 From: BenWhitehead Date: Thu, 15 Dec 2022 15:09:12 -0500 Subject: [PATCH] docs: update javadocs for ReadChannel to be more clear about the behavior (#1050) --- .../java/com/google/cloud/ReadChannel.java | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/google-cloud-core/src/main/java/com/google/cloud/ReadChannel.java b/google-cloud-core/src/main/java/com/google/cloud/ReadChannel.java index 781326fa7a..effc33ee8e 100644 --- a/google-cloud-core/src/main/java/com/google/cloud/ReadChannel.java +++ b/google-cloud-core/src/main/java/com/google/cloud/ReadChannel.java @@ -37,6 +37,7 @@ public interface ReadChannel extends ReadableByteChannel, Closeable, Restorable< @Override void close(); + /** Set the offset to read from. */ void seek(long position) throws IOException; /** @@ -62,6 +63,23 @@ public interface ReadChannel extends ReadableByteChannel, Closeable, Restorable< *

If used in conjunction with {@link #seek(long)} the total number of returned bytes from this * channel will be reduced by the number of bytes specified to seek. * + *

The value provided as {@code limit} will define a left-closed, + * right-open interval along with either {@code 0} or any value provided to {@link + * #seek(long)}, i.e. {@code [}{@link #seek(long)}{@code , }{@link #limit(long)}{@code )}. + * + *

An example to help illustrate the relationship

+ * + * Imagine some data {@code [A, B, C, D, E, F, G, H, I, J]}, 10 bytes total. + * + *
    + *
  1. {@code limit(5)} would produce {@code [A, B, C, D, E]} + *
  2. {@code seek(8)} would produce {@code [I, J]} + *
  3. {@code seek(2)} {@code limit(5)} would produce {@code [C, D, E]} + *
  4. {@code seek(3)} {@code limit(3)} would produce {@code []} + *
+ * *

NOTE:Implementers are not required to return a new instance from this method, however * they are allowed to. Users of this method should always use the instance returned from this * method.