Skip to content

Commit

Permalink
Add missing snippets to Datastore Transaction, add snippets to Transa…
Browse files Browse the repository at this point in the history 
…ction javadoc (#1270)
  • Loading branch information
@mziccard
mziccard authored Sep 20, 2016
1 parent ee24968 commit 4fe00dd
Show file tree
Hide file tree
Showing 3 changed files with 268 additions and 6 deletions.
67 changes: 64 additions & 3 deletions google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,15 @@ interface Response {
* to fail if entity was changed by others after it was seen by this transaction) but any
* write changes in this transaction will not be reflected by the returned entity.
*
* <p>Example of getting an entity for a given key.
* <pre> {@code
* String keyName = "my_key_name";
* Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
* Entity entity = transaction.get(key);
* transaction.commit();
* // Do something with the entity
* }</pre>
*
* @throws DatastoreException upon failure or if no longer active
*/
@Override
Expand All @@ -74,6 +83,23 @@ interface Response {
* to fail if any of the entities was changed by others after they were seen by this transaction)
* but any write changes in this transaction will not be reflected by the returned entities.
*
* <p>Example of getting entities for several keys.
* <pre> {@code
* String firstKeyName = "my_first_key_name";
* String secondKeyName = "my_second_key_name";
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
* Key firstKey = keyFactory.newKey(firstKeyName);
* Key secondKey = keyFactory.newKey(secondKeyName);
* Iterator<Entity> entitiesIterator = transaction.get(firstKey, secondKey);
* List<Entity> entities = Lists.newArrayList();
* while (entitiesIterator.hasNext()) {
* Entity entity = entitiesIterator.next();
* // do something with the entity
* entities.add(entity);
* }
* transaction.commit();
* }</pre>
*
* @throws DatastoreException upon failure or if no longer active
*/
@Override
Expand All @@ -85,6 +111,20 @@ interface Response {
* to fail if any of the entities was changed by others after they were seen by this transaction)
* but any write changes in this transaction will not be reflected by the returned entities.
*
* <p>Example of fetching a list of entities for several keys.
* <pre> {@code
* String firstKeyName = "my_first_key_name";
* String secondKeyName = "my_second_key_name";
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
* Key firstKey = keyFactory.newKey(firstKeyName);
* Key secondKey = keyFactory.newKey(secondKeyName);
* List<Entity> entities = transaction.fetch(firstKey, secondKey);
* for (Entity entity : entities) {
* // do something with the entity
* }
* transaction.commit();
* }</pre>
*
* @throws DatastoreException upon failure or if no longer active
*/
@Override
Expand All @@ -97,6 +137,26 @@ interface Response {
* query was performed) but any write changes in this transaction will not be reflected by
* the result.
*
* <p>Example of running a query to find all entities with an ancestor.
* <pre> {@code
* String parentKeyName = "my_parent_key_name";
* KeyFactory keyFactory = datastore.newKeyFactory().kind("ParentKind");
* Key parentKey = keyFactory.newKey(parentKeyName);
* // Build a query
* Query<Entity> query = Query.entityQueryBuilder()
* .kind("MyKind")
* .filter(PropertyFilter.hasAncestor(parentKey))
* .build();
* QueryResults<Entity> results = transaction.run(query);
* List<Entity> entities = Lists.newArrayList();
* while (results.hasNext()) {
* Entity result = results.next();
* // do something with result
* entities.add(result);
* }
* transaction.commit();
* }</pre>
*
* @throws DatastoreException upon failure or if no longer active
*/
@Override
Expand All @@ -108,9 +168,10 @@ interface Response {
* <p>Example of committing a transaction.
* <pre> {@code
* // create an entity
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
* Key key = datastore.allocateId(keyFactory.newKey());
* Entity entity = Entity.builder(key).set("description", "commit()").build();
*
* // add the entity and commit
* try {
* transaction.put(entity);
Expand All @@ -130,7 +191,7 @@ interface Response {
* <p>Example of rolling back a transaction.
* <pre> {@code
* // create an entity
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
* Key key = datastore.allocateId(keyFactory.newKey());
* Entity entity = Entity.builder(key).set("description", "rollback()").build();
*
Expand All @@ -150,7 +211,7 @@ interface Response {
* <p>Example of verifying if a transaction is active.
* <pre> {@code
* // create an entity
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
* KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
* Key key = datastore.allocateId(keyFactory.newKey());
* Entity entity = Entity.builder(key).set("description", "active()").build();
* // calling transaction.active() now would return true
Expand Down
104 changes: 101 additions & 3 deletions ...mples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,20 @@

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

import com.google.api.client.util.Lists;
import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreException;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Key;
import com.google.cloud.datastore.KeyFactory;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
import com.google.cloud.datastore.Transaction;

import java.util.Iterator;
import java.util.List;

/**
* This class contains a number of snippets for the {@link Transaction} interface.
*/
Expand All @@ -40,6 +47,95 @@ public TransactionSnippets(Transaction transaction) {
this.transaction = transaction;
}

/**
* Example of getting an entity for a given key.
*/
// [TARGET get(Key)]
// [VARIABLE "my_key_name"]
public Entity get(String keyName) {
Datastore datastore = transaction.datastore();
// [START get]
Key key = datastore.newKeyFactory().kind("MyKind").newKey(keyName);
Entity entity = transaction.get(key);
transaction.commit();
// Do something with the entity
// [END get]
return entity;
}

/**
* Example of getting entities for several keys.
*/
// [TARGET get(Key...)]
// [VARIABLE "my_first_key_name"]
// [VARIABLE "my_second_key_name"]
public List<Entity> getMultiple(String firstKeyName, String secondKeyName) {
Datastore datastore = transaction.datastore();
// TODO change so that it's not necessary to hold the entities in a list for integration testing
// [START getMultiple]
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
Key firstKey = keyFactory.newKey(firstKeyName);
Key secondKey = keyFactory.newKey(secondKeyName);
Iterator<Entity> entitiesIterator = transaction.get(firstKey, secondKey);
List<Entity> entities = Lists.newArrayList();
while (entitiesIterator.hasNext()) {
Entity entity = entitiesIterator.next();
// do something with the entity
entities.add(entity);
}
transaction.commit();
// [END getMultiple]
return entities;
}

/**
* Example of fetching a list of entities for several keys.
*/
// [TARGET fetch(Key...)]
// [VARIABLE "my_first_key_name"]
// [VARIABLE "my_second_key_name"]
public List<Entity> fetchEntitiesWithKeys(String firstKeyName, String secondKeyName) {
Datastore datastore = transaction.datastore();
// [START fetchEntitiesWithKeys]
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
Key firstKey = keyFactory.newKey(firstKeyName);
Key secondKey = keyFactory.newKey(secondKeyName);
List<Entity> entities = transaction.fetch(firstKey, secondKey);
for (Entity entity : entities) {
// do something with the entity
}
transaction.commit();
// [END fetchEntitiesWithKeys]
return entities;
}

/**
* Example of running a query to find all entities with an ancestor.
*/
// [TARGET run(Query)]
// [VARIABLE "my_parent_key_name"]
public List<Entity> run(String parentKeyName) {
Datastore datastore = transaction.datastore();
// [START run]
KeyFactory keyFactory = datastore.newKeyFactory().kind("ParentKind");
Key parentKey = keyFactory.newKey(parentKeyName);
// Build a query
Query<Entity> query = Query.entityQueryBuilder()
.kind("MyKind")
.filter(PropertyFilter.hasAncestor(parentKey))
.build();
QueryResults<Entity> results = transaction.run(query);
List<Entity> entities = Lists.newArrayList();
while (results.hasNext()) {
Entity result = results.next();
// do something with result
entities.add(result);
}
transaction.commit();
// [END run]
return entities;
}

/**
* Example of committing a transaction.
*/
Expand All @@ -48,9 +144,10 @@ public Key commit() {
Datastore datastore = transaction.datastore();
// [START commit]
// create an entity
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
Key key = datastore.allocateId(keyFactory.newKey());
Entity entity = Entity.builder(key).set("description", "commit()").build();

// add the entity and commit
try {
transaction.put(entity);
Expand All @@ -59,6 +156,7 @@ public Key commit() {
// handle exception
}
// [END commit]

return key;
}

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

Expand All @@ -90,7 +188,7 @@ public Key active() {
Datastore datastore = transaction.datastore();
// [START active]
// create an entity
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
KeyFactory keyFactory = datastore.newKeyFactory().kind("MyKind");
Key key = datastore.allocateId(keyFactory.newKey());
Entity entity = Entity.builder(key).set("description", "active()").build();
// calling transaction.active() now would return true
Expand Down
Loading

0 comments on commit 4fe00dd

Please sign in to comment.