Adding QueryParameter support in BigQuery

google-cloud-bigquery/pom.xml

@@ -31,7 +31,7 @@
     <dependency>
       <groupId>com.google.apis</groupId>
       <artifactId>google-api-services-bigquery</artifactId>
-      <version>v2-rev303-1.22.0</version>
+      <version>v2-rev330-1.22.0</version>
       <scope>compile</scope>
       <exclusions>
         <exclusion>

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Field.java

@@ -72,19 +72,15 @@ public static class Type implements Serializable {
 
     private static final long serialVersionUID = 2841484762609576959L;
 
-    public enum Value {
-      BYTES, STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, RECORD
-    }
-
-    private final Value value;
+    private final LegacySQLTypeName value;
     private final List<Field> fields;
 
-    private Type(Value value) {
+    private Type(LegacySQLTypeName value) {
       this.value = checkNotNull(value);
       this.fields = null;
     }
 
-    private Type(Value value, List<Field> fields) {
+    private Type(LegacySQLTypeName value, List<Field> fields) {
       checkArgument(fields.size() > 0, "Record must have at least one field");
       this.value = value;
       this.fields = fields;
@@ -97,7 +93,7 @@ private Type(Value value, List<Field> fields) {
      *     Data Types</a>
      */
     @Deprecated
-    public Value value() {
+    public LegacySQLTypeName value() {
       return getValue();
     }
 
@@ -107,81 +103,81 @@ public Value value() {
      * @see <a href="https://cloud.google.com/bigquery/preparing-data-for-bigquery#datatypes">
      *     Data Types</a>
      */
-    public Value getValue() {
+    public LegacySQLTypeName getValue() {
       return value;
     }
 
     /**
-     * Returns the list of sub-fields if {@link #value()} is set to {@link Value#RECORD}. Returns
-     * {@code null} otherwise.
+     * Returns the list of sub-fields if {@link #value()} is set to {@link
+     * LegacySQLTypeName#RECORD}. Returns {@code null} otherwise.
      */
     @Deprecated
     public List<Field> fields() {
       return getFields();
     }
 
     /**
-     * Returns the list of sub-fields if {@link #value()} is set to {@link Value#RECORD}. Returns
-     * {@code null} otherwise.
+     * Returns the list of sub-fields if {@link #value()} is set to {@link
+     * LegacySQLTypeName#RECORD}. Returns {@code null} otherwise.
      */
     public List<Field> getFields() {
       return fields;
     }
 
     /**
-     * Returns a {@link Value#BYTES} field value.
+     * Returns a {@link LegacySQLTypeName#BYTES} field value.
      */
     public static Type bytes() {
-      return new Type(Value.BYTES);
+      return new Type(LegacySQLTypeName.BYTES);
     }
 
     /**
-     * Returns a {@link Value#STRING} field value.
+     * Returns a {@link LegacySQLTypeName#STRING} field value.
      */
     public static Type string() {
-      return new Type(Value.STRING);
+      return new Type(LegacySQLTypeName.STRING);
     }
 
     /**
-     * Returns an {@link Value#INTEGER} field value.
+     * Returns an {@link LegacySQLTypeName#INTEGER} field value.
      */
     public static Type integer() {
-      return new Type(Value.INTEGER);
+      return new Type(LegacySQLTypeName.INTEGER);
     }
 
     /**
-     * Returns a {@link Value#FLOAT} field value.
+     * Returns a {@link LegacySQLTypeName#FLOAT} field value.
      */
     public static Type floatingPoint() {
-      return new Type(Value.FLOAT);
+      return new Type(LegacySQLTypeName.FLOAT);
     }
 
     /**
-     * Returns a {@link Value#BOOLEAN} field value.
+     * Returns a {@link LegacySQLTypeName#BOOLEAN} field value.
      */
     public static Type bool() {
-      return new Type(Value.BOOLEAN);
+      return new Type(LegacySQLTypeName.BOOLEAN);
     }
 
     /**
-     * Returns a {@link Value#TIMESTAMP} field value.
+     * Returns a {@link LegacySQLTypeName#TIMESTAMP} field value.
      */
     public static Type timestamp() {
-      return new Type(Value.TIMESTAMP);
+      return new Type(LegacySQLTypeName.TIMESTAMP);
     }
 
     /**
-     * Returns a {@link Value#RECORD} field value with associated list of sub-fields.
+     * Returns a {@link LegacySQLTypeName#RECORD} field value with associated list of sub-fields.
      */
     public static Type record(Field... fields) {
-      return new Type(Value.RECORD, ImmutableList.copyOf(fields));
+      return new Type(LegacySQLTypeName.RECORD, ImmutableList.copyOf(fields));
     }
 
     /**
-     * Returns a {@link Value#RECORD} field value with associated list of sub-fields.
+     * Returns a {@link LegacySQLTypeName#RECORD} field value with associated list of sub-fields.
      */
     public static Type record(List<Field> fields) {
-      return new Type(Value.RECORD, ImmutableList.copyOf(checkNotNull(fields)));
+      return new Type(LegacySQLTypeName.RECORD, ImmutableList.copyOf(checkNotNull(fields)));
     }
 
     @Override
@@ -389,17 +385,17 @@ public String getDescription() {
   }
 
   /**
-   * Returns the list of sub-fields if {@link #type()} is a {@link Type.Value#RECORD}. Returns
-   * {@code null} otherwise.
+   * Returns the list of sub-fields if {@link #type()} is a {@link LegacySQLTypeName#RECORD}.
+   * Returns {@code null} otherwise.
    */
   @Deprecated
   public List<Field> fields() {
     return getFields();
   }
 
   /**
-   * Returns the list of sub-fields if {@link #type()} is a {@link Type.Value#RECORD}. Returns
-   * {@code null} otherwise.
+   * Returns the list of sub-fields if {@link #type()} is a {@link LegacySQLTypeName#RECORD}.
+   * Returns {@code null} otherwise.
    */
   public List<Field> getFields() {
     return type.getFields();
@@ -474,7 +470,7 @@ public static Builder newBuilder(String name, Type type) {
   static Field fromPb(TableFieldSchema fieldSchemaPb) {
     Builder fieldBuilder = new Builder();
     fieldBuilder.setName(fieldSchemaPb.getName());
-    Type.Value enumValue = Type.Value.valueOf(fieldSchemaPb.getType());
+    LegacySQLTypeName enumValue = LegacySQLTypeName.valueOf(fieldSchemaPb.getType());
     if (fieldSchemaPb.getMode() != null) {
       fieldBuilder.setMode(Mode.valueOf(fieldSchemaPb.getMode()));
     }

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/LegacySQLTypeName.java

@@ -0,0 +1,51 @@
+/*
+ * 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.cloud.bigquery;
+
+/**
+ * A type used in legacy SQL contexts. For example, these types are used in query results,
+ * even if the query is a standard SQL query.
+ */
+public enum LegacySQLTypeName {
+  /** Variable-length binary data. */
+  BYTES(StandardSQLTypeName.BYTES),
+  /** Variable-length character (Unicode) data. */
+  STRING(StandardSQLTypeName.STRING),
+  /** A 64-bit signed integer value. */
+  INTEGER(StandardSQLTypeName.INT64),
+  /** A 64-bit IEEE binary floating-point value. */
+  FLOAT(StandardSQLTypeName.FLOAT64),
+  /** A Boolean value (true or false). */
+  BOOLEAN(StandardSQLTypeName.BOOL),
+  /** Represents an absolute point in time, with microsecond precision. */
+  TIMESTAMP(StandardSQLTypeName.TIMESTAMP),
+  /** A record type with a nested schema. */
+  RECORD(StandardSQLTypeName.STRUCT);
+
+  private StandardSQLTypeName equivalent;
+
+  LegacySQLTypeName(StandardSQLTypeName equivalent) {
+    this.equivalent = equivalent;
+  }
+
+  /**
+   * Provides the standard SQL type name equivalent to this type name.
+   */
+  public StandardSQLTypeName getStandardType() {
+    return equivalent;
+  }
+}

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/QueryParameter.java

@@ -0,0 +1,128 @@
+/*
+ * 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.cloud.bigquery;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.base.Function;
+import com.google.common.base.MoreObjects;
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * A query parameter for a Google BigQuery query.
+ *
+ * <p>Each query parameter has a name and a typed value. The name is used for queries with named
+ * parameters, and should be null for queries with positional parameters. All scalar types are
+ * converted into strings before being passed to the server, but the nature of the conversion
+ * depends on the particular type.
+ *
+ * <p>See {@link QueryParameterValue} for more details on the supported types and how to provide
+ * them.
+ */
+public class QueryParameter implements Serializable {
+  static final Function<com.google.api.services.bigquery.model.QueryParameter, QueryParameter>
+      FROM_PB_FUNCTION =
+          new Function<com.google.api.services.bigquery.model.QueryParameter, QueryParameter>() {
+            @Override
+            public QueryParameter apply(com.google.api.services.bigquery.model.QueryParameter pb) {
+              return QueryParameter.fromPb(pb);
+            }
+          };
+  static final Function<QueryParameter, com.google.api.services.bigquery.model.QueryParameter>
+      TO_PB_FUNCTION =
+          new Function<QueryParameter, com.google.api.services.bigquery.model.QueryParameter>() {
+            @Override
+            public com.google.api.services.bigquery.model.QueryParameter apply(
+                QueryParameter queryParameter) {
+              return queryParameter.toPb();
+            }
+          };
+
+  private static final long serialVersionUID = -3106977352686037480L;
+
+  private final String name;
+  private final QueryParameterValue parameterValue;
+
+  private QueryParameter(String name, QueryParameterValue parameterValue) {
+    this.name = name;
+    this.parameterValue = checkNotNull(parameterValue);
+  }
+
+  /** Returns the query parameter name. */
+  public String getName() {
+    return name;
+  }
+
+  /** Returns the typed query parameter value. */
+  public QueryParameterValue getParameterValue() {
+    return parameterValue;
+  }
+
+  /**
+   * Creates a positional {@code QueryParameter} object with the given value.
+   */
+  public static QueryParameter of(QueryParameterValue value) {
+    return new QueryParameter(null, value);
+  }
+
+  /**
+   * Creates a named {@code QueryParameter} object with the given value.
+   */
+  public static QueryParameter named(String name, QueryParameterValue value) {
+    return new QueryParameter(name, value);
+  }
+
+  @Override
+  public String toString() {
+    return MoreObjects.toStringHelper(this)
+        .add("name", name)
+        .add("parameterValue", parameterValue)
+        .toString();
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(name, parameterValue);
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    return obj instanceof QueryParameter && Objects.equals(toPb(), ((QueryParameter) obj).toPb());
+  }
+
+  com.google.api.services.bigquery.model.QueryParameter toPb() {
+    com.google.api.services.bigquery.model.QueryParameter queryParameterPb =
+        new com.google.api.services.bigquery.model.QueryParameter();
+    queryParameterPb.setName(name);
+    if (parameterValue != null) {
+      queryParameterPb.setParameterValue(parameterValue.toValuePb());
+      queryParameterPb.setParameterType(parameterValue.toTypePb());
+    }
+    return queryParameterPb;
+  }
+
+  static QueryParameter fromPb(
+      com.google.api.services.bigquery.model.QueryParameter queryParameterPb) {
+    checkNotNull(queryParameterPb.getParameterType());
+    checkNotNull(queryParameterPb.getParameterValue());
+    QueryParameterValue value =
+          QueryParameterValue.fromPb(
+              queryParameterPb.getParameterValue(), queryParameterPb.getParameterType());
+    return named(queryParameterPb.getName(), value);
+  }
+}