1# Google Compute Engine Client for Java 2 3Java idiomatic client for [Compute Engine][product-docs]. 4 5[![Maven][maven-version-image]][maven-version-link] 6![Stability][stability-image] 7 8- [Product Documentation][product-docs] 9- [Client Library Documentation][javadocs] 10 11 12## Quickstart 13 14 15If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file: 16 17```xml 18<dependencyManagement> 19 <dependencies> 20 <dependency> 21 <groupId>com.google.cloud</groupId> 22 <artifactId>libraries-bom</artifactId> 23 <version>26.12.0</version> 24 <type>pom</type> 25 <scope>import</scope> 26 </dependency> 27 </dependencies> 28</dependencyManagement> 29 30<dependencies> 31 <dependency> 32 <groupId>com.google.cloud</groupId> 33 <artifactId>google-cloud-compute</artifactId> 34 </dependency> 35``` 36 37If you are using Maven without the BOM, add this to your dependencies: 38 39<!-- {x-version-update-start:google-cloud-compute:released} --> 40 41```xml 42<dependency> 43 <groupId>com.google.cloud</groupId> 44 <artifactId>google-cloud-compute</artifactId> 45 <version>1.27.0</version> 46</dependency> 47``` 48 49If you are using Gradle without BOM, add this to your dependencies: 50 51```Groovy 52implementation 'com.google.cloud:google-cloud-compute:1.27.0' 53``` 54 55If you are using SBT, add this to your dependencies: 56 57```Scala 58libraryDependencies += "com.google.cloud" % "google-cloud-compute" % "1.27.0" 59``` 60<!-- {x-version-update-end} --> 61 62## Authentication 63 64See the [Authentication][authentication] section in the base directory's README. 65 66## Authorization 67 68The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired Compute Engine APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the Compute Engine API calls. 69 70## Getting Started 71 72### Prerequisites 73 74You will need a [Google Cloud Platform Console][developer-console] project with the Compute Engine [API enabled][enable-api]. 75You will need to [enable billing][enable-billing] to use Google Compute Engine. 76[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by 77[installing the Google Cloud Command Line Interface][cloud-cli] and running the following commands in command line: 78`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`. 79 80### Installation and setup 81 82You'll need to obtain the `google-cloud-compute` library. See the [Quickstart](#quickstart) section 83to add `google-cloud-compute` as a dependency in your code. 84 85## About Compute Engine 86 87 88[Compute Engine][product-docs] delivers virtual machines running in Google's innovative data centers and worldwide fiber network. Compute Engine's tooling and workflow support enable scaling from single instances to global, load-balanced cloud computing. Compute Engine's VMs boot quickly, come with persistent disk storage, deliver consistent performance and are available in many configurations. 89 90 91 92See the [Compute Engine client library docs][javadocs] to learn how to 93use this Compute Engine Client Library. 94 95 96### Compute alpha to beta migration 97 98Java compute library is GA from version 1.7.0 and backwards incompatible with 0.x.x. Also it is incompatible with 1.5.x-alpha and prior in a following way: 99- Everything except polling methods which used to return `Operation` now returns `OperationFuture`. 100- Library automatically polls Operation status. 101- `Operation op = client.myMethod(args)` should be replaced with `OperationFuture<Operation, Operation> opFuture = client.myMethodAsync(args);` 102- Polling is now done automatically, manual polling is no longer required. Calling `opFuture.get()` will wait for automatic polling to complete. It will return the result of the long running operation once the operation is completed on the server side or throw an exception if an error occurs during polling. 103- To check for intermediate status on the future use either `opFuture.peekMetadata()` (non-blocking) or `opFuture.getMetadata()` (blocking) 104- If you wish to stop automatic polling call `opFuture.cancel()` - it will cancel the future on the client side but it will not affect the execution of the operation on the server side in any way (server will keep working on the operation). 105- The calls still may be done without relying on automatic polling and/or OperationFuture. To do so, use `client.myMethodCallable(MyMethodRequest).call()` semantics instead. Note this semantics does not have flattened method declarations and the request message must be instantiated explicitly by the users code. 106 107### Example 108The following example creates a GCE address, then lists all the available addresses in the region and in the whole project and eventually deletes the newly created address. 109 110```java 111import com.google.cloud.compute.v1.Address; 112import com.google.cloud.compute.v1.AddressesClient; 113import com.google.cloud.compute.v1.AddressesScopedList; 114import com.google.cloud.compute.v1.Operation; 115import com.google.protobuf.util.JsonFormat; 116import java.io.IOException; 117import java.util.Map; 118 119public class ComputeExample { 120 121 public static void main(String[] args) throws IOException, InterruptedException { 122 final String project = "PROJECT_NAME"; 123 final String region = "REGION"; 124 final String address = "test-address-21"; 125 126 AddressesClient addressesClient = AddressesClient.create(); 127 128 // AddressClient#insert() 129 System.out.println("\n===============\nAddressClient#insert()\n==============="); 130 OperationFuture<Operation,Operation> insertResponse = 131 addressesClient.insertAsync(project, region, Address.newBuilder().setName(address).build()); 132 Operation insertResponseOperation = insertResponse.get(); 133 System.out.println(JsonFormat.printer().print(insertResponse) + "\n"); 134 135 // AddressClient#list() 136 System.out.println("\n===============\nAddressClient#list()\n==============="); 137 for (Address addr : addressesClient.list(project, region).iterateAll()) { 138 System.out.println(JsonFormat.printer().print(addr)); 139 } 140 141 // AddressClient#aggregatedList() 142 System.out.println("\n===============\nAddressClient#aggregatedList()\n==============="); 143 for (Map.Entry<String, AddressesScopedList> addr : 144 addressesClient.aggregatedList(project).iterateAll()) { 145 System.out.println("KEY: " + addr.getKey()); 146 System.out.println(JsonFormat.printer().print(addr.getValue())); 147 } 148 149 // AddressClient#delete() 150 System.out.println("\n===============\nAddressClient#delete()\n==============="); 151 OperationFuture<Operation,Operation> deleteResponse = addressesClient.deleteAsync(project, region, address); 152 Operation deleteResponseOperation = deleteResponse.get(); 153 System.out.println(JsonFormat.printer().print(deleteResponse) + "\n"); 154 } 155} 156 157``` 158 159 160 161 162 163## Troubleshooting 164 165To get help, follow the instructions in the [shared Troubleshooting document][troubleshooting]. 166 167## Transport 168 169Compute Engine uses HTTP/JSON for the transport layer. 170 171## Supported Java Versions 172 173Java 8 or above is required for using this client. 174 175Google's Java client libraries, 176[Google Cloud Client Libraries][cloudlibs] 177and 178[Google Cloud API Libraries][apilibs], 179follow the 180[Oracle Java SE support roadmap][oracle] 181(see the Oracle Java SE Product Releases section). 182 183### For new development 184 185In general, new feature development occurs with support for the lowest Java 186LTS version covered by Oracle's Premier Support (which typically lasts 5 years 187from initial General Availability). If the minimum required JVM for a given 188library is changed, it is accompanied by a [semver][semver] major release. 189 190Java 11 and (in September 2021) Java 17 are the best choices for new 191development. 192 193### Keeping production systems current 194 195Google tests its client libraries with all current LTS versions covered by 196Oracle's Extended Support (which typically lasts 8 years from initial 197General Availability). 198 199#### Legacy support 200 201Google's client libraries support legacy versions of Java runtimes with long 202term stable libraries that don't receive feature updates on a best efforts basis 203as it may not be possible to backport all patches. 204 205Google provides updates on a best efforts basis to apps that continue to use 206Java 7, though apps might need to upgrade to current versions of the library 207that supports their JVM. 208 209#### Where to find specific information 210 211The latest versions and the supported Java versions are identified on 212the individual GitHub repository `github.com/GoogleAPIs/java-SERVICENAME` 213and on [google-cloud-java][g-c-j]. 214 215## Versioning 216 217 218This library follows [Semantic Versioning](http://semver.org/). 219 220 221 222## Contributing 223 224 225Contributions to this library are always welcome and highly encouraged. 226 227See [CONTRIBUTING][contributing] for more information how to get started. 228 229Please note that this project is released with a Contributor Code of Conduct. By participating in 230this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more 231information. 232 233 234## License 235 236Apache 2.0 - See [LICENSE][license] for more information. 237 238## CI Status 239 240Java Version | Status 241------------ | ------ 242Java 8 | [![Kokoro CI][kokoro-badge-image-2]][kokoro-badge-link-2] 243Java 8 OSX | [![Kokoro CI][kokoro-badge-image-3]][kokoro-badge-link-3] 244Java 8 Windows | [![Kokoro CI][kokoro-badge-image-4]][kokoro-badge-link-4] 245Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5] 246 247Java is a registered trademark of Oracle and/or its affiliates. 248 249[product-docs]: https://cloud.google.com/compute/ 250[javadocs]: https://cloud.google.com/java/docs/reference/google-cloud-compute/latest/overview 251[kokoro-badge-image-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.svg 252[kokoro-badge-link-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.html 253[kokoro-badge-image-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.svg 254[kokoro-badge-link-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.html 255[kokoro-badge-image-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.svg 256[kokoro-badge-link-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.html 257[kokoro-badge-image-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.svg 258[kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.html 259[kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.svg 260[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.html 261[stability-image]: https://img.shields.io/badge/stability-stable-green 262[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-compute.svg 263[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-compute/1.24.0 264[authentication]: https://github.com/googleapis/google-cloud-java#authentication 265[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes 266[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles 267[iam-policy]: https://cloud.google.com/iam/docs/overview#cloud-iam-policy 268[developer-console]: https://console.developers.google.com/ 269[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects 270[cloud-cli]: https://cloud.google.com/cli 271[troubleshooting]: https://github.com/googleapis/google-cloud-java/blob/main/TROUBLESHOOTING.md 272[contributing]: https://github.com/googleapis/google-cloud-java/blob/main/CONTRIBUTING.md 273[code-of-conduct]: https://github.com/googleapis/google-cloud-java/blob/main/CODE_OF_CONDUCT.md#contributor-code-of-conduct 274[license]: https://github.com/googleapis/google-cloud-java/blob/main/LICENSE 275[enable-billing]: https://cloud.google.com/apis/docs/getting-started#enabling_billing 276[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=compute.googleapis.com 277[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM 278[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png 279 280[semver]: https://semver.org/ 281[cloudlibs]: https://cloud.google.com/apis/docs/client-libraries-explained 282[apilibs]: https://cloud.google.com/apis/docs/client-libraries-explained#google_api_client_libraries 283[oracle]: https://www.oracle.com/java/technologies/java-se-support-roadmap.html 284[g-c-j]: http://github.com/googleapis/google-cloud-java 285
