1Google API Extensions for Java 2============================== 3 4- [API Documentation](https://cloud.google.com/java/docs/reference/gax/latest/overview.html) 5 6Google API Extensions for Java (GAX Java) is a library which aids in the 7development of client libraries for server APIs, based on [GRPC](http://grpc.io) 8and Google API conventions. 9 10Application code will rarely need to use most of the classes within this 11library directly, but code generated automatically from the API definition 12files can use services such as paged list iteration, request batching, and 13polling of long-running operations to provide a more convenient and idiomatic 14API surface to callers. 15 16Currently, this library shouldn't be used independently of google-cloud-java, otherwise there is 17a high risk of diamond dependency problems, because google-cloud-java uses beta features from this 18library which can change in breaking ways between versions. See [VERSIONING](#versioning) for 19more information. 20 21> For new and existing Developers/ Contributors: 22> 23> In December 2022, gax-java's build tool has been migrated from gradle to maven. 24> Gradle related files are no longer being maintained and will be eventually removed. 25> 26> The artifact coordinates in Maven Central (`{{ group_id }}:{{ artifact_id }}`) remain the same. 27 28Quickstart 29---------- 30 31[//]: # ({x-version-update-start:gax:released}) 32If you are using Maven, add this to your pom.xml file 33```xml 34<dependency> 35 <groupId>com.google.api</groupId> 36 <artifactId>gax</artifactId> 37 <version>2.23.0</version> 38</dependency> 39<dependency> 40 <groupId>com.google.api</groupId> 41 <artifactId>gax-grpc</artifactId> 42 <version>2.23.0</version> 43</dependency> 44``` 45 46If you are using Gradle, add this to your dependencies 47 48```Groovy 49compile 'com.google.api:gax:2.23.0', 50 'com.google.api:gax-grpc:2.23.0' 51``` 52 53If you are using SBT, add this to your dependencies 54 55```Scala 56libraryDependencies += "com.google.api" % "gax" % "2.23.0" 57libraryDependencies += "com.google.api" % "gax-grpc" % "2.23.0" 58``` 59[//]: # ({x-version-update-end}) 60 61To find the latest version, see https://search.maven.org/artifact/com.google.api/gax. 62 63Java Versions 64------------- 65 66Java 8 or above is required for using this library. 67 68To build this project, JDK 11 or above is required. 69The build produces Java bytecode targeted for Java 8. 70 71The project uses Gradle to build while it also provides Bazel build. 72 73If you build this project in Bazel, it requires Bazel 4 and basic UNIX commands 74(e.g., `cat`). 75 76Contributing 77------------ 78 79Contributions to this library are always welcome and highly encouraged. 80 81See the [CONTRIBUTING] documentation for more information on how to get started. 82 83Versioning 84---------- 85 86This library follows [Semantic Versioning](http://semver.org/), but with some 87additional qualifications: 88 891. Components marked with `@BetaApi` are considered to be "0.x" features inside 90 a "1.x" library. This means they can change between minor and patch releases 91 in incompatible ways. These features should not be used by any library "B" 92 that itself has consumers, unless the components of library B that use 93 `@BetaApi` features are also marked with `@BetaApi`. Features marked as 94 `@BetaApi` are on a path to eventually become "1.x" features with the marker 95 removed. 96 97 **Special exception for google-cloud-java**: google-cloud-java is 98 allowed to depend on `@BetaApi` features without declaring the consuming 99 code `@BetaApi`, because gax-java and google-cloud-java move in step 100 with each other. For this reason, gax-java should not be used 101 independently of google-cloud-java. 102 1031. Components marked with `@InternalApi` are technically public, but are only 104 public for technical reasons, because of the limitations of Java's access 105 modifiers. For the purposes of semver, they should be considered private. 106 1071. Components marked with `@InternalExtensionOnly` are stable for usage, but 108 not for extension. Thus, methods will not be removed from interfaces marked 109 with this annotation, but methods can be added, thus breaking any 110 code implementing the interface. See the javadocs for more details on other 111 consequences of this annotation. 112 113### Submodule notes 114 115- `gax` is stable (>= 1.0.0), so anything not marked `@BetaApi`, `@InternalApi`, 116or `@InternalExtensionOnly` won't break between minor releases. Anything marked 117`@InternalExtensionOnly` can only break extensions between minor releases. 118- `gax-grpc` is stable (>= 1.0.0), so anything not marked `@BetaApi`, `@InternalApi`, 119or `@InternalExtensionOnly` won't break between minor releases. Anything marked 120`@InternalExtensionOnly` can only break extensions between minor releases. 121- `gax-httpjson` is beta (0.x.y), so anything may change at any time and the public 122API should not be considered stable. There is no difference whether a class is 123marked `@BetaApi` or not; that annotation is only present as a reminder. There is 124also no difference whether a class is marked `@InternalExtensionOnly` or not; that 125only implies that the annotation will still be present in 1.0.0. 126 127### Feature notes 128 129- **Long Running Operations** - This feature is not yet considered stable. 130- **Streaming** - Streaming features are not yet considered stable. 131- **Batching** - Batching features are not yet considered stable. 132- **Generated Code Support** - Features to support generated code is not yet 133 considered stable. 134- **Testing** - There are no plans to consider any code in the testlib jar to be stable. 135 136Repository Structure 137-------------------- 138 139This repository contains the following java packages. 140 141### gax 142 143Transport-independent part of GAX for Java. 144The term "transport" in this context usually means the distinction between gRPC or REST. 145Basically all logic, which does not depend explicitly on gRPC or REST goes to this package. 146The examples of such transport-agnostic logic, which is in this package: 147retries, pagination, batching, utilities and core logic. 148 149- `com.google.api.gax.batching` - Contains general-purpose batching logic. 150- `com.google.api.gax.core` - Contains core interfaces and classes that are not 151 specific to grpc and could be used in other contexts. 152- `com.google.api.gax.longrunning` - Contains classes related to long running 153 operations. 154- `com.google.api.gax.paging` - Contains classes related to list calls that return 155 results in pages. 156- `com.google.api.gax.retrying` - Contains classes related to retrying API calls. 157- `com.google.api.gax.rpc` - Contains classes related to making RPC calls. 158 159### gax-grpc 160 161This depends on gax module from the above, and has all the gRPC-specific logic, 162which could not go to the gax module because of this dependency on gRPC. 163Basically it has gRPC-specific implementations of the interfaces and abstract classes defined in gax. 164 165- `com.google.api.gax.grpc` - Contains classes that provide functionality on top 166 of gRPC calls. 167- `com.google.longrunning` - Contains the mix-in client for long-running operations 168 which is implemented by a number of Google APIs. 169 170### gax-httpjson 171 172This module is very similar to gax-grpc, but depends on REST-specific implementation. 173It enables the generated libraries to communicate with the backend services based on HTTP 1741.1 protocol. 175 176- `com.google.api.gax.httpjson` - Contains classes that provide functionality on 177 top of http/json calls. 178 179License 180------- 181 182BSD - See [LICENSE] for more information. 183 184[CONTRIBUTING]:https://github.com/googleapis/gax-java/blob/main/CONTRIBUTING.md 185[LICENSE]: https://github.com/googleapis/gax-java/blob/main/LICENSE 186 187