feat: add limit support to ReadChannel (#688)

Add new methods to ReadChannel to allow limiting of the channel independent of any chunk sizes or buffers.

###### Motivation
GCS supports range reads of objects, ReadChannel currently has `seek` to allow settings the begin offset, but doesn't provide limit to allow setting the end offset. The only alternative is to provide manually sized ByteBuffer(s) to read into that would have to track size externally.

This new feature allows the Channel itself to absorb the burden and prevent reading more bytes than necessary from GCS.

Author: BenWhitehead

java-core/google-cloud-core/clirr-ignored-differences.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- see https://www.mojohaus.org/clirr-maven-plugin/examples/ignored-differences.html -->
+<differences>
+    <!-- Clear doesn't know about default interface methods -->
+    <difference>
+        <differenceType>7012</differenceType>
+        <className>com/google/cloud/ReadChannel</className>
+        <method>* limit(long)</method>
+    </difference>
+    <difference>
+        <differenceType>7012</differenceType>
+        <className>com/google/cloud/ReadChannel</className>
+        <method>long limit()</method>
+    </difference>
+</differences>

java-core/google-cloud-core/src/main/java/com/google/cloud/ReadChannel.java

@@ -53,4 +53,34 @@ public interface ReadChannel extends ReadableByteChannel, Closeable, Restorable<
    */
   @Override
   RestorableState<ReadChannel> capture();
+
+  /**
+   * Limit the maximum number of bytes available to be read from this channel. If the limit is
+   * larger than the actual size of the content this will have no material impact.
+   *
+   * <p><i>NOTE:</i>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.
+   *
+   * <p><i>Default Implementation:</i>By default, this method will simply return {@code this}.
+   *
+   * @param limit the maximum number of bytes to limit this channel to
+   * @return The instance of channel which will respect the limit.
+   * @throws UnsupportedOperationException If the {@code this} instances does not support limiting
+   * @since 2.4.0
+   */
+  default ReadChannel limit(long limit) {
+    return this;
+  }
+
+  /**
+   * The currently defined limit for this channel. Initial value is {@link Long#MAX_VALUE}
+   *
+   * @return the current limit for this channel
+   * @throws UnsupportedOperationException If the {@code this} instances does not support limiting
+   * @since 2.4.0
+   */
+  default long limit() {
+    return Long.MAX_VALUE;
+  }
 }