Skip to content

Commit 08885df

Browse files
mziccardmziccard
committed
Minor consistency fixes to Datastore snippets, update javadoc
1 parent c8931c0 commit 08885df

File tree

3 files changed

+240
-66
lines changed

3 files changed

+240
-66
lines changed

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

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,40 @@ interface TransactionCallable<T> {
5252
* Any thrown exception will cause the transaction to rollback and will be propagated
5353
* as a {@link DatastoreException} with the original exception as its root cause.
5454
*
55+
* <p>Example of running in a transaction.
56+
* <pre> {@code
57+
* String callableResult = "my_callable_result";
58+
* TransactionCallable<String> callable = new TransactionCallable<String>() {
59+
* public String run(DatastoreReaderWriter readerWriter) {
60+
* // use readerWriter to run in transaction
61+
* return callableResult;
62+
* }
63+
* };
64+
* String result = datastore.runInTransaction(callable);
65+
* }</pre>
66+
*
5567
* @param callable the callback to call with a newly created transactional readerWriter
5668
* @throws DatastoreException upon failure
5769
*/
5870
<T> T runInTransaction(TransactionCallable<T> callable);
5971

6072
/**
6173
* Returns a new Batch for processing multiple write operations in one request.
74+
*
75+
* <p>Example of starting a new batch.
76+
* <pre> {@code
77+
* String keyName1 = "my_key_name_1";
78+
* String keyName2 = "my_key_name_2";
79+
* Key key1 = datastore.newKeyFactory().kind("MyKind").newKey(keyName1);
80+
* Key key2 = datastore.newKeyFactory().kind("MyKind").newKey(keyName2);
81+
* Batch batch = datastore.newBatch();
82+
* Entity entity1 = Entity.builder(key1).set("name", "John").build();
83+
* Entity entity2 = Entity.builder(key2).set("title", "title").build();
84+
* batch.add(entity1);
85+
* batch.add(entity2);
86+
* batch.submit();
87+
* }</pre>
88+
*
6289
*/
6390
Batch newBatch();
6491

@@ -67,55 +94,145 @@ interface TransactionCallable<T> {
6794
* The returned key will have the same information (projectId, kind, namespace and ancestors)
6895
* as the given key and will have a newly assigned id.
6996
*
97+
* <p>Example of allocating an id.
98+
* <pre> {@code
99+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
100+
* IncompleteKey incompleteKey = keyFactory.newKey();
101+
*
102+
* // let cloud datastore automatically assign an id
103+
* Key key = datastore.allocateId(incompleteKey);
104+
* }</pre>
105+
*
70106
* @throws DatastoreException upon failure
71107
*/
72108
Key allocateId(IncompleteKey key);
73109

74110
/**
75111
* Returns a list of keys using the allocated ids ordered by the input.
76112
*
113+
* <p>Example of allocating multiple ids in a single batch.
114+
* <pre> {@code
115+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
116+
* IncompleteKey incompleteKey1 = keyFactory.newKey();
117+
* IncompleteKey incompleteKey2 = keyFactory.newKey();
118+
*
119+
* // let cloud datastore automatically assign the ids
120+
* List<Key> keys = datastore.allocateId(incompleteKey1, incompleteKey2);
121+
* }</pre>
122+
*
77123
* @throws DatastoreException upon failure
78124
* @see #allocateId(IncompleteKey)
79125
*/
80126
List<Key> allocateId(IncompleteKey... keys);
81127

82128
/**
83129
* {@inheritDoc}
130+
*
131+
* <p>Example of updating multiple entities.
132+
* <pre> {@code
133+
* String keyName1 = "my_key_name_1";
134+
* String keyName2 = "my_key_name_2";
135+
* Key key1 = datastore.newKeyFactory().kind("MyKind").newKey(keyName1);
136+
* Entity.Builder entityBuilder1 = Entity.builder(key1);
137+
* entityBuilder1.set("propertyName", "updatedValue1");
138+
* Entity entity1 = entityBuilder1.build();
139+
*
140+
* Key key2 = datastore.newKeyFactory().kind("MyKind").newKey(keyName2);
141+
* Entity.Builder entityBuilder2 = Entity.builder(key2);
142+
* entityBuilder2.set("propertyName", "updatedValue2");
143+
* Entity entity2 = entityBuilder2.build();
144+
*
145+
* datastore.update(entity1, entity2);
146+
* }</pre>
147+
*
84148
* @throws DatastoreException upon failure
85149
*/
86150
@Override
87151
void update(Entity... entities);
88152

89153
/**
90154
* {@inheritDoc}
155+
*
156+
* <p>Example of putting a single entity.
157+
* <pre> {@code
158+
* String keyName = "my_key_name";
159+
* Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
160+
* Entity.Builder entityBuilder = Entity.builder(key);
161+
* entityBuilder.set("propertyName", "value");
162+
* Entity entity = entityBuilder.build();
163+
* datastore.put(entity);
164+
* }</pre>
165+
*
91166
* @throws DatastoreException upon failure
92167
*/
93168
@Override
94169
Entity put(FullEntity<?> entity);
95170

96171
/**
97172
* {@inheritDoc}
173+
*
174+
* <p>Example of putting multiple entities.
175+
* <pre> {@code
176+
* String keyName1 = "my_key_name1";
177+
* String keyName2 = "my_key_name2";
178+
* Key key1 = datastore.newKeyFactory().kind("MyKind").newKey(keyName1);
179+
* Entity.Builder entityBuilder1 = Entity.builder(key1);
180+
* entityBuilder1.set("propertyName", "value1");
181+
* Entity entity1 = entityBuilder1.build();
182+
*
183+
* Key key2 = datastore.newKeyFactory().kind("MyKind").newKey(keyName2);
184+
* Entity.Builder entityBuilder2 = Entity.builder(key2);
185+
* entityBuilder2.set("propertyName", "value2");
186+
* Entity entity2 = entityBuilder2.build();
187+
*
188+
* datastore.put(entity1, entity2);
189+
* }</pre>
190+
*
98191
* @throws DatastoreException upon failure
99192
*/
100193
@Override
101194
List<Entity> put(FullEntity<?>... entities);
102195

103196
/**
104197
* {@inheritDoc}
198+
*
199+
* <p>Example of deleting multiple entities.
200+
* <pre> {@code
201+
* String keyName1 = "my_key_name1";
202+
* String keyName2 = "my_key_name2";
203+
* Key key1 = datastore.newKeyFactory().kind("MyKind").newKey(keyName1);
204+
* Key key2 = datastore.newKeyFactory().kind("MyKind").newKey(keyName2);
205+
* datastore.delete(key1, key2);
206+
* }</pre>
207+
*
105208
* @throws DatastoreException upon failure
106209
*/
107210
@Override
108211
void delete(Key... keys);
109212

110213
/**
111214
* Returns a new KeyFactory for this service
215+
*
216+
* <p>Example of creating a {@code KeyFactory}.
217+
* <pre> {@code
218+
* KeyFactory keyFactory = datastore.newKeyFactory();
219+
* }</pre>
220+
*
112221
*/
113222
KeyFactory newKeyFactory();
114223

115224
/**
116225
* Returns an {@link Entity} for the given {@link Key} or {@code null} if it doesn't exist.
117226
* {@link ReadOption}s can be specified if desired.
118227
*
228+
* <p>Example of getting an entity.
229+
* <pre> {@code
230+
* String keyName = "my_key_name";
231+
* Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
232+
* Entity entity = datastore.get(key);
233+
* // Do something with the entity
234+
* }</pre>
235+
*
119236
* @throws DatastoreException upon failure
120237
*/
121238
Entity get(Key key, ReadOption... options);
@@ -127,6 +244,22 @@ interface TransactionCallable<T> {
127244
* {@link Iterator#hasNext hasNext} or {@link Iterator#next next} methods. {@link ReadOption}s can
128245
* be specified if desired.
129246
*
247+
* <p>Example of getting multiple entity objects.
248+
* <pre> {@code
249+
* String firstKeyName = "my_first_key_name";
250+
* String secondKeyName = "my_second_key_name";
251+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
252+
* Key firstKey = keyFactory.newKey(firstKeyName);
253+
* Key secondKey = keyFactory.newKey(secondKeyName);
254+
* Iterator<Entity> entitiesIterator = datastore.get(Lists.newArrayList(firstKey, secondKey));
255+
* List<Entity> entities = Lists.newArrayList();
256+
* while (entitiesIterator.hasNext()) {
257+
* Entity entity = entitiesIterator.next();
258+
* // do something with the entity
259+
* entities.add(entity);
260+
* }
261+
* }</pre>
262+
*
130263
* @throws DatastoreException upon failure
131264
* @see #get(Key)
132265
*/
@@ -136,13 +269,60 @@ interface TransactionCallable<T> {
136269
* Returns a list with a value for each given key (ordered by input). {@code null} values are
137270
* returned for nonexistent keys. When possible prefer using {@link #get(Key...)} to avoid eagerly
138271
* loading the results. {@link ReadOption}s can be specified if desired.
272+
*
273+
* <p>Example of fetching a list of Entity objects.
274+
* <pre> {@code
275+
* String firstKeyName = "my_first_key_name";
276+
* String secondKeyName = "my_second_key_name";
277+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
278+
* Key firstKey = keyFactory.newKey(firstKeyName);
279+
* Key secondKey = keyFactory.newKey(secondKeyName);
280+
* List<Entity> entities = datastore.fetch(Lists.newArrayList(firstKey, secondKey));
281+
* for (Entity entity : entities) {
282+
* // do something with the entity
283+
* }
284+
* }</pre>
285+
*
139286
*/
140287
List<Entity> fetch(Iterable<Key> keys, ReadOption... options);
141288

142289
/**
143290
* Submits a {@link Query} and returns its result. {@link ReadOption}s can be specified if
144291
* desired.
145292
*
293+
* <p>Example of running a query to find all entities of one kind.
294+
* <pre> {@code
295+
* String kind = "my_kind";
296+
* StructuredQuery<Entity> query = Query.entityQueryBuilder()
297+
* .kind(kind)
298+
* .build();
299+
* QueryResults<Entity> results = datastore.run(query);
300+
* List<Entity> entities = Lists.newArrayList();
301+
* while (results.hasNext()) {
302+
* Entity result = results.next();
303+
* // do something with result
304+
* entities.add(result);
305+
* }
306+
* }</pre>
307+
*
308+
* <p>Example of running a query to find all entities with a matching property value.
309+
* <pre> {@code
310+
* String kind = "my_kind";
311+
* String property = "my_property";
312+
* String value = "my_value";
313+
* StructuredQuery<Entity> query = Query.entityQueryBuilder()
314+
* .kind(kind)
315+
* .filter(PropertyFilter.eq(property, value))
316+
* .build();
317+
* QueryResults<Entity> results = datastore.run(query);
318+
* List<Entity> entities = Lists.newArrayList();
319+
* while (results.hasNext()) {
320+
* Entity result = results.next();
321+
* // do something with result
322+
* entities.add(result);
323+
* }
324+
* }</pre>
325+
*
146326
* @throws DatastoreException upon failure
147327
*/
148328
<T> QueryResults<T> run(Query<T> query, ReadOption... options);

0 commit comments

Comments
 (0)