Package s2.client

Class StreamClient

java.lang.Object

s2.client.BaseClient

s2.client.BasinClient

s2.client.StreamClient

All Implemented Interfaces:

AutoCloseable

public class StreamClient
extends BasinClient

Client for stream-level operations.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	StreamClient.AppendSessionRequestStream

Constructor Summary

Constructors

Constructor	Description
StreamClient(String streamName, String basin, Config config, io.grpc.ManagedChannel channel, ScheduledExecutorService executor)	Instantiates a new Stream client.

Method Summary

Modifier and Type	Method	Description
com.google.common.util.concurrent.ListenableFuture<AppendOutput>	append(AppendInput request)	Append a batch of records to a stream, using the unary append RPC.
StreamClient.AppendSessionRequestStream	appendSession(Consumer<AppendOutput> onResponse, Consumer<Throwable> onError, Runnable onComplete)	Start an unmanaged streaming append session.
com.google.common.util.concurrent.ListenableFuture<Long>	checkTail()	Check the sequence number that will be assigned to the next record on a stream.
ManagedAppendSession	managedAppendSession()	Start a managed append session.
ManagedReadSession	managedReadSession(ReadSessionRequest request, Integer maxBufferedBytes)	Retrieve batches of records from a stream continuously, using a buffered queue-backed iterator.
com.google.common.util.concurrent.ListenableFuture<ReadOutput>	read(ReadRequest request)	Retrieve a batch of records from a stream, using the unary read RPC.
ReadSession	readSession(ReadSessionRequest request, Consumer<ReadOutput> onResponse, Consumer<Throwable> onError)	Retrieve batches of records from a stream continuously.

Methods inherited from class s2.client.BasinClient

createStream, deleteStream, getStreamConfig, listStreams, reconfigureStream, streamClient

Methods inherited from class s2.client.BaseClient

close

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

StreamClient

public StreamClient(String streamName,
 String basin,
 Config config,
 io.grpc.ManagedChannel channel,
 ScheduledExecutorService executor)

Instantiates a new Stream client.

Most users will prefer to use the BasinClient.streamClient(String) method for construction.

Parameters:

streamName - the stream name

basin - the basin

config - the config

channel - the channel

executor - the executor

See Also:

• BasinClient.streamClient(java.lang.String)

Method Details

checkTail

public com.google.common.util.concurrent.ListenableFuture<Long> checkTail()

Check the sequence number that will be assigned to the next record on a stream.

Returns:

future of the next sequence number

read

public com.google.common.util.concurrent.ListenableFuture<ReadOutput> read(ReadRequest request)

Retrieve a batch of records from a stream, using the unary read RPC.

Parameters:

request - the request

Returns:

future of the read result

See Also:

• readSession(s2.types.ReadSessionRequest, java.util.function.Consumer<s2.types.ReadOutput>, java.util.function.Consumer<java.lang.Throwable>)

readSession

public ReadSession readSession(ReadSessionRequest request,
 Consumer<ReadOutput> onResponse,
 Consumer<Throwable> onError)

Retrieve batches of records from a stream continuously.

This entryway into a read session does internally perform retries (if configured via Config.maxRetries). It does not handle any form of backpressure or flow control directly.

The stream is interacted with via callbacks, which delegate to an underlying GRPC StreamObserver class.

Parameters:

request - the request

onResponse - function to run, sequentially, on each successful message

onError - function to run on an error

Returns:

a ReadSession instance

See Also:

• managedReadSession(s2.types.ReadSessionRequest, java.lang.Integer)

managedReadSession

public ManagedReadSession managedReadSession(ReadSessionRequest request,
 Integer maxBufferedBytes)

Retrieve batches of records from a stream continuously, using a buffered queue-backed iterator.

This entryway into a read session, similar to readSession(s2.types.ReadSessionRequest, java.util.function.Consumer<s2.types.ReadOutput>, java.util.function.Consumer<java.lang.Throwable>), will retry internally if configured.

The GRPC streaming response will be buffered, based on the `maxBufferedBytes` param, preventing situations where the result of a read accumulate faster than a user can handle.

Results are interacted with via an interator-like API, rather than via callbacks.

Parameters:

request - the request

maxBufferedBytes - the max allowed amount of read response metered bytes to keep in the buffer

Returns:

a ManagedReadSession instance

See Also:

• readSession(s2.types.ReadSessionRequest, java.util.function.Consumer<s2.types.ReadOutput>, java.util.function.Consumer<java.lang.Throwable>)

append

public com.google.common.util.concurrent.ListenableFuture<AppendOutput> append(AppendInput request)

Append a batch of records to a stream, using the unary append RPC.

Note that the choice of Config.appendRetryPolicy is important. Since appends are not idempotent by default, retries could cause duplicates in a stream. If you use-case cannot tolerate the potential of duplicate records, make sure to select AppendRetryPolicy.NO_SIDE_EFFECTS.

Parameters:

request - the request

Returns:

future of the append response

See Also:

• Config.appendRetryPolicy
• AppendRetryPolicy

appendSession

public StreamClient.AppendSessionRequestStream appendSession(Consumer<AppendOutput> onResponse,
 Consumer<Throwable> onError,
 Runnable onComplete)

Start an unmanaged streaming append session.

Append batches of records to a stream continuously, while guaranteeing pipelined requests are processed in order.

Most users will prefer to use managedAppendSession() instead.

Retries are not attempted, and no flow control is performed.

Parameters:

onResponse - function to run, sequentially, on each successful message

onError - function to run on an error, which will be a terminal message

onComplete - function to run on successful server-side completion of the session

Returns:

the append session request stream

managedAppendSession

public ManagedAppendSession managedAppendSession()

Start a managed append session.

Append batches of records to a stream continuously, while guaranteeing pipelined requests are processed in order.

Unlike with appendSession(java.util.function.Consumer<s2.types.AppendOutput>, java.util.function.Consumer<java.lang.Throwable>, java.lang.Runnable), this session will attempt to retry intermittent failures if so elected.

Note that the choice of Config.appendRetryPolicy is important. Since appends are not idempotent by default, retries could cause duplicates in a stream. If you use-case cannot tolerate the potential of duplicate records, make sure to select AppendRetryPolicy.NO_SIDE_EFFECTS.

Returns:

the managed append session

See Also:

• Config.appendRetryPolicy
• AppendRetryPolicy