Interface ReadChannel (2.28.0)

public interface ReadChannel extends ReadableByteChannel, Closeable, Restorable<ReadChannel>

A channel for reading data from a Google Cloud object.

Implementations of this class may buffer data internally to reduce remote calls. This interface implements Restorable to allow saving the reader's state to continue reading afterwards.

Implements

ReadableByteChannel, Closeable, com.google.cloud.Restorable<com.google.cloud.ReadChannel>

Methods

capture()

public abstract RestorableState<ReadChannel> capture()

Captures the read channel state so that it can be saved and restored afterwards.

Returns
TypeDescription
RestorableState<ReadChannel>

a RestorableState object that contains the read channel state and can restore it afterwards.

close()

public abstract void close()

Overridden to remove IOException. See Also: java.nio.channels.Channel#close()

limit()

public default long limit()

The currently defined limit for this channel. Initial value is Long#MAX_VALUE

Returns
TypeDescription
long

the current limit for this channel

limit(long limit)

public default ReadChannel limit(long limit)

Limit the maximum number of bytes to be read from the objects content, counting from the beginning of the object, which will be available to read from this channel. If the limit is larger than the actual size of the content this will have no material impact.

If used in conjunction with #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 limit will define a <a target="blank"rel="noopener noreferrer"href="https://en.wikipedia.org/wiki/Interval(mathematics)#Classification_of_intervals">left-closed, right-open interval along with either 0 or any value provided to #seek(long), i.e. [#seek(long), #limit(long)).

An example to help illustrate the relationship

Imagine some data [A, B, C, D, E, F, G, H, I, J], 10 bytes total.

  1. limit(5) would produce [A, B, C, D, E]
  2. seek(8) would produce [I, J]
  3. seek(2) limit(5) would produce [C, D, E]
  4. seek(3) limit(3) would produce []

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.

Default Implementation:By default, this method will simply return this.

Parameter
NameDescription
limitlong

the maximum number of bytes to limit this channel to

Returns
TypeDescription
ReadChannel

The instance of channel which will respect the limit.

seek(long position)

public abstract void seek(long position)

Set the offset to read from.

Parameter
NameDescription
positionlong
Exceptions
TypeDescription
IOException

setChunkSize(int chunkSize)

public abstract void setChunkSize(int chunkSize)

Sets the minimum size that will be read by a single RPC. Read data will be locally buffered until consumed.

Parameter
NameDescription
chunkSizeint