Update resource-manager branch

README.md

@@ -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
 --------------------
@@ -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
 ----------------------
@@ -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);

gcloud-java-core/README.md

@@ -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
 -------------

gcloud-java-core/pom.xml

@@ -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>

gcloud-java-core/src/main/java/com/google/gcloud/AuthCredentials.java

@@ -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

gcloud-java-core/src/main/java/com/google/gcloud/BaseServiceException.java

@@ -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;
+  }
+}

gcloud-java-core/src/main/java/com/google/gcloud/ExceptionHandler.java

@@ -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;
   }
 
@@ -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;
   }
 

gcloud-java-core/src/main/java/com/google/gcloud/Page.java

@@ -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();
+
+}

gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java

@@ -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);
+  }
+}