Interface Batcher<ElementT,ElementResultT> (2.20.0) 

public interface Batcher<ElementT,ElementResultT> extends AutoCloseable

Represents a batching context where individual elements will be accumulated and flushed in a large batch request at some point in the future. The buffered elements can be flushed manually or when triggered by an internal threshold. This is intended to be used for high throughput scenarios at the cost of latency.

Batcher instances are not thread safe. To use across different threads, create a new Batcher instance per thread.

Implements

AutoCloseable

Type Parameters

NameDescription
ElementT
ElementResultT

Static Fields

THROTTLED_TIME_KEY

public static final ApiCallContext.Key<Long> THROTTLED_TIME_KEY

ApiCallContext.Key for tracking batch total throttled time

Field Value
TypeDescription
Key<Long>

Methods

add(ElementT entry)

public abstract ApiFuture<ElementResultT> add(ElementT entry)

Queues the passed in element to be sent at some point in the future.

The element will be sent as part of a larger batch request at some point in the future. The returned ApiFuture will be resolved once the result for the element has been extracted from the batch response.

Note: Cancelling returned result simply marks the future cancelled, It would not stop the batch request.

Parameter
NameDescription
entryElementT
Returns
TypeDescription
com.google.api.core.ApiFuture<ElementResultT>

close()

public abstract void close()

Closes this Batcher by preventing new elements from being added, and then flushing the existing elements.

Exceptions
TypeDescription
InterruptedException

closeAsync()

public abstract ApiFuture<Void> closeAsync()

Closes this Batcher by preventing new elements from being added, and then sending outstanding elements. The returned future will be resolved when the last element completes

Returns
TypeDescription
com.google.api.core.ApiFuture<Void>

flush()

public abstract void flush()

Synchronously sends any pending elements as a batch and waits for all outstanding batches to be complete.

Exceptions
TypeDescription
InterruptedException

sendOutstanding()

public abstract void sendOutstanding()

Sends accumulated elements asynchronously for batching.

Note: This method can be invoked concurrently unlike #add and #close, which can only be called from a single user thread. Please take caution to avoid race condition.