├── .github ├── release-trigger.yml └── release-please.yml ├── SECURITY.md ├── LICENSE ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md └── README.md /.github/release-trigger.yml: -------------------------------------------------------------------------------- 1 | enabled: true 2 | multiScmName: gax-java 3 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | To report a security issue, please use [g.co/vulnz](https://g.co/vulnz). 4 | 5 | The Google Security Team will respond within 5 working days of your report on g.co/vulnz. 6 | 7 | We use g.co/vulnz for our intake, and do coordination and disclosure here using GitHub Security Advisory to privately discuss and fix the issue. 8 | -------------------------------------------------------------------------------- /.github/release-please.yml: -------------------------------------------------------------------------------- 1 | releaseType: java-yoshi 2 | bumpMinorPreMajor: true 3 | handleGHRelease: true 4 | branches: 5 | - releaseType: java-backport 6 | bumpMinorPreMajor: true 7 | handleGHRelease: true 8 | branch: 2.16.x 9 | - releaseType: java-backport 10 | bumpMinorPreMajor: true 11 | handleGHRelease: true 12 | branch: 2.19.x 13 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2016, Google Inc. All rights reserved. 2 | 3 | Redistribution and use in source and binary forms, with or without 4 | modification, are permitted provided that the following conditions are 5 | met: 6 | 7 | * Redistributions of source code must retain the above copyright 8 | notice, this list of conditions and the following disclaimer. 9 | * Redistributions in binary form must reproduce the above 10 | copyright notice, this list of conditions and the following disclaimer 11 | in the documentation and/or other materials provided with the 12 | distribution. 13 | * Neither the name of Google Inc. nor the names of its 14 | contributors may be used to endorse or promote products derived from 15 | this software without specific prior written permission. 16 | 17 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Want to contribute? Great! First, read this page (including the small print at the end). 2 | 3 | ### Before you contribute 4 | Before we can use your code, you must sign the 5 | [Google Individual Contributor License Agreement] 6 | (https://cla.developers.google.com/about/google-individual) 7 | (CLA), which you can do online. The CLA is necessary mainly because you own the 8 | copyright to your changes, even after your contribution becomes part of our 9 | codebase, so we need your permission to use and distribute your code. We also 10 | need to be sure of various other things—for instance that you'll tell us if you 11 | know that your code infringes on other people's patents. You don't have to sign 12 | the CLA until after you've submitted your code for review and a member has 13 | approved it, but you must do it before we can put your code into our codebase. 14 | Before you start working on a larger contribution, you should get in touch with 15 | us first through the issue tracker with your idea so that we can help out and 16 | possibly guide you. Coordinating up front makes it much easier to avoid 17 | frustration later on. 18 | 19 | ### Code reviews 20 | All submissions, including submissions by project members, require review. We 21 | use Github pull requests for this purpose. 22 | 23 | ### Building 24 | To build GAX: 25 | 26 | ```sh 27 | mvn clean install 28 | ``` 29 | 30 | ### The small print 31 | Contributions made by corporations are covered by a different agreement than 32 | the one above, the 33 | [Software Grant and Corporate Contributor License Agreement] 34 | (https://cla.developers.google.com/about/google-corporate). 35 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Code of Conduct 2 | 3 | As contributors and maintainers of this project, 4 | and in the interest of fostering an open and welcoming community, 5 | we pledge to respect all people who contribute through reporting issues, 6 | posting feature requests, updating documentation, 7 | submitting pull requests or patches, and other activities. 8 | 9 | We are committed to making participation in this project 10 | a harassment-free experience for everyone, 11 | regardless of level of experience, gender, gender identity and expression, 12 | sexual orientation, disability, personal appearance, 13 | body size, race, ethnicity, age, religion, or nationality. 14 | 15 | Examples of unacceptable behavior by participants include: 16 | 17 | * The use of sexualized language or imagery 18 | * Personal attacks 19 | * Trolling or insulting/derogatory comments 20 | * Public or private harassment 21 | * Publishing other's private information, 22 | such as physical or electronic 23 | addresses, without explicit permission 24 | * Other unethical or unprofessional conduct. 25 | 26 | Project maintainers have the right and responsibility to remove, edit, or reject 27 | comments, commits, code, wiki edits, issues, and other contributions 28 | that are not aligned to this Code of Conduct. 29 | By adopting this Code of Conduct, 30 | project maintainers commit themselves to fairly and consistently 31 | applying these principles to every aspect of managing this project. 32 | Project maintainers who do not follow or enforce the Code of Conduct 33 | may be permanently removed from the project team. 34 | 35 | This code of conduct applies both within project spaces and in public spaces 36 | when an individual is representing the project or its community. 37 | 38 | Instances of abusive, harassing, or otherwise unacceptable behavior 39 | may be reported by opening an issue 40 | or contacting one or more of the project maintainers. 41 | 42 | This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, 43 | available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/) 44 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Google API Extensions for Java 2 | ============================== 3 | 4 | [![Build Status](https://travis-ci.org/googleapis/gax-java.svg?branch=main)](https://travis-ci.org/googleapis/gax-java) 5 | 6 | 🚌 In January 2023, this library has moved to [gapic-generator-java/gax-java](https://github.com/googleapis/gapic-generator-java/tree/main/gax-java). This repository will be archived in the future. Future releases will appear in the new repository (https://github.com/googleapis/gapic-generator-java/releases). 7 | The Maven artifact coordinates (com.google.api:gax) remain the same. 8 | 9 | - [Documentation](https://googleapis.dev/java/gax/latest/) 10 | 11 | Google API Extensions for Java (GAX Java) is a library which aids in the 12 | development of client libraries for server APIs, based on [GRPC](http://grpc.io) 13 | and Google API conventions. 14 | 15 | Application code will rarely need to use most of the classes within this 16 | library directly, but code generated automatically from the API definition 17 | files can use services such as paged list iteration, request batching, and 18 | polling of long-running operations to provide a more convenient and idiomatic 19 | API surface to callers. 20 | 21 | Currently, this library shouldn't be used independently from google-cloud-java, otherwise there is 22 | a high risk of diamond dependency problems, because google-cloud-java uses beta features from this 23 | library which can change in breaking ways between versions. See [VERSIONING](#versioning) for 24 | more information. 25 | 26 | > For new and existing Developers/ Contributors: 27 | > 28 | > In December 2022, gax-java's build tool has been migrated from gradle to maven. 29 | > Gradle related files are no longer being maintained and will be eventually removed. 30 | > 31 | > The artifact coordinates in Maven Central (`{{ group_id }}:{{ artifact_id }}`) remain the same. 32 | 33 | Quickstart 34 | ---------- 35 | 36 | [//]: # ({x-version-update-start:gax:released}) 37 | If you are using Maven, add this to your pom.xml file 38 | ```xml 39 | 40 | com.google.api 41 | gax 42 | 2.8.1 43 | 44 | 45 | com.google.api 46 | gax-grpc 47 | 2.8.1 48 | 49 | ``` 50 | 51 | If you are using Gradle, add this to your dependencies 52 | 53 | ```Groovy 54 | compile 'com.google.api:gax:2.8.1', 55 | 'com.google.api:gax-grpc:2.8.1' 56 | ``` 57 | 58 | If you are using SBT, add this to your dependencies 59 | 60 | ```Scala 61 | libraryDependencies += "com.google.api" % "gax" % "2.8.1" 62 | libraryDependencies += "com.google.api" % "gax-grpc" % "2.8.1" 63 | ``` 64 | [//]: # ({x-version-update-end}) 65 | 66 | Java Versions 67 | ------------- 68 | 69 | Java 8 or above is required for using this library. 70 | 71 | To build this project, JDK 11 or above is required. 72 | The build produces Java bytecode targeted for Java 8. 73 | 74 | The project uses Gradle to build while it also provides Bazel build. 75 | 76 | If you build this project in Bazel, it requires Bazel 4 and basic UNIX commands 77 | (e.g., `cat`). 78 | 79 | Contributing 80 | ------------ 81 | 82 | Contributions to this library are always welcome and highly encouraged. 83 | 84 | See the [CONTRIBUTING] documentation for more information on how to get started. 85 | 86 | Versioning 87 | ---------- 88 | 89 | This library follows [Semantic Versioning](http://semver.org/), but with some 90 | additional qualifications: 91 | 92 | 1. Components marked with `@BetaApi` are considered to be "0.x" features inside 93 | a "1.x" library. This means they can change between minor and patch releases 94 | in incompatible ways. These features should not be used by any library "B" 95 | that itself has consumers, unless the components of library B that use 96 | `@BetaApi` features are also marked with `@BetaApi`. Features marked as 97 | `@BetaApi` are on a path to eventually become "1.x" features with the marker 98 | removed. 99 | 100 | **Special exception for google-cloud-java**: google-cloud-java is 101 | allowed to depend on `@BetaApi` features without declaring the consuming 102 | code `@BetaApi`, because gax-java and google-cloud-java move in step 103 | with each other. For this reason, gax-java should not be used 104 | independently of google-cloud-java. 105 | 106 | 1. Components marked with `@InternalApi` are technically public, but are only 107 | public for technical reasons, because of the limitations of Java's access 108 | modifiers. For the purposes of semver, they should be considered private. 109 | 110 | 1. Components marked with `@InternalExtensionOnly` are stable for usage, but 111 | not for extension. Thus, methods will not be removed from interfaces marked 112 | with this annotation, but methods can be added, thus breaking any 113 | code implementing the interface. See the javadocs for more details on other 114 | consequences of this annotation. 115 | 116 | ### Submodule notes 117 | 118 | - `gax` is stable (>= 1.0.0), so anything not marked `@BetaApi`, `@InternalApi`, 119 | or `@InternalExtensionOnly` won't break between minor releases. Anything marked 120 | `@InternalExtensionOnly` can only break extensions between minor releases. 121 | - `gax-grpc` is stable (>= 1.0.0), so anything not marked `@BetaApi`, `@InternalApi`, 122 | or `@InternalExtensionOnly` won't break between minor releases. Anything marked 123 | `@InternalExtensionOnly` can only break extensions between minor releases. 124 | - `gax-httpjson` is beta (0.x.y), so anything may change at any time and the public 125 | API should not be considered stable. There is no difference whether a class is 126 | marked `@BetaApi` or not; that annotation is only present as a reminder. There is 127 | also no difference whether a class is marked `@InternalExtensionOnly` or not; that 128 | only implies that the annotation will still be present in 1.0.0. 129 | 130 | ### Feature notes 131 | 132 | - **Long Running Operations** - This feature is not yet considered stable. 133 | - **Streaming** - Streaming features are not yet considered stable. 134 | - **Batching** - Batching features are not yet considered stable. 135 | - **Generated Code Support** - Features to support generated code is not yet 136 | considered stable. 137 | - **Testing** - There are no plans to consider any code in the testlib jar to be stable. 138 | 139 | Repository Structure 140 | -------------------- 141 | 142 | This repository contains the following java packages. 143 | 144 | ### gax 145 | 146 | - `com.google.api.gax.batching` - Contains general-purpose batching logic. 147 | - `com.google.api.gax.core` - Contains core interfaces and classes that are not 148 | specific to grpc and could be used in other contexts. 149 | - `com.google.api.gax.longrunning` - Contains classes related to long running 150 | operations. 151 | - `com.google.api.gax.paging` - Contains classes related to list calls that return 152 | results in pages. 153 | - `com.google.api.gax.retrying` - Contains classes related to retrying API calls. 154 | - `com.google.api.gax.rpc` - Contains classes related to making RPC calls. 155 | 156 | ### gax-grpc 157 | 158 | - `com.google.api.gax.grpc` - Contains classes that provide functionality on top 159 | of gRPC calls. 160 | - `com.google.longrunning` - Contains the mix-in client for long-running operations 161 | which is implemented by a number of Google APIs. 162 | 163 | ### gax-httpjson 164 | 165 | - `com.google.api.gax.httpjson` - Contains classes that provide functionality on 166 | top of http/json calls. 167 | 168 | License 169 | ------- 170 | 171 | BSD - See [LICENSE] for more information. 172 | 173 | [CONTRIBUTING]:https://github.com/googleapis/gax-java/blob/main/CONTRIBUTING.md 174 | [LICENSE]: https://github.com/googleapis/gax-java/blob/main/LICENSE 175 | 176 | --------------------------------------------------------------------------------