Using Cloud Client Libraries

To make sure that your projects have compatible versions of Cloud Client Libraries, use the versions specified in the Google Cloud Libraries Bill of Materials (BOM). The libraries in the BOM don't have dependency conflicts that would manifest as NoSuchMethodError or NoClassDefFoundError.

The BOM is necessary because Google publishes over two hundred open source Java libraries that make it easier to use services in Google Cloud. The Google Cloud libraries depend on several foundational libraries that can be used for general purposes.

These recommendations apply to the components of the following libraries:

Updating your project to use the BOM

To make sure that your projects uses compatible versions of the libraries and their component artifacts, import com.google.cloud:libraries-bom and use the BOM to specify dependency versions. Be sure to remove any versions that you set previously.

If you encounter compatibility issues with protobuf-java 4.x, update your codebase and dependencies to ensure compatibility, see release notes of libraries-bom v26.50.0 for potential compatibility issues. If this is not feasible, use com.google.cloud:libraries-bom-protobuf3 as a workaround. com.google.cloud:libraries-bom-protobuf3 includes the same client libraries and library versions as libraries-bom.

Maven

Import the BOM in the dependencyManagement section of your pom.xml file. Include specific artifacts you depend on in the dependencies section, but don't specify the artifacts' versions in the dependencies section. The example below demonstrates how you would import the BOM and include the google-cloud-storage artifact.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.57.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage</artifactId>
  </dependency>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-storage-control</artifactId>
  </dependency>
</dependencies>

In this example, because the BOM manages library versions, the version of google-cloud-storage is omitted.

Gradle

BOMs are supported by default in Gradle 5.x or later. Add a platform dependency on com.google.cloud:libraries-bom and remove the version from the dependency declarations in the artifact's build.gradle file.

implementation platform('com.google.cloud:libraries-bom:26.57.0')

implementation 'com.google.cloud:google-cloud-storage'

The platform and enforcedPlatform keywords supply dependency versions declared in a BOM. The enforcedPlatform keyword enforces the dependency versions declared in the BOM and thus overrides what you specified. For more details of the platform and enforcedPlatform keywords Gradle 5.x or higher, see Gradle: Importing Maven BOMs.

If you're using Gradle 4.6 or later, add enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle file. For details, see Gradle 4.6 Release Notes: BOM import. Versions of Gradle earlier than 4.6 don't support BOMs.

SBT

SBT doesn't support BOMs. You can find recommended versions of libraries from a particular BOM version on the dashboard and set the versions manually.

Bazel

Bazel doesn't support BOMs. You can find recommended versions of libraries from a particular BOM version on the dashboard and set the versions manually.

Guava Versions -jre or -android

Since the release of version 21.0.0, the Libraries BOM includes Guava's -jre version (which supports Java 8+). The section below is not applicable for Java 8 users.

Google's Guava release contains two versions of artifacts: "-jre" and "-android" versions. The one with "-jre" (such as com.google.guava:guava:31.1-jre) is for Java 8 and supports lambda functions and streams. The other version with the "-android" suffix (such as com.google.guava:guava:31.1-android) is for Java 7 and Android development.

The Google Cloud Libraries BOM contains Guava with the "-android" version to make sure that the BOM works in Java 7. However, this means the version of Guava in the BOM doesn't have some methods that are intended for Java 8 lambda functions, such as ImmutableList.toImmutableList().

If your project requires Java 8 or later and uses Guava classes such as com.google.common.collect.Streams, you should add a dependency on a JRE version of Guava.

In Maven:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>31.1-jre</version>  <!-- "-jre" for Java 8 or higher -->
      </dependency>
    </dependencies>
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>libraries-bom</artifactId>
        ...
  </dependencyManagement>

In Gradle:

dependencies {
  constraints {
    implementation 'com.google.guava:guava:31.1-jre' // "-jre" for Java 8 or higher
  }
  implementation platform('com.google.cloud:libraries-bom:26.12.0')
  ...
}

The previous sample doesn't work if you use enforcedPlatform because enforcedPlatform takes precedence over constraints. If you want to use enforcedPlatform with the Guava version, you can configure ResolutionStrategy.

Troubleshooting

When using the Cloud Client Libraries in your applications, you might encounter exceptions and runtime errors. This guide provides suggestions to help you debug and locate the root causes.

Client Library Debug Logging

Cloud Client Libraries comes with opt-in Debug Logging that can help you troubleshoot your application's integration with the API. When logging is activated, key events such as requests and responses, along with data payloads and metadata, such as headers, are logged to the standard error stream.

WARNING: Client Library Debug Logging includes your data payloads in plaintext, which could include sensitive data such as PII for yourself or your customers, private keys, or other security data that could be compromised if leaked. Always practice good data hygiene with your application logs, and follow the principle of least access. Google also recommends that client library debug logging be enabled only temporarily during active debugging, and not used permanently in production.

Prerequisite

Our libraries support debug logging using the SLF4J interface.

Client libraries and Libraries BOM does not include slf4j-api dependency. You will need to set up logging dependencies including SLF4J and corresponding logging implementations and configurations before turning on client library debug logging.

NOTE: You need to have SLF4J and corresponding logging providers, e.g., logback, log4j2, etc., in your classpath in order to use the client library debug logging feature; otherwise, no debug logging even if you enable it using environment variable.

Enable Logging with an environment variable

Debug logging is turned off by default. Debug logging is not turned on unless explicitly even if the prerequisites are met.

You can enable client library debug logging by setting the environment variable GOOGLE_SDK_JAVA_LOGGING to true, case insensitive. If unset or any other value, then client library debug logging is disabled.