1 /* 2 * Copyright 2015 Google LLC 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.cloud; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.nio.channels.ReadableByteChannel; 22 23 /** 24 * A channel for reading data from a Google Cloud object. 25 * 26 * <p>Implementations of this class may buffer data internally to reduce remote calls. This 27 * interface implements {@link Restorable} to allow saving the reader's state to continue reading 28 * afterwards. 29 */ 30 public interface ReadChannel extends ReadableByteChannel, Closeable, Restorable<ReadChannel> { 31 32 /** 33 * Overridden to remove IOException. 34 * 35 * @see java.nio.channels.Channel#close() 36 */ 37 @Override close()38 void close(); 39 40 /** Set the offset to read from. */ seek(long position)41 void seek(long position) throws IOException; 42 43 /** 44 * Sets the minimum size that will be read by a single RPC. Read data will be locally buffered 45 * until consumed. 46 */ setChunkSize(int chunkSize)47 void setChunkSize(int chunkSize); 48 49 /** 50 * Captures the read channel state so that it can be saved and restored afterwards. 51 * 52 * @return a {@link RestorableState} object that contains the read channel state and can restore 53 * it afterwards. 54 */ 55 @Override capture()56 RestorableState<ReadChannel> capture(); 57 58 /** 59 * Limit the maximum number of bytes to be read from the objects content, counting from the 60 * beginning of the object, which will be available to read from this channel. If the limit is 61 * larger than the actual size of the content this will have no material impact. 62 * 63 * <p>If used in conjunction with {@link #seek(long)} the total number of returned bytes from this 64 * channel will be reduced by the number of bytes specified to seek. 65 * 66 * <p>The value provided as {@code limit} will define a <a target="_blank" rel="noopener 67 * noreferrer" 68 * href="https://en.wikipedia.org/wiki/Interval_(mathematics)#Classification_of_intervals">left-closed, 69 * right-open</a> interval along with either {@code 0} or any value provided to {@link 70 * #seek(long)}, i.e. {@code [}{@link #seek(long)}{@code , }{@link #limit(long)}{@code )}. 71 * 72 * <h3>An example to help illustrate the relationship</h3> 73 * 74 * Imagine some data {@code [A, B, C, D, E, F, G, H, I, J]}, 10 bytes total. 75 * 76 * <ol> 77 * <li>{@code limit(5)} would produce {@code [A, B, C, D, E]} 78 * <li>{@code seek(8)} would produce {@code [I, J]} 79 * <li>{@code seek(2)} {@code limit(5)} would produce {@code [C, D, E]} 80 * <li>{@code seek(3)} {@code limit(3)} would produce {@code []} 81 * </ol> 82 * 83 * <p><i>NOTE:</i>Implementers are not required to return a new instance from this method, however 84 * they are allowed to. Users of this method should always use the instance returned from this 85 * method. 86 * 87 * <p><i>Default Implementation:</i>By default, this method will simply return {@code this}. 88 * 89 * @param limit the maximum number of bytes to limit this channel to 90 * @return The instance of channel which will respect the limit. 91 * @throws UnsupportedOperationException If the {@code this} instances does not support limiting 92 * @since 2.4.0 93 */ limit(long limit)94 default ReadChannel limit(long limit) { 95 return this; 96 } 97 98 /** 99 * The currently defined limit for this channel. Initial value is {@link Long#MAX_VALUE} 100 * 101 * @return the current limit for this channel 102 * @throws UnsupportedOperationException If the {@code this} instances does not support limiting 103 * @since 2.4.0 104 */ limit()105 default long limit() { 106 return Long.MAX_VALUE; 107 } 108 } 109