Skip to content

Commit

Permalink
Merge pull request #368 from ajkannan/pull-master-updates
Browse files Browse the repository at this point in the history
Update resource-manager branch
  • Loading branch information
aozarov committed Nov 12, 2015
2 parents cfe1633 + e112ce6 commit ebf4adc
Show file tree
Hide file tree
Showing 63 changed files with 2,253 additions and 804 deletions.
64 changes: 59 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,22 @@ This client supports the following Google Cloud Platform services:
Quickstart
----------
Add this to your pom.xml file
If you are using Maven, add this to your pom.xml file
```xml
<dependency>
<groupId>com.google.gcloud</groupId>
<artifactId>gcloud-java</artifactId>
<version>0.0.10</version>
<version>0.0.11</version>
</dependency>
```
If you are using Gradle, add this to your dependencies
```Groovy
compile 'com.google.gcloud:gcloud-java:jar:0.0.11'
```
If you are using SBT, add this to your dependencies
```Scala
libraryDependencies += "com.google.gcloud" % "gcloud-java" % "0.0.11"
```

Example Applications
--------------------
Expand All @@ -37,15 +45,61 @@ Example Applications
- [`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
- 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).

Specifying a Project ID
-----------------------

Most `gcloud-java` libraries require a project ID. There are multiple ways to specify this project ID.

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.
2. When using `gcloud-java` elsewhere, you can do one of the following:
* Supply the project ID when building the service options. For example, to use Datastore from a project with ID "PROJECT_ID", you can write:

```java
Datastore datastore = DatastoreOptions.builder().projectId("PROJECT_ID").build().service();
```
* Specify the environment variable `GCLOUD_PROJECT` to be your desired project ID.
* 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:

```
gcloud config set project PROJECT_ID
```

`gcloud-java` determines the project ID from the following sources in the listed order, stopping once it finds a value:

1. Project ID supplied when building the service options
2. Project ID specified by the environment variable `GCLOUD_PROJECT`
3. App Engine project ID
4. Compute Engine project ID
5. Google Cloud SDK project ID

Authentication
--------------

There are multiple ways to authenticate to use Google Cloud services.

1. When using `gcloud-java` libraries from within Compute/App Engine, no additional authentication steps are necessary.
2. When using `gcloud-java` libraries elsewhere, there are two options:
* [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.
* 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`.
* [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:
* Define the environment variable GOOGLE_APPLICATION_CREDENTIALS to be the location of the key. For example:
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json
```
* 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:
```java
Storage storage = StorageOptions.builder()
.authCredentials(AuthCredentials.createForJson(new FileInputStream("/path/to/my/key.json"))
.build()
.service();
```
* 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.
`gcloud-java` looks for credentials in the following order, stopping once it finds credentials:
1. Credentials supplied when building the service options
2. App Engine credentials
3. Key file pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable
4. Google Cloud SDK credentials
5. Compute Engine credentials
Google Cloud Datastore
----------------------
Expand All @@ -67,7 +121,7 @@ import com.google.gcloud.datastore.Entity;
import com.google.gcloud.datastore.Key;
import com.google.gcloud.datastore.KeyFactory;
Datastore datastore = DatastoreOptions.getDefaultInstance().service();
Datastore datastore = DatastoreOptions.defaultInstance().service();
KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
Key key = keyFactory.newKey(keyName);
Entity entity = datastore.get(key);
Expand Down
12 changes: 10 additions & 2 deletions gcloud-java-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,22 @@ This module provides common functionality required by service-specific modules o

Quickstart
----------
Add this to your pom.xml file
If you are using Maven, add this to your pom.xml file
```xml
<dependency>
<groupId>com.google.gcloud</groupId>
<artifactId>gcloud-java-core</artifactId>
<version>0.0.10</version>
<version>0.0.11</version>
</dependency>
```
If you are using Gradle, add this to your dependencies
```Groovy
compile 'com.google.gcloud:gcloud-java-core:jar:0.0.11'
```
If you are using SBT, add this to your dependencies
```Scala
libraryDependencies += "com.google.gcloud" % "gcloud-java-core" % "0.0.11"
```

Java Versions
-------------
Expand Down
2 changes: 1 addition & 1 deletion gcloud-java-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
<parent>
<groupId>com.google.gcloud</groupId>
<artifactId>gcloud-java-pom</artifactId>
<version>0.0.11-SNAPSHOT</version>
<version>0.0.12-SNAPSHOT</version>
</parent>
<properties>
<site.installationModule>gcloud-java-core</site.installationModule>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ public boolean equals(Object obj) {
@Override
protected HttpRequestInitializer httpRequestInitializer(HttpTransport transport,
Set<String> scopes) {
return new HttpCredentialsAdapter(googleCredentials);
return new HttpCredentialsAdapter(googleCredentials.createScoped(scopes));
}

@Override
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
/*
* Copyright 2015 Google Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.gcloud;

/**
* Base class for all service exceptions.
*/
public class BaseServiceException extends RuntimeException {

private static final long serialVersionUID = 5028833760039966178L;

private final int code;
private final boolean retryable;

public BaseServiceException(int code, String message, boolean retryable) {
super(message);
this.code = code;
this.retryable = retryable;
}

public BaseServiceException(int code, String message, boolean retryable, Exception cause) {
super(message, cause);
this.code = code;
this.retryable = retryable;
}

/**
* Returns the code associated with this exception.
*/
public int code() {
return code;
}

/**
* Returns {@code true} when it is safe to retry the operation that caused this exception.
*/
public boolean retryable() {
return retryable;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -231,11 +231,11 @@ void verifyCaller(Callable<?> callable) {
}
}

public Set<Class<? extends Exception>> getRetriableExceptions() {
public Set<Class<? extends Exception>> retriableExceptions() {
return retriableExceptions;
}

public Set<Class<? extends Exception>> getNonRetriableExceptions() {
public Set<Class<? extends Exception>> nonRetriableExceptions() {
return nonRetriableExceptions;
}

Expand All @@ -262,7 +262,7 @@ boolean shouldRetry(Exception ex) {
/**
* Returns an instance which retry any checked exception and abort on any runtime exception.
*/
public static ExceptionHandler getDefaultInstance() {
public static ExceptionHandler defaultInstance() {
return DEFAULT_INSTANCE;
}

Expand Down
67 changes: 67 additions & 0 deletions gcloud-java-core/src/main/java/com/google/gcloud/Page.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
/*
* Copyright 2015 Google Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.gcloud;

import java.util.Iterator;

/**
* Interface for Google Cloud paginated results.
*
* <p>
* Use {@code Page} to iterate through all values (also in next pages):
* <pre> {@code
* Page<T> page = ...; // get a Page<T> instance
* Iterator<T> iterator = page.iterateAll();
* while (iterator.hasNext()) {
* T value = iterator.next();
* // do something with value
* }}</pre>
* <p>
* Or handle pagination explicitly:
* <pre> {@code
* Page<T> page = ...; // get a Page<T> instance
* while (page != null) {
* for (T value : page.values()) {
* // do something with value
* }
* page = page.nextPage();
* }}</pre>
*/
public interface Page<T> {

/**
* Returns the values contained in this page.
*/
Iterable<T> values();

/**
* Returns an iterator for all values, possibly also in the next pages. Once current page's values
* are traversed the iterator fetches next page, if any.
*/
Iterator<T> iterateAll();

/**
* Returns the cursor for the nextPage or {@code null} if no more results.
*/
String nextPageCursor();

/**
* Returns the next page of results or {@code null} if no more result.
*/
Page<T> nextPage();

}
111 changes: 111 additions & 0 deletions gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
/*
* Copyright 2015 Google Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.gcloud;

import com.google.common.collect.AbstractIterator;

import java.io.Serializable;
import java.util.Collections;
import java.util.Iterator;
import java.util.Objects;

/**
* Base implementation for Google Cloud paginated results.
*/
public class PageImpl<T> implements Page<T>, Serializable {

private static final long serialVersionUID = 3914827379823557934L;

private final String cursor;
private final Iterable<T> results;
private final NextPageFetcher<T> pageFetcher;

public interface NextPageFetcher<T> extends Serializable {
Page<T> nextPage();
}

static class PageIterator<T> extends AbstractIterator<T> {

private Iterator<T> currentPageIterator;
private Page<T> currentPage;

PageIterator(Page<T> currentPage) {
this.currentPageIterator = currentPage.values().iterator();
this.currentPage = currentPage;
}

@Override
protected T computeNext() {
while (!currentPageIterator.hasNext()) {
currentPage = currentPage.nextPage();
if (currentPage == null) {
return endOfData();
}
currentPageIterator = currentPage.values().iterator();
}
return currentPageIterator.next();
}
}

/**
* Creates a {@code PageImpl} object. In order for the object to be serializable the {@code
* results} parameter must be serializable.
*/
public PageImpl(NextPageFetcher<T> pageFetcher, String cursor, Iterable<T> results) {
this.pageFetcher = pageFetcher;
this.cursor = cursor;
this.results = results;
}

@Override
public Iterable<T> values() {
return results == null ? Collections.EMPTY_LIST : results;
}

@Override
public Iterator<T> iterateAll() {
return new PageIterator<T>(this);
}

@Override
public String nextPageCursor() {
return cursor;
}

@Override
public Page<T> nextPage() {
if (cursor == null || pageFetcher == null) {
return null;
}
return pageFetcher.nextPage();
}

@Override
public int hashCode() {
return Objects.hash(cursor, results);
}

@Override
public boolean equals(Object obj) {
if (!(obj instanceof PageImpl)) {
return false;
}
PageImpl<?> other = (PageImpl<?>) obj;
return Objects.equals(cursor, other.cursor)
&& Objects.equals(results, other.results);
}
}
Loading

0 comments on commit ebf4adc

Please sign in to comment.