Add snippets to datastore's Query class and tests (#1256)

google-cloud-datastore/src/main/java/com/google/cloud/datastore/Query.java

@@ -182,6 +182,15 @@ ToStringHelper toStringHelper() {
   /**
    * Returns a new {@link GqlQuery} builder.
    *
+   * <p>Example of creating and running a GQL query.
+   * <pre> {@code
+   * String kind = "my_kind";
+   * String gqlQuery = "select * from " + kind;
+   * Query<?> query = Query.gqlQueryBuilder(gqlQuery).build();
+   * QueryResults<?> results = datastore.run(query);
+   * // Use results
+   * }</pre>
+   *
    * @see <a href="https://cloud.google.com/datastore/docs/apis/gql/gql_reference">GQL Reference</a>
    */
   public static GqlQuery.Builder<?> gqlQueryBuilder(String gql) {
@@ -191,6 +200,15 @@ public static GqlQuery.Builder<?> gqlQueryBuilder(String gql) {
   /**
    * Returns a new {@link GqlQuery} builder.
    *
+   * <p>Example of creating and running a typed GQL query.
+   * <pre> {@code
+   * String kind = "my_kind";
+   * String gqlQuery = "select * from " + kind;
+   * Query<Entity> query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
+   * QueryResults<Entity> results = datastore.run(query);
+   * // Use results
+   * }</pre>
+   *
    * @see <a href="https://cloud.google.com/datastore/docs/apis/gql/gql_reference">GQL Reference</a>
    */
   public static <V> GqlQuery.Builder<V> gqlQueryBuilder(ResultType<V> resultType, String gql) {
@@ -199,20 +217,51 @@ public static <V> GqlQuery.Builder<V> gqlQueryBuilder(ResultType<V> resultType,
 
   /**
    * Returns a new {@link StructuredQuery} builder for full (complete entities) queries.
+   *
+   * <p>Example of creating and running an entity query.
+   * <pre> {@code
+   * String kind = "my_kind";
+   * Query<Entity> query = Query.entityQueryBuilder().kind(kind).build();
+   * QueryResults<Entity> results = datastore.run(query);
+   * // Use results
+   * }</pre>
+   *
    */
   public static EntityQuery.Builder entityQueryBuilder() {
     return new EntityQuery.Builder();
   }
 
   /**
    * Returns a new {@link StructuredQuery} builder for key only queries.
+   *
+   * <p>Example of creating and running a key query.
+   * <pre> {@code
+   * String kind = "my_kind";
+   * Query<Key> query = Query.keyQueryBuilder().kind(kind).build();
+   * QueryResults<Key> results = datastore.run(query);
+   * // Use results
+   * }</pre>
+   *
    */
   public static KeyQuery.Builder keyQueryBuilder() {
     return new KeyQuery.Builder();
   }
 
   /**
    * Returns a new {@link StructuredQuery} builder for projection queries.
+   *
+   * <p>Example of creating and running a projection entity query.
+   * <pre> {@code
+   * String kind = "my_kind";
+   * String property = "my_property";
+   * Query<ProjectionEntity> query = Query.projectionEntityQueryBuilder()
+   *     .kind(kind)
+   *     .addProjection(property)
+   *     .build();
+   * QueryResults<ProjectionEntity> results = datastore.run(query);
+   * // Use results
+   * }</pre>
+   *
    */
   public static ProjectionEntityQuery.Builder projectionEntityQueryBuilder() {
     return new ProjectionEntityQuery.Builder();

google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java

@@ -0,0 +1,118 @@
+/*
+ * 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.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Query's javadoc. Any change to this file should be reflected in
+ * Query's javadoc.
+ */
+
+package com.google.cloud.examples.datastore.snippets;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.ProjectionEntity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+
+/**
+ * This class contains a number of snippets for the {@link Query} class.
+ */
+public class QuerySnippets {
+
+  private final Datastore datastore;
+
+  public QuerySnippets(Datastore datastore) {
+    this.datastore = datastore;
+  }
+
+  /**
+   * Example of creating and running a GQL query.
+   */
+  // [TARGET gqlQueryBuilder(String)]
+  // [VARIABLE "my_kind"]
+  public QueryResults<?> newQuery(String kind) {
+    // [START newQuery]
+    String gqlQuery = "select * from " + kind;
+    Query<?> query = Query.gqlQueryBuilder(gqlQuery).build();
+    QueryResults<?> results = datastore.run(query);
+    // Use results
+    // [END newQuery]
+    return results;
+  }
+
+  /**
+   * Example of creating and running a typed GQL query.
+   */
+  // [TARGET gqlQueryBuilder(ResultType, String)]
+  // [VARIABLE "my_kind"]
+  public QueryResults<Entity> newTypedQuery(String kind) {
+    // [START newTypedQuery]
+    String gqlQuery = "select * from " + kind;
+    Query<Entity> query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
+    QueryResults<Entity> results = datastore.run(query);
+    // Use results
+    // [END newTypedQuery]
+    return results;
+  }
+
+  /**
+   * Example of creating and running an entity query.
+   */
+  // [TARGET entityQueryBuilder()]
+  // [VARIABLE "my_kind"]
+  public QueryResults<Entity> newEntityQuery(String kind) {
+    // [START newEntityQuery]
+    Query<Entity> query = Query.entityQueryBuilder().kind(kind).build();
+    QueryResults<Entity> results = datastore.run(query);
+    // Use results
+    // [END newEntityQuery]
+    return results;
+  }
+
+  /**
+   * Example of creating and running a key query.
+   */
+  // [TARGET keyQueryBuilder()]
+  // [VARIABLE "my_kind"]
+  public QueryResults<Key> newKeyQuery(String kind) {
+    // [START newKeyQuery]
+    Query<Key> query = Query.keyQueryBuilder().kind(kind).build();
+    QueryResults<Key> results = datastore.run(query);
+    // Use results
+    // [END newKeyQuery]
+    return results;
+  }
+
+  /**
+   * Example of creating and running a projection entity query.
+   */
+  // [TARGET projectionEntityQueryBuilder()]
+  // [VARIABLE "my_kind"]
+  // [VARIABLE "my_property"]
+  public QueryResults<ProjectionEntity> newProjectionEntityQuery(String kind, String property) {
+    // [START newProjectionEntityQuery]
+    Query<ProjectionEntity> query = Query.projectionEntityQueryBuilder()
+        .kind(kind)
+        .addProjection(property)
+        .build();
+    QueryResults<ProjectionEntity> results = datastore.run(query);
+    // Use results
+    // [END newProjectionEntityQuery]
+    return results;
+  }
+}

google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java

@@ -0,0 +1,127 @@
+/*
+ * 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.cloud.examples.datastore.snippets;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.ProjectionEntity;
+import com.google.cloud.datastore.QueryResults;
+import com.google.common.base.Function;
+import com.google.common.collect.Iterators;
+import com.google.common.collect.Sets;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.Timeout;
+
+import java.util.Set;
+import java.util.UUID;
+
+public class ITQuerySnippets {
+
+  private static Datastore datastore;
+  private static Entity entity1;
+  private static Entity entity2;
+  private static final String KIND = "kind_" + UUID.randomUUID().toString().replace("-", "");
+  private static final Function<ProjectionEntity, String> ENTITY_TO_DESCRIPTION_FUNCTION =
+      new Function<ProjectionEntity, String>() {
+        @Override
+        public String apply(ProjectionEntity entity) {
+          return entity.getString("description");
+        }
+      };
+
+  @Rule
+  public Timeout globalTimeout = Timeout.seconds(60);
+
+  @BeforeClass
+  public static void beforeClass() {
+    datastore = DatastoreOptions.defaultInstance().service();
+    Key key1 = Key.builder(datastore.options().projectId(), KIND, "key1").build();
+    Key key2 = Key.builder(datastore.options().projectId(), KIND, "key2").build();
+    entity1 = Entity.builder(key1).set("description", "entity1").build();
+    entity2 = Entity.builder(key2).set("description", "entity2").build();
+    datastore.put(entity1, entity2);
+  }
+
+  @AfterClass
+  public static void afterClass() {
+    datastore.delete(entity1.key(), entity2.key());
+  }
+
+  @Test
+  public void testNewQuery() throws InterruptedException {
+    QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+    QueryResults<?> results = transactionSnippets.newQuery(KIND);
+    Set<?> resultSet = Sets.newHashSet(results);
+    while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+      Thread.sleep(500);
+      resultSet = Sets.newHashSet(results);
+    }
+  }
+
+  @Test
+  public void testNewTypedQuery() throws InterruptedException {
+    QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+    QueryResults<Entity> results = transactionSnippets.newTypedQuery(KIND);
+    Set<Entity> resultSet = Sets.newHashSet(results);
+    while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+      Thread.sleep(500);
+      resultSet = Sets.newHashSet(results);
+    }
+  }
+
+  @Test
+  public void testNewEntityQuery() throws InterruptedException {
+    QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+    QueryResults<Entity> results = transactionSnippets.newEntityQuery(KIND);
+    Set<Entity> resultSet = Sets.newHashSet(results);
+    while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
+      Thread.sleep(500);
+      resultSet = Sets.newHashSet(results);
+    }
+  }
+
+  @Test
+  public void testNewKeyQuery() throws InterruptedException {
+    QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+    QueryResults<Key> results = transactionSnippets.newKeyQuery(KIND);
+    Set<Key> resultSet = Sets.newHashSet(results);
+    while (!resultSet.contains(entity1.key()) || !resultSet.contains(entity2.key())) {
+      Thread.sleep(500);
+      resultSet = Sets.newHashSet(results);
+    }
+  }
+
+  @Test
+  public void testNewProjectionEntityQuery() throws InterruptedException {
+    QuerySnippets transactionSnippets = new QuerySnippets(datastore);
+    QueryResults<ProjectionEntity> results =
+        transactionSnippets.newProjectionEntityQuery(KIND, "description");
+    Set<String> resultSet =
+        Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
+    while (!resultSet.contains(entity1.getString("description"))
+        || !resultSet.contains(entity2.getString("description"))) {
+      Thread.sleep(500);
+      resultSet = Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
+    }
+  }
+}