Add common interface for field selectors

gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/BigQuery.java

@@ -19,16 +19,15 @@
 import static com.google.common.base.Preconditions.checkArgument;
 
 import com.google.common.base.Function;
-import com.google.common.base.Joiner;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Lists;
-import com.google.common.collect.Sets;
+import com.google.gcloud.FieldSelector;
+import com.google.gcloud.FieldSelector.Helper;
 import com.google.gcloud.Page;
 import com.google.gcloud.Service;
 import com.google.gcloud.bigquery.spi.BigQueryRpc;
 
 import java.util.List;
-import java.util.Set;
 
 /**
  * An interface for Google Cloud BigQuery.
@@ -43,7 +42,7 @@ public interface BigQuery extends Service<BigQueryOptions> {
    * @see <a href="https://cloud.google.com/bigquery/docs/reference/v2/datasets#resource">Dataset
    *     Resource</a>
    */
-  enum DatasetField {
+  enum DatasetField implements FieldSelector {
     ACCESS("access"),
     CREATION_TIME("creationTime"),
     DATASET_REFERENCE("datasetReference"),
@@ -56,24 +55,19 @@ enum DatasetField {
     LOCATION("location"),
     SELF_LINK("selfLink");
 
+    static final List<? extends FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.of(DATASET_REFERENCE);
+
     private final String selector;
 
     DatasetField(String selector) {
       this.selector = selector;
     }
 
+    @Override
     public String selector() {
       return selector;
     }
-
-    static String selector(DatasetField... fields) {
-      Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(fields.length + 1);
-      fieldStrings.add(DATASET_REFERENCE.selector());
-      for (DatasetField field : fields) {
-        fieldStrings.add(field.selector());
-      }
-      return Joiner.on(',').join(fieldStrings);
-    }
   }
 
   /**
@@ -82,7 +76,7 @@ static String selector(DatasetField... fields) {
    * @see <a href="https://cloud.google.com/bigquery/docs/reference/v2/tables#resource">Table
    *     Resource</a>
    */
-  enum TableField {
+  enum TableField implements FieldSelector {
     CREATION_TIME("creationTime"),
     DESCRIPTION("description"),
     ETAG("etag"),
@@ -101,25 +95,19 @@ enum TableField {
     TYPE("type"),
     VIEW("view");
 
+    static final List<? extends FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.of(TABLE_REFERENCE, TYPE);
+
     private final String selector;
 
     TableField(String selector) {
       this.selector = selector;
     }
 
+    @Override
     public String selector() {
       return selector;
     }
-
-    static String selector(TableField... fields) {
-      Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(fields.length + 2);
-      fieldStrings.add(TABLE_REFERENCE.selector());
-      fieldStrings.add(TYPE.selector());
-      for (TableField field : fields) {
-        fieldStrings.add(field.selector());
-      }
-      return Joiner.on(',').join(fieldStrings);
-    }
   }
 
   /**
@@ -128,7 +116,7 @@ static String selector(TableField... fields) {
    * @see <a href="https://cloud.google.com/bigquery/docs/reference/v2/jobs#resource">Job Resource
    *     </a>
    */
-  enum JobField {
+  enum JobField implements FieldSelector {
     CONFIGURATION("configuration"),
     ETAG("etag"),
     ID("id"),
@@ -138,25 +126,19 @@ enum JobField {
     STATUS("status"),
     USER_EMAIL("user_email");
 
+    static final List<? extends FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.of(JOB_REFERENCE, CONFIGURATION);
+
     private final String selector;
 
     JobField(String selector) {
       this.selector = selector;
     }
 
+    @Override
     public String selector() {
       return selector;
     }
-
-    static String selector(JobField... fields) {
-      Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(fields.length + 2);
-      fieldStrings.add(JOB_REFERENCE.selector());
-      fieldStrings.add(CONFIGURATION.selector());
-      for (JobField field : fields) {
-        fieldStrings.add(field.selector());
-      }
-      return Joiner.on(',').join(fieldStrings);
-    }
   }
 
   /**
@@ -210,7 +192,8 @@ private DatasetOption(BigQueryRpc.Option option, Object value) {
      * returned, even if not specified.
      */
     public static DatasetOption fields(DatasetField... fields) {
-      return new DatasetOption(BigQueryRpc.Option.FIELDS, DatasetField.selector(fields));
+      return new DatasetOption(BigQueryRpc.Option.FIELDS,
+          Helper.selector(DatasetField.REQUIRED_FIELDS, fields));
     }
   }
 
@@ -279,7 +262,8 @@ private TableOption(BigQueryRpc.Option option, Object value) {
      * of {@link Table#definition()}) are always returned, even if not specified.
      */
     public static TableOption fields(TableField... fields) {
-      return new TableOption(BigQueryRpc.Option.FIELDS, TableField.selector(fields));
+      return new TableOption(BigQueryRpc.Option.FIELDS,
+          Helper.selector(TableField.REQUIRED_FIELDS, fields));
     }
   }
 
@@ -376,10 +360,8 @@ public static JobListOption pageToken(String pageToken) {
      * listing jobs.
      */
     public static JobListOption fields(JobField... fields) {
-      String selector = JobField.selector(fields);
-      StringBuilder builder = new StringBuilder();
-      builder.append("etag,jobs(").append(selector).append(",state,errorResult),nextPageToken");
-      return new JobListOption(BigQueryRpc.Option.FIELDS, builder.toString());
+      return new JobListOption(BigQueryRpc.Option.FIELDS,
+          Helper.listSelector("jobs", JobField.REQUIRED_FIELDS, fields, "state", "errorResult"));
     }
   }
 
@@ -402,7 +384,8 @@ private JobOption(BigQueryRpc.Option option, Object value) {
      * returned, even if not specified.
      */
     public static JobOption fields(JobField... fields) {
-      return new JobOption(BigQueryRpc.Option.FIELDS, JobField.selector(fields));
+      return new JobOption(BigQueryRpc.Option.FIELDS,
+          Helper.selector(JobField.REQUIRED_FIELDS, fields));
     }
   }
 

gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/Option.java

@@ -27,7 +27,7 @@
 /**
  * Base class for BigQuery operation option.
  */
-class Option implements Serializable {
+abstract class Option implements Serializable {
 
   private static final long serialVersionUID = -6647817677804099207L;
 
@@ -53,8 +53,7 @@ public boolean equals(Object obj) {
       return false;
     }
     Option other = (Option) obj;
-    return Objects.equals(rpcOption, other.rpcOption)
-        && Objects.equals(value, other.value);
+    return Objects.equals(rpcOption, other.rpcOption) && Objects.equals(value, other.value);
   }
 
   @Override

gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/BigQueryImplTest.java

@@ -886,12 +886,14 @@ public com.google.api.services.bigquery.model.Job apply(Job job) {
     assertEquals(cursor, page.nextPageCursor());
     assertArrayEquals(jobList.toArray(), Iterables.toArray(page.values(), Job.class));
     String selector = (String) capturedOptions.getValue().get(JOB_OPTION_FIELDS.rpcOption());
-    assertTrue(selector.contains("etag,jobs("));
+    assertTrue(selector.contains("nextPageToken,jobs("));
     assertTrue(selector.contains("configuration"));
     assertTrue(selector.contains("jobReference"));
     assertTrue(selector.contains("statistics"));
-    assertTrue(selector.contains("state,errorResult),nextPageToken"));
-    assertEquals(80, selector.length());
+    assertTrue(selector.contains("state"));
+    assertTrue(selector.contains("errorResult"));
+    assertTrue(selector.contains(")"));
+    assertEquals(75, selector.length());
   }
 
   @Test

gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/OptionTest.java

@@ -17,22 +17,49 @@
 package com.google.gcloud.bigquery;
 
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNull;
 
 import com.google.gcloud.bigquery.spi.BigQueryRpc;
 
+import org.junit.Rule;
 import org.junit.Test;
+import org.junit.rules.ExpectedException;
 
 public class OptionTest {
 
+  private static final BigQueryRpc.Option RPC_OPTION = BigQueryRpc.Option.PAGE_TOKEN;
+  private static final BigQueryRpc.Option ANOTHER_RPC_OPTION = BigQueryRpc.Option.FIELDS;
+  private static final String VALUE = "some value";
+  private static final String OTHER_VALUE = "another value";
+  private static final Option OPTION = new Option(RPC_OPTION, VALUE) {};
+  private static final Option OPTION_EQUALS = new Option(RPC_OPTION, VALUE) {};
+  private static final Option OPTION_NOT_EQUALS1 = new Option(RPC_OPTION, OTHER_VALUE) {};
+  private static final Option OPTION_NOT_EQUALS2 = new Option(ANOTHER_RPC_OPTION, VALUE) {};
+
+  @Rule
+  public ExpectedException thrown = ExpectedException.none();
+
+  @Test
+  public void testEquals() {
+    assertEquals(OPTION, OPTION_EQUALS);
+    assertNotEquals(OPTION, OPTION_NOT_EQUALS1);
+    assertNotEquals(OPTION, OPTION_NOT_EQUALS2);
+  }
+
   @Test
-  public void testOption() {
-    Option option = new Option(BigQueryRpc.Option.PAGE_TOKEN, "token");
-    assertEquals(BigQueryRpc.Option.PAGE_TOKEN, option.rpcOption());
-    assertEquals("token", option.value());
+  public void testHashCode() {
+    assertEquals(OPTION.hashCode(), OPTION_EQUALS.hashCode());
   }
 
-  @Test(expected = NullPointerException.class)
-  public void testNullRpcOption() {
-    new Option(null, "token");
+  @Test
+  public void testConstructor() {
+    assertEquals(RPC_OPTION, OPTION.rpcOption());
+    assertEquals(VALUE, OPTION.value());
+    Option option = new Option(RPC_OPTION, null) {};
+    assertEquals(RPC_OPTION, option.rpcOption());
+    assertNull(option.value());
+    thrown.expect(NullPointerException.class);
+    new Option(null, VALUE) {};
   }
 }

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

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2016 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.base.Function;
+import com.google.common.base.Joiner;
+import com.google.common.collect.Lists;
+import com.google.common.collect.Sets;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Interface for Google Cloud resource's fields. Implementations of this interface can be used to
+ * select only desired fields from a returned Google Cloud resource.
+ */
+public interface FieldSelector {
+
+  /**
+   * Returns a string selector. This selector is passed to a Google Cloud service (possibly with
+   * other field selectors) to specify which resource fields should be returned by an API call.
+   */
+  String selector();
+
+  /**
+   * A helper class used to build composite selectors given a number of fields. This class is not
+   * supposed to be used directly by users.
+   */
+  class Helper {
+
+    private Helper() {}
+
+    private static final Function<FieldSelector, String> FIELD_TO_STRING_FUNCTION =
+        new Function<FieldSelector, String>() {
+          @Override
+          public String apply(FieldSelector fieldSelector) {
+            return fieldSelector.selector();
+          }
+        };
+
+    private static String selector(List<? extends FieldSelector> required, FieldSelector[] others,
+      String... extraResourceFields) {
+      Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(required.size() + others.length);
+      fieldStrings.addAll(Lists.transform(required, FIELD_TO_STRING_FUNCTION));
+      fieldStrings.addAll(Lists.transform(Arrays.asList(others), FIELD_TO_STRING_FUNCTION));
+      fieldStrings.addAll(Arrays.asList(extraResourceFields));
+      return Joiner.on(',').join(fieldStrings);
+    }
+
+    /**
+     * Returns a composite selector given a number of fields. The string selector returned by this
+     * method can be used for field selection in API calls that return a single resource. This
+     * method is not supposed to be used directly by users.
+     */
+    public static String selector(List<? extends FieldSelector> required, FieldSelector... others) {
+      return selector(required, others, new String[]{});
+    }
+
+    /**
+     * Returns a composite selector given a number of fields and a container name. The string
+     * selector returned by this method can be used for field selection in API calls that return a
+     * list of resources. This method is not supposed to be used directly by users.
+     */
+    public static String listSelector(String containerName, List<? extends FieldSelector> required,
+        FieldSelector... others) {
+      return "nextPageToken," + containerName + '(' + selector(required, others) + ')';
+    }
+
+    /**
+     * Returns a composite selector given a number of fields and a container name. This methods also
+     * takes an {@code extraResourceFields} parameter to specify some extra fields as strings. The
+     * string selector returned by this method can be used for field selection in API calls that
+     * return a list of resources. This method is not supposed to be used directly by users.
+     */
+    public static String listSelector(String containerName, List<? extends FieldSelector> required,
+        FieldSelector[] others, String... extraResourceFields) {
+      return "nextPageToken," + containerName + '('
+          + selector(required, others, extraResourceFields) + ')';
+    }
+  }
+}