Skip to content

Commit 063d000

Browse files
aozarovaozarov
committed
Merge pull request #576 from aozarov/pubsub-alpha
merge from upstream, fix merge confilict and fix build on non java 8
2 parents c47875a + 7bd63da commit 063d000

File tree

243 files changed

+31932
-2886
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

243 files changed

+31932
-2886
lines changed

‎.travis.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@ before_install:
1010
install: mvn install -DskipTests=true -Dgpg.skip=true
1111
script:
1212
- utilities/verify.sh
13-
branches:
14-
only:
15-
- master
1613
after_success:
1714
- utilities/after_success.sh
1815
env:

‎CONTRIBUTING.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,22 @@ Using maven for build/test
1515
After you cloned the repository use Maven for building and running the tests.
1616
Maven 3.0+ is required.
1717

18+
When downloading the source, we recommend you obtain service account credentials.
19+
These credentials will allow you to run integration tests using `mvn verify` in command line.
20+
Follow step 2 of the [authentication instructions](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) to generate and use JSON service account credentials.
21+
22+
It's also important to test that changes don't break compatibility with App/Compute Engine and when running elsewhere.
23+
To run tests on different platforms, try deploying the apps available on the [gcloud-java-examples](https://github.com/GoogleCloudPlatform/gcloud-java-examples) repository.
24+
End-to-end tests should ensure that gcloud-java works when running on the
25+
26+
* App Engine production environment (see the docs for [uploading your app to production App Engine](https://cloud.google.com/appengine/docs/java/tools/maven#uploading_your_app_to_production_app_engine))
27+
* App Engine development server (see the docs for [testing your app with the development server](https://cloud.google.com/appengine/docs/java/tools/maven#testing_your_app_with_the_development_server))
28+
* Compute Engine (see the [Getting Started Guide](https://cloud.google.com/compute/docs/quickstart), and be sure to [enable the appropriate APIs](https://github.com/GoogleCloudPlatform/gcloud-common/tree/master/authentication#on-google-compute-engine))
29+
* Your desktop (using `mvn exec:java`, for example)
30+
31+
When changes are made to authentication and project ID-related code, authentication and project ID inference should be tested using all relevant methods detailed in the [authentication docs](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) and [project ID docs](https://github.com/GoogleCloudPlatform/gcloud-java#specifying-a-project-id).
32+
33+
Known issue: If you have installed the Google Cloud SDK, be sure to log in (using `gcloud auth login`) before running tests. Though the Datastore tests use a local Datastore emulator that doesn't require authentication, they will not run if you have the Google Cloud SDK installed but aren't authenticated.
1834

1935
Adding Features
2036
---------------

‎README.md‎

Lines changed: 169 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -12,40 +12,154 @@ Java idiomatic client for [Google Cloud Platform][cloud-platform] services.
1212

1313
This client supports the following Google Cloud Platform services:
1414

15+
- [Google Cloud BigQuery] (#google-cloud-bigquery-alpha) (Alpha)
1516
- [Google Cloud Datastore] (#google-cloud-datastore)
17+
- [Google Cloud Resource Manager] (#google-cloud-resource-manager-alpha) (Alpha)
1618
- [Google Cloud Storage] (#google-cloud-storage)
1719

1820
> Note: This client is a work-in-progress, and may occasionally
1921
> make backwards-incompatible changes.
2022
2123
Quickstart
2224
----------
23-
Add this to your pom.xml file
25+
If you are using Maven, add this to your pom.xml file
2426
```xml
2527
<dependency>
2628
<groupId>com.google.gcloud</groupId>
2729
<artifactId>gcloud-java</artifactId>
28-
<version>0.0.10</version>
30+
<version>0.1.3</version>
2931
</dependency>
3032
```
33+
If you are using Gradle, add this to your dependencies
34+
```Groovy
35+
compile 'com.google.gcloud:gcloud-java:0.1.3'
36+
```
37+
If you are using SBT, add this to your dependencies
38+
```Scala
39+
libraryDependencies += "com.google.gcloud" % "gcloud-java" % "0.1.3"
40+
```
3141

3242
Example Applications
3343
--------------------
3444

45+
- [`BigQueryExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/BigQueryExample.java) - A simple command line interface providing some of Cloud BigQuery's functionality
46+
- Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/BigQueryExample.html).
47+
- [`Bookshelf`](https://github.com/GoogleCloudPlatform/getting-started-java/tree/master/bookshelf) - An App Engine app that manages a virtual bookshelf.
48+
- This app uses `gcloud-java` to interface with Cloud Datastore and Cloud Storage. It also uses Cloud SQL, another Google Cloud Platform service.
3549
- [`DatastoreExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/DatastoreExample.java) - A simple command line interface for the Cloud Datastore
3650
- Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html).
51+
- [`ResourceManagerExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/ResourceManagerExample.java) - A simple command line interface providing some of Cloud Resource Manager's functionality
52+
- Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/ResourceManagerExample.html).
53+
- [`SparkDemo`](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/master/managedvms/sparkjava) - An example of using gcloud-java-datastore from within the SparkJava and App Engine Managed VM frameworks.
54+
- Read about how it works on the example's [README page](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/managedvms/sparkjava#how-does-it-work).
3755
- [`StorageExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java) - A simple command line interface providing some of Cloud Storage's functionality
3856
- Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html).
3957

58+
Specifying a Project ID
59+
-----------------------
60+
61+
Most `gcloud-java` libraries require a project ID. There are multiple ways to specify this project ID.
62+
63+
1. When using `gcloud-java` libraries from within Compute/App Engine, there's no need to specify a project ID. It is automatically inferred from the production environment.
64+
2. When using `gcloud-java` elsewhere, you can do one of the following:
65+
* Supply the project ID when building the service options. For example, to use Datastore from a project with ID "PROJECT_ID", you can write:
66+
67+
```java
68+
Datastore datastore = DatastoreOptions.builder().projectId("PROJECT_ID").build().service();
69+
```
70+
* Specify the environment variable `GCLOUD_PROJECT` to be your desired project ID.
71+
* Set the project ID using the [Google Cloud SDK](https://cloud.google.com/sdk/?hl=en). To use the SDK, [download the SDK](https://cloud.google.com/sdk/?hl=en) if you haven't already, and set the project ID from the command line. For example:
72+
73+
```
74+
gcloud config set project PROJECT_ID
75+
```
76+
77+
`gcloud-java` determines the project ID from the following sources in the listed order, stopping once it finds a value:
78+
79+
1. Project ID supplied when building the service options
80+
2. Project ID specified by the environment variable `GCLOUD_PROJECT`
81+
3. App Engine project ID
82+
4. Google Cloud SDK project ID
83+
5. Compute Engine project ID
84+
4085
Authentication
4186
--------------
4287

43-
There are multiple ways to authenticate to use Google Cloud services.
88+
First, ensure that the necessary Google Cloud APIs are enabled for your project. To do this, follow the instructions on the [authentication document](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/authentication/readme.md#authentication) shared by all the gcloud language libraries.
89+
90+
Next, choose a method for authenticating API requests from within your project:
4491

4592
1. When using `gcloud-java` libraries from within Compute/App Engine, no additional authentication steps are necessary.
4693
2. When using `gcloud-java` libraries elsewhere, there are two options:
47-
* [Generate a JSON service account key](https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts). Supply a path to the downloaded JSON credentials file when building the options supplied to datastore/storage constructor.
48-
* If running locally for development/testing, you can use use [Google Cloud SDK](https://cloud.google.com/sdk/?hl=en). To use the SDK authentication, [download the SDK](https://cloud.google.com/sdk/?hl=en) if you haven't already. Then login using the SDK (`gcloud auth login` in command line), and set your current project using `gcloud config set project PROJECT_ID`.
94+
* [Generate a JSON service account key](https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts). After downloading that key, you must do one of the following:
95+
* Define the environment variable GOOGLE_APPLICATION_CREDENTIALS to be the location of the key. For example:
96+
```bash
97+
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json
98+
```
99+
* Supply the JSON credentials file when building the service options. For example, this Storage object has the necessary permissions to interact with your Google Cloud Storage data:
100+
```java
101+
Storage storage = StorageOptions.builder()
102+
.authCredentials(AuthCredentials.createForJson(new FileInputStream("/path/to/my/key.json"))
103+
.build()
104+
.service();
105+
```
106+
* If running locally for development/testing, you can use use Google Cloud SDK. Download the SDK if you haven't already, then login using the SDK (`gcloud auth login` in command line). Be sure to set your project ID as described above.
107+
108+
`gcloud-java` looks for credentials in the following order, stopping once it finds credentials:
109+
110+
1. Credentials supplied when building the service options
111+
2. App Engine credentials
112+
3. Key file pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable
113+
4. Google Cloud SDK credentials
114+
5. Compute Engine credentials
115+
116+
Google Cloud BigQuery (Alpha)
117+
----------------------
118+
119+
- [API Documentation][bigquery-api]
120+
- [Official Documentation][cloud-bigquery-docs]
121+
122+
#### Preview
123+
124+
Here is a code snippet showing a simple usage example from within Compute/App Engine. Note that you
125+
must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
126+
127+
```java
128+
import com.google.gcloud.bigquery.BigQuery;
129+
import com.google.gcloud.bigquery.BigQueryOptions;
130+
import com.google.gcloud.bigquery.Field;
131+
import com.google.gcloud.bigquery.Job;
132+
import com.google.gcloud.bigquery.JobStatus;
133+
import com.google.gcloud.bigquery.JobInfo;
134+
import com.google.gcloud.bigquery.LoadJobConfiguration;
135+
import com.google.gcloud.bigquery.Schema;
136+
import com.google.gcloud.bigquery.StandardTableDefinition;
137+
import com.google.gcloud.bigquery.Table;
138+
import com.google.gcloud.bigquery.TableId;
139+
import com.google.gcloud.bigquery.TableInfo;
140+
141+
BigQuery bigquery = BigQueryOptions.defaultInstance().service();
142+
TableId tableId = TableId.of("dataset", "table");
143+
Table table = bigquery.getTable(tableId);
144+
if (table == null) {
145+
System.out.println("Creating table " + tableId);
146+
Field integerField = Field.of("fieldName", Field.Type.integer());
147+
Schema schema = Schema.of(integerField);
148+
bigquery.create(TableInfo.of(tableId, StandardTableDefinition.of(schema)));
149+
} else {
150+
System.out.println("Loading data into table " + tableId);
151+
LoadJobConfiguration configuration = LoadJobConfiguration.of(tableId, "gs://bucket/path");
152+
Job loadJob = bigquery.create(JobInfo.of(configuration));
153+
while (!loadJob.isDone()) {
154+
Thread.sleep(1000L);
155+
}
156+
if (loadJob.status().error() != null) {
157+
System.out.println("Job completed with errors");
158+
} else {
159+
System.out.println("Job succeeded");
160+
}
161+
}
162+
```
49163
50164
Google Cloud Datastore
51165
----------------------
@@ -67,7 +181,7 @@ import com.google.gcloud.datastore.Entity;
67181
import com.google.gcloud.datastore.Key;
68182
import com.google.gcloud.datastore.KeyFactory;
69183
70-
Datastore datastore = DatastoreOptions.getDefaultInstance().service();
184+
Datastore datastore = DatastoreOptions.defaultInstance().service();
71185
KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
72186
Key key = keyFactory.newKey(keyName);
73187
Entity entity = datastore.get(key);
@@ -87,6 +201,39 @@ if (entity == null) {
87201
}
88202
```
89203
204+
Google Cloud Resource Manager (Alpha)
205+
----------------------
206+
207+
- [API Documentation][resourcemanager-api]
208+
- [Official Documentation][cloud-resourcemanager-docs]
209+
210+
#### Preview
211+
212+
Here is a code snippet showing a simple usage example. Note that you must supply Google SDK credentials for this service, not other forms of authentication listed in the [Authentication section](#authentication).
213+
214+
```java
215+
import com.google.gcloud.resourcemanager.Project;
216+
import com.google.gcloud.resourcemanager.ResourceManager;
217+
import com.google.gcloud.resourcemanager.ResourceManagerOptions;
218+
219+
import java.util.Iterator;
220+
221+
ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().service();
222+
Project myProject = resourceManager.get("some-project-id"); // Use an existing project's ID
223+
Project newProject = myProject.toBuilder()
224+
.addLabel("launch-status", "in-development")
225+
.build()
226+
.replace();
227+
System.out.println("Updated the labels of project " + newProject.projectId()
228+
+ " to be " + newProject.labels());
229+
// List all the projects you have permission to view.
230+
Iterator<Project> projectIterator = resourceManager.list().iterateAll();
231+
System.out.println("Projects I can view:");
232+
while (projectIterator.hasNext()) {
233+
System.out.println(projectIterator.next().projectId());
234+
}
235+
```
236+
90237
Google Cloud Storage
91238
----------------------
92239
@@ -110,10 +257,9 @@ import com.google.gcloud.storage.StorageOptions;
110257
import java.nio.ByteBuffer;
111258
import java.nio.channels.WritableByteChannel;
112259
113-
StorageOptions options = StorageOptions.builder().projectId("project").build();
114-
Storage storage = options.service();
260+
Storage storage = StorageOptions.defaultInstance().service();
115261
BlobId blobId = BlobId.of("bucket", "blob_name");
116-
Blob blob = Blob.load(storage, blobId);
262+
Blob blob = Blob.get(storage, blobId);
117263
if (blob == null) {
118264
BlobInfo blobInfo = BlobInfo.builder(blobId).contentType("text/plain").build();
119265
storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));
@@ -127,6 +273,11 @@ if (blob == null) {
127273
}
128274
```
129275
276+
Troubleshooting
277+
---------------
278+
279+
To get help, follow the `gcloud-java` links in the `gcloud-*` [shared Troubleshooting document](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/troubleshooting/readme.md#troubleshooting).
280+
130281
Java Versions
131282
-------------
132283
@@ -153,7 +304,7 @@ Contributing
153304
154305
Contributions to this library are always welcome and highly encouraged.
155306
156-
See [CONTRIBUTING] for more information on how to get started.
307+
See `gcloud-java`'s [CONTRIBUTING] documentation and the `gcloud-*` [shared documentation](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/contributing/readme.md#how-to-contribute-to-gcloud) for more information on how to get started.
157308
158309
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
159310
@@ -164,7 +315,7 @@ Apache 2.0 - See [LICENSE] for more information.
164315
165316
166317
[CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
167-
[code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.md
318+
[code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct
168319
[LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
169320
[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md
170321
[cloud-platform]: https://cloud.google.com/
@@ -181,3 +332,10 @@ Apache 2.0 - See [LICENSE] for more information.
181332
[cloud-storage-create-bucket]: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
182333
[cloud-storage-activation]: https://cloud.google.com/storage/docs/signup
183334
[storage-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/storage/package-summary.html
335+
336+
[resourcemanager-api]:http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/resourcemanager/package-summary.html
337+
[cloud-resourcemanager-docs]:https://cloud.google.com/resource-manager/
338+
339+
[cloud-bigquery]: https://cloud.google.com/bigquery/
340+
[cloud-bigquery-docs]: https://cloud.google.com/bigquery/docs/overview
341+
[bigquery-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/gcloud/bigquery/package-summary.html

0 commit comments

Comments
 (0)