From a60d06f914b608b4bcc80896f5dd431f40ad79a8 Mon Sep 17 00:00:00 2001 From: Marco Ziccardi Date: Mon, 19 Sep 2016 13:14:58 +0200 Subject: [PATCH] Add snippets to datastore's Query class and tests (#1256) --- .../com/google/cloud/datastore/Query.java | 49 +++++++ .../datastore/snippets/QuerySnippets.java | 118 ++++++++++++++++ .../datastore/snippets/ITQuerySnippets.java | 127 ++++++++++++++++++ 3 files changed, 294 insertions(+) create mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java create mode 100644 google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Query.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Query.java index a2396bad0e78..02197684928a 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Query.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Query.java @@ -182,6 +182,15 @@ ToStringHelper toStringHelper() { /** * Returns a new {@link GqlQuery} builder. * + *

Example of creating and running a GQL query. + * 

 {@code
+   * String kind = "my_kind";
+   * String gqlQuery = "select * from " + kind;
+   * Query query = Query.gqlQueryBuilder(gqlQuery).build();
+   * QueryResults results = datastore.run(query);
+   * // Use results
+   * }
+ * * @see GQL Reference */ public static GqlQuery.Builder gqlQueryBuilder(String gql) { @@ -191,6 +200,15 @@ public static GqlQuery.Builder gqlQueryBuilder(String gql) { /** * Returns a new {@link GqlQuery} builder. * + *

Example of creating and running a typed GQL query. + * 

 {@code
+   * String kind = "my_kind";
+   * String gqlQuery = "select * from " + kind;
+   * Query query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
+   * QueryResults results = datastore.run(query);
+   * // Use results
+   * }
+ * * @see GQL Reference */ public static GqlQuery.Builder gqlQueryBuilder(ResultType resultType, String gql) { @@ -199,6 +217,15 @@ public static GqlQuery.Builder gqlQueryBuilder(ResultType resultType, /** * Returns a new {@link StructuredQuery} builder for full (complete entities) queries. + * + *

Example of creating and running an entity query. + * 

 {@code
+   * String kind = "my_kind";
+   * Query query = Query.entityQueryBuilder().kind(kind).build();
+   * QueryResults results = datastore.run(query);
+   * // Use results
+   * }
+ * */ public static EntityQuery.Builder entityQueryBuilder() { return new EntityQuery.Builder(); @@ -206,6 +233,15 @@ public static EntityQuery.Builder entityQueryBuilder() { /** * Returns a new {@link StructuredQuery} builder for key only queries. + * + *

Example of creating and running a key query. + * 

 {@code
+   * String kind = "my_kind";
+   * Query query = Query.keyQueryBuilder().kind(kind).build();
+   * QueryResults results = datastore.run(query);
+   * // Use results
+   * }
+ * */ public static KeyQuery.Builder keyQueryBuilder() { return new KeyQuery.Builder(); @@ -213,6 +249,19 @@ public static KeyQuery.Builder keyQueryBuilder() { /** * Returns a new {@link StructuredQuery} builder for projection queries. + * + *

Example of creating and running a projection entity query. + * 

 {@code
+   * String kind = "my_kind";
+   * String property = "my_property";
+   * Query query = Query.projectionEntityQueryBuilder()
+   *     .kind(kind)
+   *     .addProjection(property)
+   *     .build();
+   * QueryResults results = datastore.run(query);
+   * // Use results
+   * }
+ * */ public static ProjectionEntityQuery.Builder projectionEntityQueryBuilder() { return new ProjectionEntityQuery.Builder(); diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/QuerySnippets.java new file mode 100644 index 000000000000..b35437cbac9f --- /dev/null +++ b/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 newTypedQuery(String kind) { + // [START newTypedQuery] + String gqlQuery = "select * from " + kind; + Query query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build(); + QueryResults 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 newEntityQuery(String kind) { + // [START newEntityQuery] + Query query = Query.entityQueryBuilder().kind(kind).build(); + QueryResults 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 newKeyQuery(String kind) { + // [START newKeyQuery] + Query query = Query.keyQueryBuilder().kind(kind).build(); + QueryResults 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 newProjectionEntityQuery(String kind, String property) { + // [START newProjectionEntityQuery] + Query query = Query.projectionEntityQueryBuilder() + .kind(kind) + .addProjection(property) + .build(); + QueryResults results = datastore.run(query); + // Use results + // [END newProjectionEntityQuery] + return results; + } +} diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITQuerySnippets.java new file mode 100644 index 000000000000..d735c12c1f75 --- /dev/null +++ b/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 ENTITY_TO_DESCRIPTION_FUNCTION = + new Function() { + @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 results = transactionSnippets.newTypedQuery(KIND); + Set 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 results = transactionSnippets.newEntityQuery(KIND); + Set 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 results = transactionSnippets.newKeyQuery(KIND); + Set 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 results = + transactionSnippets.newProjectionEntityQuery(KIND, "description"); + Set 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)); + } + } +}