Add common interface for field selectors

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

@@ -19,16 +19,14 @@
 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.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 +41,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 +54,19 @@ enum DatasetField {
     LOCATION("location"),
     SELF_LINK("selfLink");
 
+    static final List<FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.<FieldSelector>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 +75,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 +94,19 @@ enum TableField {
     TYPE("type"),
     VIEW("view");
 
+    static final List<FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.<FieldSelector>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 +115,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 +125,19 @@ enum JobField {
     STATUS("status"),
     USER_EMAIL("user_email");
 
+    static final List<FieldSelector> REQUIRED_FIELDS =
+        ImmutableList.<FieldSelector>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 +191,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,
+          selector(DatasetField.REQUIRED_FIELDS, fields));
     }
   }
 
@@ -279,7 +261,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,
+          selector(TableField.REQUIRED_FIELDS, fields));
     }
   }
 
@@ -376,9 +359,9 @@ 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");
+      StringBuilder builder =
+          selector(new StringBuilder().append("etag,jobs("), JobField.REQUIRED_FIELDS, fields)
+              .append(",state,errorResult),nextPageToken");
       return new JobListOption(BigQueryRpc.Option.FIELDS, builder.toString());
     }
   }
@@ -402,7 +385,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,
+          Option.selector(JobField.REQUIRED_FIELDS, fields));
     }
   }
 

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

@@ -18,11 +18,16 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects;
+import com.google.common.collect.Sets;
+import com.google.gcloud.FieldSelector;
 import com.google.gcloud.bigquery.spi.BigQueryRpc;
 
 import java.io.Serializable;
+import java.util.List;
 import java.util.Objects;
+import java.util.Set;
 
 /**
  * Base class for BigQuery operation option.
@@ -53,8 +58,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
@@ -69,4 +73,20 @@ public String toString() {
         .add("value", value)
         .toString();
   }
+
+  static String selector(List<FieldSelector> required, FieldSelector... others) {
+    Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(required.size() + others.length);
+    for (FieldSelector field : required) {
+      fieldStrings.add(field.selector());
+    }
+    for (FieldSelector field : others) {
+      fieldStrings.add(field.selector());
+    }
+    return Joiner.on(',').join(fieldStrings);
+  }
+
+  static StringBuilder selector(StringBuilder partialSelector, List<FieldSelector> required,
+      FieldSelector... others) {
+    return partialSelector.append(selector(required, others));
+  }
 }

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

@@ -0,0 +1,30 @@
+/*
+ * 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;
+
+/**
+ * Interface for Google Cloud resource's fields. Implementations of this interface can be used to
+ * select only desired fields when getting or listing Google Cloud resources.
+ */
+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();
+}

gcloud-java-dns/src/main/java/com/google/gcloud/dns/AbstractOption.java

@@ -18,11 +18,16 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects;
+import com.google.common.collect.Sets;
+import com.google.gcloud.FieldSelector;
 import com.google.gcloud.dns.spi.DnsRpc;
 
 import java.io.Serializable;
+import java.util.List;
 import java.util.Objects;
+import java.util.Set;
 
 /**
  * A base class for options.
@@ -67,4 +72,20 @@ public String toString() {
         .add("rpcOption", rpcOption)
         .toString();
   }
+
+  static String selector(List<FieldSelector> required, FieldSelector... others) {
+    Set<String> fieldStrings = Sets.newHashSetWithExpectedSize(required.size() + others.length);
+    for (FieldSelector field : required) {
+      fieldStrings.add(field.selector());
+    }
+    for (FieldSelector field : others) {
+      fieldStrings.add(field.selector());
+    }
+    return Joiner.on(',').join(fieldStrings);
+  }
+
+  static StringBuilder selector(StringBuilder partialSelector, List<FieldSelector> required,
+      FieldSelector... others) {
+    return partialSelector.append(selector(required, others));
+  }
 }