Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing snippets to Datastore Transaction, add snippets to Transaction javadoc #1270

Merged
merged 6 commits into from
Sep 20, 2016
Merged

Add missing snippets to Datastore Transaction, add snippets to Transaction javadoc #1270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
730ba75
Add snippets and test for transaction.get()
vchudnov-g Sep 16, 2016
bd9b8b1
Add snippets and test for transaction.fetch()
vchudnov-g Sep 16, 2016
1b78e23
Add snippets and test for transaction.run()
vchudnov-g Sep 17, 2016
8e9e142
Comsetic changes.
vchudnov-g Sep 17, 2016
b3971bf
Minor consistency fixes to Transaction snippets
mziccard Sep 20, 2016
2303882
Add Transaction snippets to Transaction javadoc
mziccard Sep 20, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 64 additions & 3 deletions google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java
View file
Open in desktop
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
Open in desktop
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