---

ajkannan · ajkannan · commit ca53e603b50f · 2016-01-05T10:29:02.000-08:00
yaml --- r: 6701 b: refs/heads/tswast-patch-1 c: d8b1814 h: refs/heads/master i: 6699: dfb6e4e
diff --git a/[refs] b/[refs]
@@ -57,5 +57,5 @@ refs/tags/v0.18.0: 9d193c4c4b9d1c6f21515dd8e50836b9194ec9bb
 refs/tags/v0.19.0: e67b56e4d8dad5f9a7b38c9b2107c23c828f2ed5
 refs/tags/v0.20.0: 839f7fb7156535146aa1cb2c5aadd8d375d854e8
 refs/tags/v0.20.1: 370471f437f1f4f68a11e068df5cd6bf39edb1fa
-refs/heads/tswast-patch-1: d58930eb7bbff659bed22f3019b16b848130ccfc
+refs/heads/tswast-patch-1: d8b1814479f0243e85d3b4b46b604e1608484df6
 refs/heads/pubsub-streaming-pull: 19262b752ee874eb2ca3b950eb2aef44d5a5267b
diff --git a/branches/tswast-patch-1/CONTRIBUTING.md b/branches/tswast-patch-1/CONTRIBUTING.md
@@ -15,6 +15,20 @@ Using maven for build/test
 After you cloned the repository use Maven for building and running the tests.
 Maven 3.0+ is required.
 
+When downloading the source, we recommend you obtain service account credentials. 
+These credentials will allow you to run integration tests using `mvn verify` in command line. 
+Follow step 2 of the [authentication instructions](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) to generate and use JSON service account credentials.
+
+It's also important to test that changes don't break compatibility with App/Compute Engine and when running elsewhere. 
+To run tests on different platforms, try deploying the apps available on the [gcloud-java-examples](https://github.com/GoogleCloudPlatform/gcloud-java-examples) repository. 
+End-to-end tests should ensure that gcloud-java works when running on the
+
+* 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))
+* 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))
+* 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))
+* Your desktop (using `mvn exec:java`, for example)
+
+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).
 
 Adding Features
 ---------------
diff --git a/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/BaseTableInfo.java b/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/BaseTableInfo.java
@@ -94,6 +94,12 @@ public enum Type {
   private final Long expirationTime;
   private final Long lastModifiedTime;
 
+  /**
+   * Base builder for tables.
+   *
+   * @param <T> the table type.
+   * @param <B> the table builder.
+   */
   public abstract static class Builder<T extends BaseTableInfo, B extends Builder<T, B>> {
 
     private String etag;
diff --git a/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java b/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/InsertAllRequest.java
@@ -236,7 +236,16 @@ public Builder ignoreUnknownValues(boolean ignoreUnknownValues) {
     /**
      * If specified, the destination table is treated as a base template. Rows are inserted into an
      * instance table named "{destination}{templateSuffix}". BigQuery will manage the creation of
-     * the instance table, using the schema of the base template table.
+     * the instance table, using the schema of the base template table. Table creation might take
+     * some time. To obtain table's information after {@link BigQuery#insertAll(InsertAllRequest)}
+     * is called use:
+     * <pre> {@code
+     * String suffixTableId = ...;
+     * BaseTableInfo suffixTable = bigquery.getTable(DATASET, suffixTableId);
+     * while (suffixTable == null) {
+     *   Thread.sleep(1000L);
+     *   suffixTable = bigquery.getTable(DATASET, suffixTableId);
+     * }}</pre>
      *
      * @see <a
      *     href="https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables">
@@ -293,7 +302,16 @@ public Boolean skipInvalidRows() {
   /**
    * If specified, the destination table is treated as a base template. Rows are inserted into an
    * instance table named "{destination}{templateSuffix}". BigQuery will manage the creation of the
-   * instance table, using the schema of the base template table.
+   * instance table, using the schema of the base template table. Table creation might take some
+   * time. To obtain table's information after {@link BigQuery#insertAll(InsertAllRequest)} is
+   * called use:
+   * <pre> {@code
+   * String suffixTableId = ...;
+   * BaseTableInfo suffixTable = bigquery.getTable(DATASET, suffixTableId);
+   * while (suffixTable == null) {
+   *   Thread.sleep(1000L);
+   *   suffixTable = bigquery.getTable(DATASET, suffixTableId);
+   * }}</pre>
    *
    * @see <a
    *     href="https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables">
diff --git a/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/JobInfo.java b/branches/tswast-patch-1/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/JobInfo.java
@@ -32,6 +32,8 @@
  * a table. Use {@link QueryJobInfo} for a job that runs a query.
  *
  * @see <a href="https://cloud.google.com/bigquery/docs/reference/v2/jobs">Jobs</a>
+ *
+ * @param <S> the statistics type.
  */
 public abstract class JobInfo<S extends JobStatistics> implements Serializable {
 
@@ -87,6 +89,13 @@ public enum WriteDisposition {
   private final S statistics;
   private final String userEmail;
 
+  /**
+   * Base builder for jobs.
+   *
+   * @param <T> the job type.
+   * @param <S> the job statistics type.
+   * @param <B> the job builder.
+   */
   public abstract static class Builder<T extends JobInfo, S extends JobStatistics,
       B extends Builder<T, S, B>> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java b/branches/tswast-patch-1/gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/ITBigQueryTest.java
@@ -476,7 +476,7 @@ public void testInsertAll() {
   }
 
   @Test
-  public void testInsertAllWithSuffix() {
+  public void testInsertAllWithSuffix() throws InterruptedException {
     String tableName = "test_insert_all_with_suffix_table";
     BaseTableInfo tableInfo = TableInfo.of(TableId.of(DATASET, tableName), TABLE_SCHEMA);
     assertNotNull(bigquery.create(tableInfo));
@@ -505,7 +505,12 @@ public void testInsertAllWithSuffix() {
     assertFalse(response.hasErrors());
     assertEquals(0, response.insertErrors().size());
     String newTableName = tableName + "_suffix";
-    assertNotNull(bigquery.getTable(DATASET, newTableName, TableOption.fields()));
+    BaseTableInfo suffixTable = bigquery.getTable(DATASET, newTableName, TableOption.fields());
+    // wait until the new table is created. If the table is never created the test will time-out
+    while (suffixTable == null) {
+      Thread.sleep(1000L);
+      suffixTable = bigquery.getTable(DATASET, newTableName, TableOption.fields());
+    }
     assertTrue(bigquery.delete(TableId.of(DATASET, tableName)));
     assertTrue(bigquery.delete(TableId.of(DATASET, newTableName)));
   }
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/BaseService.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/BaseService.java
@@ -16,6 +16,11 @@
 
 package com.google.gcloud;
 
+/**
+ * Base class for service objects.
+ *
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public abstract class BaseService<OptionsT extends ServiceOptions<?, ?, OptionsT>>
     implements Service<OptionsT> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Page.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Page.java
@@ -40,6 +40,8 @@
  *   }
  *   page = page.nextPage();
  * }}</pre>
+ *
+ * @param <T> the value type that the page holds.
  */
 public interface Page<T> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java
@@ -25,6 +25,8 @@
 
 /**
  * Base implementation for Google Cloud paginated results.
+ *
+ * @param <T> the value type that the page holds.
  */
 public class PageImpl<T> implements Page<T>, Serializable {
 
@@ -34,6 +36,11 @@ public class PageImpl<T> implements Page<T>, Serializable {
   private final Iterable<T> results;
   private final NextPageFetcher<T> pageFetcher;
 
+  /**
+   * Interface for fetching the next page of results from the service.
+   *
+   * @param <T> the value type that the page holds.
+   */
   public interface NextPageFetcher<T> extends Serializable {
     Page<T> nextPage();
   }
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Restorable.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Restorable.java
@@ -33,6 +33,8 @@
  * X restorableObj = state.restore();
  * ...
  * }</pre>
+ *
+ * @param <T> the restorable object's type.
  */
 public interface Restorable<T extends Restorable<T>> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/RestorableState.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/RestorableState.java
@@ -22,6 +22,8 @@
  *
  * Implementations of this class must implement {@link java.io.Serializable} to ensure that the
  * state of a the object can be correctly serialized.
+ *
+ * @param <T> the restored object's type.
  */
 public interface RestorableState<T extends Restorable<T>> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Service.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/Service.java
@@ -16,6 +16,11 @@
 
 package com.google.gcloud;
 
+/**
+ * Interface for service objects.
+ *
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public interface Service<OptionsT extends ServiceOptions<?, ?, OptionsT>> {
   OptionsT options();
 }
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/ServiceFactory.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/ServiceFactory.java
@@ -19,8 +19,11 @@
 /**
  * A base interface for all service factories.
  *
- * Implementation must provide a public no-arg constructor.
+ * <p>Implementation must provide a public no-arg constructor.
  * Loading of a factory implementation is done via {@link java.util.ServiceLoader}.
+ *
+ * @param <ServiceT> the service subclass.
+ * @param <ServiceOptionsT> the {@code ServiceOptions} subclass corresponding to the service.
  */
 @SuppressWarnings("rawtypes")
 public interface ServiceFactory<ServiceT extends Service, ServiceOptionsT extends ServiceOptions> {
diff --git a/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java b/branches/tswast-patch-1/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java
@@ -53,6 +53,13 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Abstract class representing service options.
+ *
+ * @param <ServiceT> the service subclass.
+ * @param <ServiceRpcT> the spi-layer class corresponding to the service.
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public abstract class ServiceOptions<ServiceT extends Service<OptionsT>, ServiceRpcT,
     OptionsT extends ServiceOptions<ServiceT, ServiceRpcT, OptionsT>> implements Serializable {
 
@@ -150,6 +157,14 @@ private Object readResolve() throws ObjectStreamException {
     }
   }
 
+  /**
+   * Builder for {@code ServiceOptions}.
+   *
+   * @param <ServiceT> the service subclass.
+   * @param <ServiceRpcT> the spi-layer class corresponding to the service.
+   * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+   * @param <B> the {@code ServiceOptions} builder.
+   */
   protected abstract static class Builder<ServiceT extends Service<OptionsT>, ServiceRpcT,
       OptionsT extends ServiceOptions<ServiceT, ServiceRpcT, OptionsT>,
       B extends Builder<ServiceT, ServiceRpcT, OptionsT, B>> {
diff --git a/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/BaseKey.java b/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/BaseKey.java
@@ -31,15 +31,20 @@
 /**
  * Base class for keys.
  */
-abstract class BaseKey extends Serializable<DatastoreV1.Key> {
+public abstract class BaseKey extends Serializable<DatastoreV1.Key> {
 
   private static final long serialVersionUID = -4671243265877410635L;
 
   private final transient String projectId;
   private final transient String namespace;
   private final transient ImmutableList<PathElement> path;
 
-  abstract static class Builder<B extends Builder<B>> {
+  /**
+   * Base class for key builders.
+   *
+   * @param <B> the key builder.
+   */
+  protected abstract static class Builder<B extends Builder<B>> {
 
     String projectId;
     String namespace;
diff --git a/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java b/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java
@@ -609,7 +609,13 @@ public static Projection first(String property) {
     }
   }
 
-  static class BaseBuilder<V, B extends BaseBuilder<V, B>> {
+  /**
+   * Base class for StructuredQuery builders.
+   *
+   * @param <V> the type of result the query returns.
+   * @param <B> the query builder.
+   */
+  protected static class BaseBuilder<V, B extends BaseBuilder<V, B>> {
 
     private final ResultType<V> resultType;
     private String namespace;
diff --git a/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/ValueBuilder.java b/branches/tswast-patch-1/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/ValueBuilder.java
@@ -18,6 +18,10 @@
 
 /**
  * A common interface for Value builders.
+ *
+ * @param <V> the data type that the {@code Value} object holds.
+ * @param <P> the value type.
+ * @param <B> the value type's associated builder.
  */
 public interface ValueBuilder<V, P extends Value<V>, B extends ValueBuilder<V, P, B>> {
 
diff --git a/branches/tswast-patch-1/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Project.java b/branches/tswast-patch-1/gcloud-java-resourcemanager/src/main/java/com/google/gcloud/resourcemanager/Project.java
@@ -42,12 +42,12 @@ public Project(ResourceManager resourceManager, ProjectInfo projectInfo) {
   /**
    * Constructs a Project object that contains project information loaded from the server.
    *
-   * @return Project object containing the project's metadata
+   * @return Project object containing the project's metadata or {@code null} if not found
    * @throws ResourceManagerException upon failure
    */
   public static Project load(ResourceManager resourceManager, String projectId) {
     ProjectInfo projectInfo = resourceManager.get(projectId);
-    return new Project(resourceManager, projectInfo);
+    return projectInfo != null ? new Project(resourceManager, projectInfo) : null;
   }
 
   /**
@@ -67,7 +67,7 @@ public ResourceManager resourceManager() {
   /**
    * Returns a Project object with updated project information.
    *
-   * @return Project object containing the project's updated metadata
+   * @return Project object containing the project's updated metadata or {@code null} if not found
    * @throws ResourceManagerException upon failure
    */
   public Project reload() {
diff --git a/branches/tswast-patch-1/gcloud-java-resourcemanager/src/test/java/com/google/gcloud/resourcemanager/ProjectTest.java b/branches/tswast-patch-1/gcloud-java-resourcemanager/src/test/java/com/google/gcloud/resourcemanager/ProjectTest.java
@@ -21,6 +21,8 @@
 import static org.easymock.EasyMock.replay;
 import static org.easymock.EasyMock.verify;
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertSame;
 
 import com.google.common.collect.ImmutableMap;
@@ -78,6 +80,24 @@ public void testReload() {
     assertEquals(newInfo, newProject.info());
   }
 
+  @Test
+  public void testLoadNull() {
+    expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(null);
+    replay(resourceManager);
+    assertNull(Project.load(resourceManager, PROJECT_INFO.projectId()));
+  }
+
+  @Test
+  public void testReloadDeletedProject() {
+    expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(PROJECT_INFO);
+    expect(resourceManager.get(PROJECT_INFO.projectId())).andReturn(null);
+    replay(resourceManager);
+    Project loadedProject = Project.load(resourceManager, PROJECT_INFO.projectId());
+    assertNotNull(loadedProject);
+    Project reloadedProject = loadedProject.reload();
+    assertNull(reloadedProject);
+  }
+
   @Test
   public void testInfo() {
     replay(resourceManager);
