README.md
1# Google Storage Transfer Service Client for Java
2
3Java idiomatic client for [Storage Transfer Service][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-storage-transfer</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-storage-transfer:released} -->
40
41```xml
42<dependency>
43 <groupId>com.google.cloud</groupId>
44 <artifactId>google-cloud-storage-transfer</artifactId>
45 <version>1.17.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-storage-transfer:1.17.0'
53```
54
55If you are using SBT, add this to your dependencies:
56
57```Scala
58libraryDependencies += "com.google.cloud" % "google-cloud-storage-transfer" % "1.17.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 Storage Transfer Service APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the Storage Transfer Service API calls.
69
70## Getting Started
71
72### Prerequisites
73
74You will need a [Google Cloud Platform Console][developer-console] project with the Storage Transfer Service [API enabled][enable-api].
75You will need to [enable billing][enable-billing] to use Google Storage Transfer Service.
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-storage-transfer` library. See the [Quickstart](#quickstart) section
83to add `google-cloud-storage-transfer` as a dependency in your code.
84
85## About Storage Transfer Service
86
87
88[Storage Transfer Service][product-docs] Secure, low-cost services for transferring data from cloud or on-premises sources.
89
90See the [Storage Transfer Service client library docs][javadocs] to learn how to
91use this Storage Transfer Service Client Library.
92
93
94
95
96
97
98## Troubleshooting
99
100To get help, follow the instructions in the [shared Troubleshooting document][troubleshooting].
101
102## Transport
103
104Storage Transfer Service uses gRPC for the transport layer.
105
106## Supported Java Versions
107
108Java 8 or above is required for using this client.
109
110Google's Java client libraries,
111[Google Cloud Client Libraries][cloudlibs]
112and
113[Google Cloud API Libraries][apilibs],
114follow the
115[Oracle Java SE support roadmap][oracle]
116(see the Oracle Java SE Product Releases section).
117
118### For new development
119
120In general, new feature development occurs with support for the lowest Java
121LTS version covered by Oracle's Premier Support (which typically lasts 5 years
122from initial General Availability). If the minimum required JVM for a given
123library is changed, it is accompanied by a [semver][semver] major release.
124
125Java 11 and (in September 2021) Java 17 are the best choices for new
126development.
127
128### Keeping production systems current
129
130Google tests its client libraries with all current LTS versions covered by
131Oracle's Extended Support (which typically lasts 8 years from initial
132General Availability).
133
134#### Legacy support
135
136Google's client libraries support legacy versions of Java runtimes with long
137term stable libraries that don't receive feature updates on a best efforts basis
138as it may not be possible to backport all patches.
139
140Google provides updates on a best efforts basis to apps that continue to use
141Java 7, though apps might need to upgrade to current versions of the library
142that supports their JVM.
143
144#### Where to find specific information
145
146The latest versions and the supported Java versions are identified on
147the individual GitHub repository `github.com/GoogleAPIs/java-SERVICENAME`
148and on [google-cloud-java][g-c-j].
149
150## Versioning
151
152
153This library follows [Semantic Versioning](http://semver.org/).
154
155
156
157## Contributing
158
159
160Contributions to this library are always welcome and highly encouraged.
161
162See [CONTRIBUTING][contributing] for more information how to get started.
163
164Please note that this project is released with a Contributor Code of Conduct. By participating in
165this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more
166information.
167
168
169## License
170
171Apache 2.0 - See [LICENSE][license] for more information.
172
173## CI Status
174
175Java Version | Status
176------------ | ------
177Java 8 | [![Kokoro CI][kokoro-badge-image-2]][kokoro-badge-link-2]
178Java 8 OSX | [![Kokoro CI][kokoro-badge-image-3]][kokoro-badge-link-3]
179Java 8 Windows | [![Kokoro CI][kokoro-badge-image-4]][kokoro-badge-link-4]
180Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5]
181
182Java is a registered trademark of Oracle and/or its affiliates.
183
184[product-docs]: https://cloud.google.com/storage-transfer-service
185[javadocs]: https://cloud.google.com/java/docs/reference/google-cloud-storage-transfer/latest/overview
186[kokoro-badge-image-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.svg
187[kokoro-badge-link-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java7.html
188[kokoro-badge-image-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.svg
189[kokoro-badge-link-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8.html
190[kokoro-badge-image-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.svg
191[kokoro-badge-link-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-osx.html
192[kokoro-badge-image-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.svg
193[kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java8-win.html
194[kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.svg
195[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/google-cloud-java/java11.html
196[stability-image]: https://img.shields.io/badge/stability-stable-green
197[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-storage-transfer.svg
198[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-storage-transfer/1.14.0
199[authentication]: https://github.com/googleapis/google-cloud-java#authentication
200[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
201[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles
202[iam-policy]: https://cloud.google.com/iam/docs/overview#cloud-iam-policy
203[developer-console]: https://console.developers.google.com/
204[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects
205[cloud-cli]: https://cloud.google.com/cli
206[troubleshooting]: https://github.com/googleapis/google-cloud-java/blob/main/TROUBLESHOOTING.md
207[contributing]: https://github.com/googleapis/google-cloud-java/blob/main/CONTRIBUTING.md
208[code-of-conduct]: https://github.com/googleapis/google-cloud-java/blob/main/CODE_OF_CONDUCT.md#contributor-code-of-conduct
209[license]: https://github.com/googleapis/google-cloud-java/blob/main/LICENSE
210[enable-billing]: https://cloud.google.com/apis/docs/getting-started#enabling_billing
211[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=storagetransfer.googleapis.com
212[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM
213[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
214
215[semver]: https://semver.org/
216[cloudlibs]: https://cloud.google.com/apis/docs/client-libraries-explained
217[apilibs]: https://cloud.google.com/apis/docs/client-libraries-explained#google_api_client_libraries
218[oracle]: https://www.oracle.com/java/technologies/java-se-support-roadmap.html
219[g-c-j]: http://github.com/googleapis/google-cloud-java
220
