com.google.api.gax.batching

Class BatchingSettings

java.lang.Object

com.google.api.gax.batching.BatchingSettings

public abstract class BatchingSettings
extends java.lang.Object

Represents the batching settings to use for an API method that is capable of batching.

By default the settings are configured to not use batching (i.e. the batch size threshold is 1). This is the safest default behavior, which has meaning in all possible scenarios. Users are expected to configure actual batching thresholds explicitly: the element count, the request bytes count and the delay.

Warning: With the wrong settings, it is possible to cause long periods of dead waiting time.

When batching is turned on for an API method, a call to that method will result in the request being queued up with other requests. When any of the set thresholds are reached, the queued up requests are packaged together in a batch and set to the service as a single RPC. When the response comes back, it is split apart into individual responses according to the individual input requests.

There are several supported thresholds:

• Delay Threshold: Counting from the time that the first message is queued, once this delay has passed, then send the batch. The default value is 1 millisecond.
• Message Count Threshold: Once this many messages are queued, send all of the messages in a single call, even if the delay threshold hasn't elapsed yet. The default value is 1 message.
• Request Byte Threshold: Once the number of bytes in the batched request reaches this threshold, send all of the messages in a single call, even if neither the delay or message count thresholds have been exceeded yet. The default value is 1 byte.

These thresholds are treated as triggers, not as limits. Thus, if a request is made with 2x the message count threshold, it will not be split apart (unless one of the limits listed further down is crossed); only one batch will be sent. Each threshold is an independent trigger and doesn't have any knowledge of the other thresholds.

Two of the values above also have limits:

• Message Count Limit: The limit of the number of messages that the server will accept in a single request.
• Request Byte Limit: The limit of the byte size of a request that the server will accept.

For these values, individual requests that surpass the limit are rejected, and the batching logic will not batch together requests if the resulting batch will surpass the limit. Thus, a batch can be sent that is actually under the threshold if the next request would put the combined request over the limit.

Batching also supports FlowControl. This can be used to prevent the batching implementation from accumulating messages without limit, resulting eventually in an OutOfMemory exception. This can occur if messages are created and added to batching faster than they can be processed. The flow control behavior is controlled using FlowControlSettings.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BatchingSettings.Builder See the class documentation of BatchingSettings for a description of the different values that can be set.

Constructor Summary

Constructors

Constructor and Description
BatchingSettings()

Method Summary

Modifier and Type	Method and Description
abstract org.threeten.bp.Duration	getDelayThreshold() Get the delay threshold to use for batching.
abstract java.lang.Long	getElementCountThreshold() Get the element count threshold to use for batching.
abstract FlowControlSettings	getFlowControlSettings() Get the flow control settings to use.
abstract java.lang.Boolean	getIsEnabled() Returns the Boolean object to indicate if the batching is enabled.
abstract java.lang.Long	getRequestByteThreshold() Get the request byte threshold to use for batching.
static BatchingSettings.Builder	newBuilder() Get a new builder.
abstract BatchingSettings.Builder	toBuilder() Get a builder with the same values as this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

BatchingSettings

public BatchingSettings()

Method Detail

getElementCountThreshold

@Nullable
public abstract java.lang.Long getElementCountThreshold()

Get the element count threshold to use for batching.

getRequestByteThreshold

@Nullable
public abstract java.lang.Long getRequestByteThreshold()

Get the request byte threshold to use for batching.

getDelayThreshold

@Nullable
public abstract org.threeten.bp.Duration getDelayThreshold()

Get the delay threshold to use for batching.

getIsEnabled

public abstract java.lang.Boolean getIsEnabled()

Returns the Boolean object to indicate if the batching is enabled. Default to true

getFlowControlSettings

public abstract FlowControlSettings getFlowControlSettings()

Get the flow control settings to use.

newBuilder

public static BatchingSettings.Builder newBuilder()

Get a new builder.

toBuilder

public abstract BatchingSettings.Builder toBuilder()

Get a builder with the same values as this object.