Advanced usage

This guide outlines how to customize several of the more advanced aspects of the Java client library. A common pattern is that many of these features rely on the underlying Callable rather than the standard methods. The callable is generally a good place to look for other per-RPC features that aren't documented here.


The Java library provides a surface for setting timeouts on a per-call level. To use this feature you should use the callable object directly. For example, if calling GoogleAdsService.searchStream(), the timeout would be set as:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request = ...

  // Executes the API call, with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> result = googleAdsServiceClient
          GrpcCallContext.createDefault().withTimeout(Duration.of(5, ChronoUnit.MINUTES)));

The timeout currently cannot be increased beyond a maximum value of 1 hour. If this becomes an issue, it is usually best to split the query up and execute the chunks in parallel; this avoids the situation where a long running request fails and the only way to recover is to trigger the request again from the start.

Retry Settings

The Java library also provides a surface for configuring retry settings on a per-call level. To use this feature you should use the callable object directly. For example, if calling GoogleAdsService.searchStream(), the retry settings would be configured as follows:

    // Creates a context object with the custom retry settings.
    GrpcCallContext context = GrpcCallContext.createDefault()

    // Creates and issues a search Google Ads stream request.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request, context);

Startup time performance optimization

You may notice a small delay the first time a GoogleAdsClient instance is created. This is due to the fluent interface for services (GoogleAdsClient.getVersionXX()), which loads all the API classes at once in order to provide a more convenient mechanism for constructing service classes.

If the first request performance is in the critical path for your application, you should do the following steps:

  1. Create the GoogleAdsClient on startup, before serving user requests.

  2. Send a few warm up requests to the Google Ads API when the process first starts. For example:

// Runs some warmup requests.
try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Runs 5 warmup requests. In our profiling we see that 90% of performance
  // loss is only experienced on the first API call. After 3 subsequent calls we
  // saw a negligible improvement in performance.
  for (int i = 0; i < 5; ++i) {
    // Warmup queries are run with a nonexistant CID so the calls will fail. If
    // you have a CID that you know will be accessible with the OAuth
    // credentials provided you may want to provide that instead and avoid the
    // try-catch.
    try {"-1", "Warmup query");
    } catch (GoogleAdsException ex) {
      // Do nothing, we're expecting this to fail.

The warm up requests only need to be run once per process. Every subsequent service client creation will automatically reuse the preloaded classes.

Service client reuse

You should reuse service client instances where practical since each call to GoogleAdsClient.getVersionXXX().createYYYServiceClient() will create a new TCP connection.

Additionally you must make sure that you close the client when it's no longer required. Either this can be done in a try-with-resources block, or can be done by calling ServiceClient.close().