• Documentation

Google API Extensions for Java (GAX Java) is a library which aids in thedevelopment of client libraries for server APIs, based onGRPCand Google API conventions.

Application code will rarely need to use most of the classes within thislibrary directly, but code generated automatically from the API definitionfiles can use services such as paged list iteration, request batching, andpolling of long-running operations to provide a more convenient and idiomaticAPI surface to callers.

Currently, this library shouldn't be used independently from google-cloud-java, otherwise there isa high risk of diamond dependency problems, because google-cloud-java uses beta features from thislibrary which can change in breaking ways between versions. SeeVERSIONING formore information.

Quickstart

If you are using Maven, add this to your pom.xml file

<dependency>  <groupId>com.google.api</groupId>  <artifactId>gax</artifactId>  <version>2.8.1</version></dependency><dependency>  <groupId>com.google.api</groupId>  <artifactId>gax-grpc</artifactId>  <version>2.8.1</version></dependency>

If you are using Gradle, add this to your dependencies

compile 'com.google.api:gax:2.8.1',  'com.google.api:gax-grpc:2.8.1'

If you are using SBT, add this to your dependencies

libraryDependencies += "com.google.api" % "gax" % "2.8.1"libraryDependencies += "com.google.api" % "gax-grpc" % "2.8.1"

Java Versions

Java 7 or above is required for using this library.

Contributing

Contributions to this library are always welcome and highly encouraged.

See theCONTRIBUTING documentation for more information on how to get started.

Versioning

This library followsSemantic Versioning, but with someadditional qualifications:

1. Components marked with@BetaApi are considered to be "0.x" features insidea "1.x" library. This means they can change between minor and patch releasesin incompatible ways. These features should not be used by any library "B"that itself has consumers, unless the components of library B that use@BetaApi features are also marked with@BetaApi. Features marked as@BetaApi are on a path to eventually become "1.x" features with the markerremoved.

   Special exception for google-cloud-java: google-cloud-java isallowed to depend on@BetaApi features without declaring the consumingcode@BetaApi, because gax-java and google-cloud-java move in stepwith each other. For this reason, gax-java should not be usedindependently of google-cloud-java.

2. Components marked with@InternalApi are technically public, but are onlypublic for technical reasons, because of the limitations of Java's accessmodifiers. For the purposes of semver, they should be considered private.

3. Components marked with@InternalExtensionOnly are stable for usage, butnot for extension. Thus, methods will not be removed from interfaces markedwith this annotation, but methods can be added, thus breaking anycode implementing the interface. See the javadocs for more details on otherconsequences of this annotation.

Submodule notes

• gax is stable (>= 1.0.0), so anything not marked@BetaApi,@InternalApi,or@InternalExtensionOnly won't break between minor releases. Anything marked@InternalExtensionOnly can only break extensions between minor releases.
• gax-grpc is stable (>= 1.0.0), so anything not marked@BetaApi,@InternalApi,or@InternalExtensionOnly won't break between minor releases. Anything marked@InternalExtensionOnly can only break extensions between minor releases.
• gax-httpjson is beta (0.x.y), so anything may change at any time and the publicAPI should not be considered stable. There is no difference whether a class ismarked@BetaApi or not; that annotation is only present as a reminder. There isalso no difference whether a class is marked@InternalExtensionOnly or not; thatonly implies that the annotation will still be present in 1.0.0.

Feature notes

• Long Running Operations - This feature is not yet considered stable.
• Streaming - Streaming features are not yet considered stable.
• Batching - Batching features are not yet considered stable.
• Generated Code Support - Features to support generated code is not yetconsidered stable.
• Testing - There are no plans to consider any code in the testlib jar to be stable.

Repository Structure

This repository contains the following java packages.

gax

• com.google.api.gax.batching - Contains general-purpose batching logic.
• com.google.api.gax.core - Contains core interfaces and classes that are notspecific to grpc and could be used in other contexts.
• com.google.api.gax.longrunning - Contains classes related to long runningoperations.
• com.google.api.gax.paging - Contains classes related to list calls that returnresults in pages.
• com.google.api.gax.retrying - Contains classes related to retrying API calls.
• com.google.api.gax.rpc - Contains classes related to making RPC calls.

gax-grpc

• com.google.api.gax.grpc - Contains classes that provide functionality on topof gRPC calls.
• com.google.longrunning - Contains the mix-in client for long-running operationswhich is implemented by a number of Google APIs.

gax-httpjson

• com.google.api.gax.httpjson - Contains classes that provide functionality ontop of http/json calls.

License

BSD - SeeLICENSE for more information.