Skip to content

Commit a60d06f

Browse files
mziccardmziccard
authored
Add snippets to datastore's Query class and tests (#1256)
1 parent 2a89cdf commit a60d06f

3 files changed

Lines changed: 294 additions & 0 deletions

File tree

  • google-cloud-datastore/src/main/java/com/google/cloud/datastore
  • google-cloud-examples/src

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,15 @@ ToStringHelper toStringHelper() {
182182
/**
183183
* Returns a new {@link GqlQuery} builder.
184184
*
185+
* <p>Example of creating and running a GQL query.
186+
* <pre> {@code
187+
* String kind = "my_kind";
188+
* String gqlQuery = "select * from " + kind;
189+
* Query<?> query = Query.gqlQueryBuilder(gqlQuery).build();
190+
* QueryResults<?> results = datastore.run(query);
191+
* // Use results
192+
* }</pre>
193+
*
185194
* @see <a href="https://cloud.google.com/datastore/docs/apis/gql/gql_reference">GQL Reference</a>
186195
*/
187196
public static GqlQuery.Builder<?> gqlQueryBuilder(String gql) {
@@ -191,6 +200,15 @@ public static GqlQuery.Builder<?> gqlQueryBuilder(String gql) {
191200
/**
192201
* Returns a new {@link GqlQuery} builder.
193202
*
203+
* <p>Example of creating and running a typed GQL query.
204+
* <pre> {@code
205+
* String kind = "my_kind";
206+
* String gqlQuery = "select * from " + kind;
207+
* Query<Entity> query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
208+
* QueryResults<Entity> results = datastore.run(query);
209+
* // Use results
210+
* }</pre>
211+
*
194212
* @see <a href="https://cloud.google.com/datastore/docs/apis/gql/gql_reference">GQL Reference</a>
195213
*/
196214
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,
199217

200218
/**
201219
* Returns a new {@link StructuredQuery} builder for full (complete entities) queries.
220+
*
221+
* <p>Example of creating and running an entity query.
222+
* <pre> {@code
223+
* String kind = "my_kind";
224+
* Query<Entity> query = Query.entityQueryBuilder().kind(kind).build();
225+
* QueryResults<Entity> results = datastore.run(query);
226+
* // Use results
227+
* }</pre>
228+
*
202229
*/
203230
public static EntityQuery.Builder entityQueryBuilder() {
204231
return new EntityQuery.Builder();
205232
}
206233

207234
/**
208235
* Returns a new {@link StructuredQuery} builder for key only queries.
236+
*
237+
* <p>Example of creating and running a key query.
238+
* <pre> {@code
239+
* String kind = "my_kind";
240+
* Query<Key> query = Query.keyQueryBuilder().kind(kind).build();
241+
* QueryResults<Key> results = datastore.run(query);
242+
* // Use results
243+
* }</pre>
244+
*
209245
*/
210246
public static KeyQuery.Builder keyQueryBuilder() {
211247
return new KeyQuery.Builder();
212248
}
213249

214250
/**
215251
* Returns a new {@link StructuredQuery} builder for projection queries.
252+
*
253+
* <p>Example of creating and running a projection entity query.
254+
* <pre> {@code
255+
* String kind = "my_kind";
256+
* String property = "my_property";
257+
* Query<ProjectionEntity> query = Query.projectionEntityQueryBuilder()
258+
* .kind(kind)
259+
* .addProjection(property)
260+
* .build();
261+
* QueryResults<ProjectionEntity> results = datastore.run(query);
262+
* // Use results
263+
* }</pre>
264+
*
216265
*/
217266
public static ProjectionEntityQuery.Builder projectionEntityQueryBuilder() {
218267
return new ProjectionEntityQuery.Builder();

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/*
18+
* EDITING INSTRUCTIONS
19+
* This file is referenced in Query's javadoc. Any change to this file should be reflected in
20+
* Query's javadoc.
21+
*/
22+
23+
package com.google.cloud.examples.datastore.snippets;
24+
25+
import com.google.cloud.datastore.Datastore;
26+
import com.google.cloud.datastore.Entity;
27+
import com.google.cloud.datastore.Key;
28+
import com.google.cloud.datastore.ProjectionEntity;
29+
import com.google.cloud.datastore.Query;
30+
import com.google.cloud.datastore.QueryResults;
31+
32+
/**
33+
* This class contains a number of snippets for the {@link Query} class.
34+
*/
35+
public class QuerySnippets {
36+
37+
private final Datastore datastore;
38+
39+
public QuerySnippets(Datastore datastore) {
40+
this.datastore = datastore;
41+
}
42+
43+
/**
44+
* Example of creating and running a GQL query.
45+
*/
46+
// [TARGET gqlQueryBuilder(String)]
47+
// [VARIABLE "my_kind"]
48+
public QueryResults<?> newQuery(String kind) {
49+
// [START newQuery]
50+
String gqlQuery = "select * from " + kind;
51+
Query<?> query = Query.gqlQueryBuilder(gqlQuery).build();
52+
QueryResults<?> results = datastore.run(query);
53+
// Use results
54+
// [END newQuery]
55+
return results;
56+
}
57+
58+
/**
59+
* Example of creating and running a typed GQL query.
60+
*/
61+
// [TARGET gqlQueryBuilder(ResultType, String)]
62+
// [VARIABLE "my_kind"]
63+
public QueryResults<Entity> newTypedQuery(String kind) {
64+
// [START newTypedQuery]
65+
String gqlQuery = "select * from " + kind;
66+
Query<Entity> query = Query.gqlQueryBuilder(Query.ResultType.ENTITY, gqlQuery).build();
67+
QueryResults<Entity> results = datastore.run(query);
68+
// Use results
69+
// [END newTypedQuery]
70+
return results;
71+
}
72+
73+
/**
74+
* Example of creating and running an entity query.
75+
*/
76+
// [TARGET entityQueryBuilder()]
77+
// [VARIABLE "my_kind"]
78+
public QueryResults<Entity> newEntityQuery(String kind) {
79+
// [START newEntityQuery]
80+
Query<Entity> query = Query.entityQueryBuilder().kind(kind).build();
81+
QueryResults<Entity> results = datastore.run(query);
82+
// Use results
83+
// [END newEntityQuery]
84+
return results;
85+
}
86+
87+
/**
88+
* Example of creating and running a key query.
89+
*/
90+
// [TARGET keyQueryBuilder()]
91+
// [VARIABLE "my_kind"]
92+
public QueryResults<Key> newKeyQuery(String kind) {
93+
// [START newKeyQuery]
94+
Query<Key> query = Query.keyQueryBuilder().kind(kind).build();
95+
QueryResults<Key> results = datastore.run(query);
96+
// Use results
97+
// [END newKeyQuery]
98+
return results;
99+
}
100+
101+
/**
102+
* Example of creating and running a projection entity query.
103+
*/
104+
// [TARGET projectionEntityQueryBuilder()]
105+
// [VARIABLE "my_kind"]
106+
// [VARIABLE "my_property"]
107+
public QueryResults<ProjectionEntity> newProjectionEntityQuery(String kind, String property) {
108+
// [START newProjectionEntityQuery]
109+
Query<ProjectionEntity> query = Query.projectionEntityQueryBuilder()
110+
.kind(kind)
111+
.addProjection(property)
112+
.build();
113+
QueryResults<ProjectionEntity> results = datastore.run(query);
114+
// Use results
115+
// [END newProjectionEntityQuery]
116+
return results;
117+
}
118+
}

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

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.examples.datastore.snippets;
18+
19+
import com.google.cloud.datastore.Datastore;
20+
import com.google.cloud.datastore.DatastoreOptions;
21+
import com.google.cloud.datastore.Entity;
22+
import com.google.cloud.datastore.Key;
23+
import com.google.cloud.datastore.ProjectionEntity;
24+
import com.google.cloud.datastore.QueryResults;
25+
import com.google.common.base.Function;
26+
import com.google.common.collect.Iterators;
27+
import com.google.common.collect.Sets;
28+
29+
import org.junit.AfterClass;
30+
import org.junit.BeforeClass;
31+
import org.junit.Rule;
32+
import org.junit.Test;
33+
import org.junit.rules.Timeout;
34+
35+
import java.util.Set;
36+
import java.util.UUID;
37+
38+
public class ITQuerySnippets {
39+
40+
private static Datastore datastore;
41+
private static Entity entity1;
42+
private static Entity entity2;
43+
private static final String KIND = "kind_" + UUID.randomUUID().toString().replace("-", "");
44+
private static final Function<ProjectionEntity, String> ENTITY_TO_DESCRIPTION_FUNCTION =
45+
new Function<ProjectionEntity, String>() {
46+
@Override
47+
public String apply(ProjectionEntity entity) {
48+
return entity.getString("description");
49+
}
50+
};
51+
52+
@Rule
53+
public Timeout globalTimeout = Timeout.seconds(60);
54+
55+
@BeforeClass
56+
public static void beforeClass() {
57+
datastore = DatastoreOptions.defaultInstance().service();
58+
Key key1 = Key.builder(datastore.options().projectId(), KIND, "key1").build();
59+
Key key2 = Key.builder(datastore.options().projectId(), KIND, "key2").build();
60+
entity1 = Entity.builder(key1).set("description", "entity1").build();
61+
entity2 = Entity.builder(key2).set("description", "entity2").build();
62+
datastore.put(entity1, entity2);
63+
}
64+
65+
@AfterClass
66+
public static void afterClass() {
67+
datastore.delete(entity1.key(), entity2.key());
68+
}
69+
70+
@Test
71+
public void testNewQuery() throws InterruptedException {
72+
QuerySnippets transactionSnippets = new QuerySnippets(datastore);
73+
QueryResults<?> results = transactionSnippets.newQuery(KIND);
74+
Set<?> resultSet = Sets.newHashSet(results);
75+
while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
76+
Thread.sleep(500);
77+
resultSet = Sets.newHashSet(results);
78+
}
79+
}
80+
81+
@Test
82+
public void testNewTypedQuery() throws InterruptedException {
83+
QuerySnippets transactionSnippets = new QuerySnippets(datastore);
84+
QueryResults<Entity> results = transactionSnippets.newTypedQuery(KIND);
85+
Set<Entity> resultSet = Sets.newHashSet(results);
86+
while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
87+
Thread.sleep(500);
88+
resultSet = Sets.newHashSet(results);
89+
}
90+
}
91+
92+
@Test
93+
public void testNewEntityQuery() throws InterruptedException {
94+
QuerySnippets transactionSnippets = new QuerySnippets(datastore);
95+
QueryResults<Entity> results = transactionSnippets.newEntityQuery(KIND);
96+
Set<Entity> resultSet = Sets.newHashSet(results);
97+
while (!resultSet.contains(entity1) || !resultSet.contains(entity2)) {
98+
Thread.sleep(500);
99+
resultSet = Sets.newHashSet(results);
100+
}
101+
}
102+
103+
@Test
104+
public void testNewKeyQuery() throws InterruptedException {
105+
QuerySnippets transactionSnippets = new QuerySnippets(datastore);
106+
QueryResults<Key> results = transactionSnippets.newKeyQuery(KIND);
107+
Set<Key> resultSet = Sets.newHashSet(results);
108+
while (!resultSet.contains(entity1.key()) || !resultSet.contains(entity2.key())) {
109+
Thread.sleep(500);
110+
resultSet = Sets.newHashSet(results);
111+
}
112+
}
113+
114+
@Test
115+
public void testNewProjectionEntityQuery() throws InterruptedException {
116+
QuerySnippets transactionSnippets = new QuerySnippets(datastore);
117+
QueryResults<ProjectionEntity> results =
118+
transactionSnippets.newProjectionEntityQuery(KIND, "description");
119+
Set<String> resultSet =
120+
Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
121+
while (!resultSet.contains(entity1.getString("description"))
122+
|| !resultSet.contains(entity2.getString("description"))) {
123+
Thread.sleep(500);
124+
resultSet = Sets.newHashSet(Iterators.transform(results, ENTITY_TO_DESCRIPTION_FUNCTION));
125+
}
126+
}
127+
}

0 commit comments

Comments
 (0)