Skip to content

The Google Cloud Platform Libraries BOM

Jump to bottom
Tomo Suzuki edited this page Jul 23, 2021 · 99 revisions

Google publishes over two hundred open source Java libraries that make it easier to use services in Google Cloud Platform (GCP). Additionally Google maintains several foundation libraries that can be used for very general purposes, which the GCP libraries also depend on. When we publish a version of Google Cloud Platform Libraries BOM, we ensure that the libraries in the BOM do not have dependency conflicts, that would manifest as NoSuchMethodError or NoClassDefFoundError. By using the Libraries BOM, you can ensure your projects always have compatible versions of these several hundred different artifacts.

These recommendations apply to the components of these libraries:

To ensure that your own project uses compatible versions of these libraries and all their component artifacts, import com.google.cloud:libraries-bom and use that to specify dependency versions. Be sure to remove any versions that had been previously set!

Maven

Import the BOM in the dependencyManagement section of your pom.xml. Include specific artifacts you depend on in the dependencies section but do not specify their version there.

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>libraries-bom</artifactId>
        <version>20.8.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.guava</groupId>
      <artifactId>guava</artifactId>
    </dependency>
  </dependencies>

In this example, since the BOM manages library versions, the version of google-cloud-storage and guava are omitted.

Gradle

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

If you are using Gradle 4.x, add enableFeaturePreview('IMPROVED_POM_SUPPORT') to your settings.gradle.

dependencies {
  api enforcedPlatform('com.google.cloud:libraries-bom:20.8.0')
  api 'com.google.cloud:google-cloud-storage'
  api 'com.google.guava:guava'
}

For more details for Gradle 5.x or higher, refer to Gradle: Importing Maven BOMs.

For Gradle 4 example, refer to Gradle 4.6 Release Notes: BOM import.

SBT

SBT does not currently support BOMs. Until it does, you can find recommended versions of libraries from a particular BOM versions on the dashboard and set those manually.

Bazel

Bazel does not currently support BOMs. Until it does, you can find recommended versions of libraries from a particular BOM versions on the dashboard and set those manually.

Guava Versions "-jre" or "-android"

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

The Google Cloud Platform Libraries BOM contains Guava with the "-android" flavor to ensure that the BOM works in Java 7. However, this means the version of Guava in the BOM does not 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>30.1.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 {
    api 'com.google.guava:guava:30.1.1-jre' // "-jre" for Java 8 or higher
  }
  api platform('com.google.cloud:libraries-bom:20.8.0')
  ...
}

Note that, as enforcedPlatform keyword would supersede the constraints keyword, you cannot use enforcedPlatform if you want to override the Guava flavor.

Intrinsic conflicts

It is possible for GCP open source Java libraries to have conflicts that cannot be resolved by following the recommendations of this document. Such conflicts are called intrinsic conflicts. There is an ongoing effort to remove intrinsic conflicts among GCP open source Java libraries and prevent new ones from occurring. The Cloud Open Source Java Dashboard reports the current results of compatibility checks. As of the time of this writing, some conflicts are still in the process of being fixed, but they should not be encountered by most users who only use the public APIs of the libraries. If you encounter such a conflict, please file an issue against cloud-opensource-java.

Clone this wiki locally