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.
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.
Closes this Batcher by preventing new elements from being added, then flushing the existing
elements and waiting for all the outstanding work to be resolved.
Closes this Batcher by preventing new elements from being added, then flushing the existing
elements and waiting for all the outstanding work to be resolved. If all of the outstanding
work has not been resolved, then a BatchingException will be thrown with details of the
remaining work. The batcher will remain in a closed state and will not allow additional
elements to be added.
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
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eBatcher\u003c/code\u003e interface allows for the accumulation and batch processing of elements, optimizing for high throughput at the expense of latency.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eBatcher\u003c/code\u003e instances are not thread-safe, requiring a new instance per thread for multi-threaded use.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eadd\u003c/code\u003e method queues elements for future batching, with an \u003ccode\u003eApiFuture\u003c/code\u003e returned to track each element's individual result upon extraction from the batch response.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eclose\u003c/code\u003e method prevents new elements from being added and processes existing ones, with a timeout option to handle cases where outstanding work remains unresolved.\u003c/p\u003e\n"],["\u003cp\u003eThere are multiple versions available, ranging from 2.7.1 to 2.63.1 which is the latest, with documentation available for each version.\u003c/p\u003e\n"]]],[],null,["# Interface Batcher<ElementT,ElementResultT> (2.69.0)\n\nVersion latestkeyboard_arrow_down\n\n- [2.69.0 (latest)](/java/docs/reference/gax/latest/com.google.api.gax.batching.Batcher)\n- [2.68.2](/java/docs/reference/gax/2.68.2/com.google.api.gax.batching.Batcher)\n- [2.67.0](/java/docs/reference/gax/2.67.0/com.google.api.gax.batching.Batcher)\n- [2.66.0](/java/docs/reference/gax/2.66.0/com.google.api.gax.batching.Batcher)\n- [2.65.0](/java/docs/reference/gax/2.65.0/com.google.api.gax.batching.Batcher)\n- [2.63.1](/java/docs/reference/gax/2.63.1/com.google.api.gax.batching.Batcher)\n- [2.62.0](/java/docs/reference/gax/2.62.0/com.google.api.gax.batching.Batcher)\n- [2.61.0](/java/docs/reference/gax/2.61.0/com.google.api.gax.batching.Batcher)\n- [2.60.0](/java/docs/reference/gax/2.60.0/com.google.api.gax.batching.Batcher)\n- [2.59.1](/java/docs/reference/gax/2.59.1/com.google.api.gax.batching.Batcher)\n- [2.58.0](/java/docs/reference/gax/2.58.0/com.google.api.gax.batching.Batcher)\n- [2.57.0](/java/docs/reference/gax/2.57.0/com.google.api.gax.batching.Batcher)\n- [2.55.0](/java/docs/reference/gax/2.55.0/com.google.api.gax.batching.Batcher)\n- [2.54.1](/java/docs/reference/gax/2.54.1/com.google.api.gax.batching.Batcher)\n- [2.53.0](/java/docs/reference/gax/2.53.0/com.google.api.gax.batching.Batcher)\n- [2.52.0](/java/docs/reference/gax/2.52.0/com.google.api.gax.batching.Batcher)\n- [2.51.0](/java/docs/reference/gax/2.51.0/com.google.api.gax.batching.Batcher)\n- [2.50.0](/java/docs/reference/gax/2.50.0/com.google.api.gax.batching.Batcher)\n- [2.49.0](/java/docs/reference/gax/2.49.0/com.google.api.gax.batching.Batcher)\n- [2.48.1](/java/docs/reference/gax/2.48.1/com.google.api.gax.batching.Batcher)\n- [2.47.0](/java/docs/reference/gax/2.47.0/com.google.api.gax.batching.Batcher)\n- [2.46.1](/java/docs/reference/gax/2.46.1/com.google.api.gax.batching.Batcher)\n- [2.45.0](/java/docs/reference/gax/2.45.0/com.google.api.gax.batching.Batcher)\n- [2.43.0](/java/docs/reference/gax/2.43.0/com.google.api.gax.batching.Batcher)\n- [2.42.0](/java/docs/reference/gax/2.42.0/com.google.api.gax.batching.Batcher)\n- [2.41.0](/java/docs/reference/gax/2.41.0/com.google.api.gax.batching.Batcher)\n- [2.39.0](/java/docs/reference/gax/2.39.0/com.google.api.gax.batching.Batcher)\n- [2.38.0](/java/docs/reference/gax/2.38.0/com.google.api.gax.batching.Batcher)\n- [2.37.0](/java/docs/reference/gax/2.37.0/com.google.api.gax.batching.Batcher)\n- [2.36.0](/java/docs/reference/gax/2.36.0/com.google.api.gax.batching.Batcher)\n- [2.35.0](/java/docs/reference/gax/2.35.0/com.google.api.gax.batching.Batcher)\n- [2.34.1](/java/docs/reference/gax/2.34.1/com.google.api.gax.batching.Batcher)\n- [2.33.0](/java/docs/reference/gax/2.33.0/com.google.api.gax.batching.Batcher)\n- [2.32.1](/java/docs/reference/gax/2.32.1/com.google.api.gax.batching.Batcher)\n- [2.31.1](/java/docs/reference/gax/2.31.1/com.google.api.gax.batching.Batcher)\n- [2.30.1](/java/docs/reference/gax/2.30.1/com.google.api.gax.batching.Batcher)\n- [2.24.0](/java/docs/reference/gax/2.24.0/com.google.api.gax.batching.Batcher)\n- [2.23.3](/java/docs/reference/gax/2.23.3/com.google.api.gax.batching.Batcher)\n- [2.22.0](/java/docs/reference/gax/2.22.0/com.google.api.gax.batching.Batcher)\n- [2.21.0](/java/docs/reference/gax/2.21.0/com.google.api.gax.batching.Batcher)\n- [2.20.1](/java/docs/reference/gax/2.20.1/com.google.api.gax.batching.Batcher)\n- [2.19.6](/java/docs/reference/gax/2.19.6/com.google.api.gax.batching.Batcher)\n- [2.18.7](/java/docs/reference/gax/2.18.7/com.google.api.gax.batching.Batcher)\n- [2.17.0](/java/docs/reference/gax/2.17.0/com.google.api.gax.batching.Batcher)\n- [2.16.0](/java/docs/reference/gax/2.16.0/com.google.api.gax.batching.Batcher)\n- [2.15.0](/java/docs/reference/gax/2.15.0/com.google.api.gax.batching.Batcher)\n- [2.14.0](/java/docs/reference/gax/2.14.0/com.google.api.gax.batching.Batcher)\n- [2.13.0](/java/docs/reference/gax/2.13.0/com.google.api.gax.batching.Batcher)\n- [2.12.2](/java/docs/reference/gax/2.12.2/com.google.api.gax.batching.Batcher)\n- [2.11.0](/java/docs/reference/gax/2.11.0/com.google.api.gax.batching.Batcher)\n- [2.10.0](/java/docs/reference/gax/2.10.0/com.google.api.gax.batching.Batcher)\n- [2.9.0](/java/docs/reference/gax/2.9.0/com.google.api.gax.batching.Batcher)\n- [2.8.1](/java/docs/reference/gax/2.8.1/com.google.api.gax.batching.Batcher)\n- [2.7.1](/java/docs/reference/gax/2.7.1/com.google.api.gax.batching.Batcher) \n\n public interface Batcher\u003cElementT,ElementResultT\u003e extends AutoCloseable\n\nRepresents a batching context where individual elements will be accumulated and flushed in a\nlarge batch request at some point in the future. The buffered elements can be flushed manually or\nwhen triggered by an internal threshold. This is intended to be used for high throughput\nscenarios at the cost of latency.\n\nBatcher instances are not thread safe. To use across different threads, create a new Batcher\ninstance per thread. \n\nImplements\n----------\n\n[AutoCloseable](https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html)\n\nStatic Fields\n-------------\n\n### THROTTLED_TIME_KEY\n\n public static final ApiCallContext.Key\u003cLong\u003e THROTTLED_TIME_KEY\n\n[ApiCallContext.Key](/java/docs/reference/gax/latest/com.google.api.gax.rpc.ApiCallContext.Key) for tracking batch total throttled time\n\nMethods\n-------\n\n### add(ElementT entry)\n\n public abstract ApiFuture\u003cElementResultT\u003e add(ElementT entry)\n\nQueues the passed in element to be sent at some point in the future.\n\nThe element will be sent as part of a larger batch request at some point in the future. The\nreturned [ApiFuture](https://cloud.google.com/java/docs/reference/api-common/latest/com.google.api.core.ApiFuture.html) will be resolved once the result for the element has been extracted\nfrom the batch response.\n\nNote: Cancelling returned result simply marks the future cancelled, It would not stop the\nbatch request.\n\n### cancelOutstanding()\n\n public abstract void cancelOutstanding()\n\nCancels all outstanding batch RPCs.\n\n### close()\n\n public abstract void close()\n\nCloses this Batcher by preventing new elements from being added, then flushing the existing\nelements and waiting for all the outstanding work to be resolved.\n\n### close(Duration timeout)\n\n public abstract void close(Duration timeout)\n\nCloses this Batcher by preventing new elements from being added, then flushing the existing\nelements and waiting for all the outstanding work to be resolved. If all of the outstanding\nwork has not been resolved, then a [BatchingException](/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingException) will be thrown with details of the\nremaining work. The batcher will remain in a closed state and will not allow additional\nelements to be added.\n\n### closeAsync()\n\n public abstract ApiFuture\u003cVoid\u003e closeAsync()\n\nCloses this Batcher by preventing new elements from being added, and then sending outstanding\nelements. The returned future will be resolved when the last element completes\n\n### flush()\n\n public abstract void flush()\n\nSynchronously sends any pending elements as a batch and waits for all outstanding batches to be\ncomplete.\n\n### sendOutstanding()\n\n public abstract void sendOutstanding()\n\nSends accumulated elements asynchronously for batching.\n\nNote: This method can be invoked concurrently unlike #add and #close, which\ncan only be called from a single user thread. Please take caution to avoid race condition."]]
