Skip to content

Commit 4fe00dd

Browse files
mziccardmziccard
authored
Add missing snippets to Datastore Transaction, add snippets to Transaction javadoc (#1270)
1 parent ee24968 commit 4fe00dd

File tree

3 files changed

+268
-6
lines changed

3 files changed

+268
-6
lines changed

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

+64-3
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,15 @@ interface Response {
6363
* to fail if entity was changed by others after it was seen by this transaction) but any
6464
* write changes in this transaction will not be reflected by the returned entity.
6565
*
66+
* <p>Example of getting an entity for a given key.
67+
* <pre> {@code
68+
* String keyName = "my_key_name";
69+
* Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
70+
* Entity entity = transaction.get(key);
71+
* transaction.commit();
72+
* // Do something with the entity
73+
* }</pre>
74+
*
6675
* @throws DatastoreException upon failure or if no longer active
6776
*/
6877
@Override
@@ -74,6 +83,23 @@ interface Response {
7483
* to fail if any of the entities was changed by others after they were seen by this transaction)
7584
* but any write changes in this transaction will not be reflected by the returned entities.
7685
*
86+
* <p>Example of getting entities for several keys.
87+
* <pre> {@code
88+
* String firstKeyName = "my_first_key_name";
89+
* String secondKeyName = "my_second_key_name";
90+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
91+
* Key firstKey = keyFactory.newKey(firstKeyName);
92+
* Key secondKey = keyFactory.newKey(secondKeyName);
93+
* Iterator<Entity> entitiesIterator = transaction.get(firstKey, secondKey);
94+
* List<Entity> entities = Lists.newArrayList();
95+
* while (entitiesIterator.hasNext()) {
96+
* Entity entity = entitiesIterator.next();
97+
* // do something with the entity
98+
* entities.add(entity);
99+
* }
100+
* transaction.commit();
101+
* }</pre>
102+
*
77103
* @throws DatastoreException upon failure or if no longer active
78104
*/
79105
@Override
@@ -85,6 +111,20 @@ interface Response {
85111
* to fail if any of the entities was changed by others after they were seen by this transaction)
86112
* but any write changes in this transaction will not be reflected by the returned entities.
87113
*
114+
* <p>Example of fetching a list of entities for several keys.
115+
* <pre> {@code
116+
* String firstKeyName = "my_first_key_name";
117+
* String secondKeyName = "my_second_key_name";
118+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
119+
* Key firstKey = keyFactory.newKey(firstKeyName);
120+
* Key secondKey = keyFactory.newKey(secondKeyName);
121+
* List<Entity> entities = transaction.fetch(firstKey, secondKey);
122+
* for (Entity entity : entities) {
123+
* // do something with the entity
124+
* }
125+
* transaction.commit();
126+
* }</pre>
127+
*
88128
* @throws DatastoreException upon failure or if no longer active
89129
*/
90130
@Override
@@ -97,6 +137,26 @@ interface Response {
97137
* query was performed) but any write changes in this transaction will not be reflected by
98138
* the result.
99139
*
140+
* <p>Example of running a query to find all entities with an ancestor.
141+
* <pre> {@code
142+
* String parentKeyName = "my_parent_key_name";
143+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("ParentKind");
144+
* Key parentKey = keyFactory.newKey(parentKeyName);
145+
* // Build a query
146+
* Query<Entity> query = Query.entityQueryBuilder()
147+
* .kind("MyKind")
148+
* .filter(PropertyFilter.hasAncestor(parentKey))
149+
* .build();
150+
* QueryResults<Entity> results = transaction.run(query);
151+
* List<Entity> entities = Lists.newArrayList();
152+
* while (results.hasNext()) {
153+
* Entity result = results.next();
154+
* // do something with result
155+
* entities.add(result);
156+
* }
157+
* transaction.commit();
158+
* }</pre>
159+
*
100160
* @throws DatastoreException upon failure or if no longer active
101161
*/
102162
@Override
@@ -108,9 +168,10 @@ interface Response {
108168
* <p>Example of committing a transaction.
109169
* <pre> {@code
110170
* // create an entity
111-
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
171+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
112172
* Key key = datastore.allocateId(keyFactory.newKey());
113173
* Entity entity = Entity.builder(key).set("description", "commit()").build();
174+
*
114175
* // add the entity and commit
115176
* try {
116177
* transaction.put(entity);
@@ -130,7 +191,7 @@ interface Response {
130191
* <p>Example of rolling back a transaction.
131192
* <pre> {@code
132193
* // create an entity
133-
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
194+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
134195
* Key key = datastore.allocateId(keyFactory.newKey());
135196
* Entity entity = Entity.builder(key).set("description", "rollback()").build();
136197
*
@@ -150,7 +211,7 @@ interface Response {
150211
* <p>Example of verifying if a transaction is active.
151212
* <pre> {@code
152213
* // create an entity
153-
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
214+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
154215
* Key key = datastore.allocateId(keyFactory.newKey());
155216
* Entity entity = Entity.builder(key).set("description", "active()").build();
156217
* // calling transaction.active() now would return true

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

+101-3
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,20 @@
2222

2323
package com.google.cloud.examples.datastore.snippets;
2424

25+
import com.google.api.client.util.Lists;
2526
import com.google.cloud.datastore.Datastore;
2627
import com.google.cloud.datastore.DatastoreException;
2728
import com.google.cloud.datastore.Entity;
2829
import com.google.cloud.datastore.Key;
2930
import com.google.cloud.datastore.KeyFactory;
31+
import com.google.cloud.datastore.Query;
32+
import com.google.cloud.datastore.QueryResults;
33+
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
3034
import com.google.cloud.datastore.Transaction;
3135

36+
import java.util.Iterator;
37+
import java.util.List;
38+
3239
/**
3340
* This class contains a number of snippets for the {@link Transaction} interface.
3441
*/
@@ -40,6 +47,95 @@ public TransactionSnippets(Transaction transaction) {
4047
this.transaction = transaction;
4148
}
4249

50+
/**
51+
* Example of getting an entity for a given key.
52+
*/
53+
// [TARGET get(Key)]
54+
// [VARIABLE "my_key_name"]
55+
public Entity get(String keyName) {
56+
Datastore datastore = transaction.datastore();
57+
// [START get]
58+
Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
59+
Entity entity = transaction.get(key);
60+
transaction.commit();
61+
// Do something with the entity
62+
// [END get]
63+
return entity;
64+
}
65+
66+
/**
67+
* Example of getting entities for several keys.
68+
*/
69+
// [TARGET get(Key...)]
70+
// [VARIABLE "my_first_key_name"]
71+
// [VARIABLE "my_second_key_name"]
72+
public List<Entity> getMultiple(String firstKeyName, String secondKeyName) {
73+
Datastore datastore = transaction.datastore();
74+
// TODO change so that it's not necessary to hold the entities in a list for integration testing
75+
// [START getMultiple]
76+
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
77+
Key firstKey = keyFactory.newKey(firstKeyName);
78+
Key secondKey = keyFactory.newKey(secondKeyName);
79+
Iterator<Entity> entitiesIterator = transaction.get(firstKey, secondKey);
80+
List<Entity> entities = Lists.newArrayList();
81+
while (entitiesIterator.hasNext()) {
82+
Entity entity = entitiesIterator.next();
83+
// do something with the entity
84+
entities.add(entity);
85+
}
86+
transaction.commit();
87+
// [END getMultiple]
88+
return entities;
89+
}
90+
91+
/**
92+
* Example of fetching a list of entities for several keys.
93+
*/
94+
// [TARGET fetch(Key...)]
95+
// [VARIABLE "my_first_key_name"]
96+
// [VARIABLE "my_second_key_name"]
97+
public List<Entity> fetchEntitiesWithKeys(String firstKeyName, String secondKeyName) {
98+
Datastore datastore = transaction.datastore();
99+
// [START fetchEntitiesWithKeys]
100+
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
101+
Key firstKey = keyFactory.newKey(firstKeyName);
102+
Key secondKey = keyFactory.newKey(secondKeyName);
103+
List<Entity> entities = transaction.fetch(firstKey, secondKey);
104+
for (Entity entity : entities) {
105+
// do something with the entity
106+
}
107+
transaction.commit();
108+
// [END fetchEntitiesWithKeys]
109+
return entities;
110+
}
111+
112+
/**
113+
* Example of running a query to find all entities with an ancestor.
114+
*/
115+
// [TARGET run(Query)]
116+
// [VARIABLE "my_parent_key_name"]
117+
public List<Entity> run(String parentKeyName) {
118+
Datastore datastore = transaction.datastore();
119+
// [START run]
120+
KeyFactory keyFactory = datastore.newKeyFactory().kind("ParentKind");
121+
Key parentKey = keyFactory.newKey(parentKeyName);
122+
// Build a query
123+
Query<Entity> query = Query.entityQueryBuilder()
124+
.kind("MyKind")
125+
.filter(PropertyFilter.hasAncestor(parentKey))
126+
.build();
127+
QueryResults<Entity> results = transaction.run(query);
128+
List<Entity> entities = Lists.newArrayList();
129+
while (results.hasNext()) {
130+
Entity result = results.next();
131+
// do something with result
132+
entities.add(result);
133+
}
134+
transaction.commit();
135+
// [END run]
136+
return entities;
137+
}
138+
43139
/**
44140
* Example of committing a transaction.
45141
*/
@@ -48,9 +144,10 @@ public Key commit() {
48144
Datastore datastore = transaction.datastore();
49145
// [START commit]
50146
// create an entity
51-
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
147+
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
52148
Key key = datastore.allocateId(keyFactory.newKey());
53149
Entity entity = Entity.builder(key).set("description", "commit()").build();
150+
54151
// add the entity and commit
55152
try {
56153
transaction.put(entity);
@@ -59,6 +156,7 @@ public Key commit() {
59156
// handle exception
60157
}
61158
// [END commit]
159+
62160
return key;
63161
}
64162

@@ -70,7 +168,7 @@ public Key rollback() {
70168
Datastore datastore = transaction.datastore();
71169
// [START rollback]
72170
// create an entity
73-
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
171+
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
74172
Key key = datastore.allocateId(keyFactory.newKey());
75173
Entity entity = Entity.builder(key).set("description", "rollback()").build();
76174

@@ -90,7 +188,7 @@ public Key active() {
90188
Datastore datastore = transaction.datastore();
91189
// [START active]
92190
// create an entity
93-
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
191+
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
94192
Key key = datastore.allocateId(keyFactory.newKey());
95193
Entity entity = Entity.builder(key).set("description", "active()").build();
96194
// calling transaction.active() now would return true

0 commit comments

Comments
 (0)