Example of committing a transaction. + *
{@code
+ * // create an entity
+ * KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ * Key key = datastore.allocateId(keyFactory.newKey());
+ * Entity entity = Entity.builder(key).set("description", "commit()").build();
+ * // add the entity and commit
+ * try {
+ * transaction.put(entity);
+ * transaction.commit();
+ * } catch (DatastoreException ex) {
+ * // handle exception
+ * }
+ * }
+ *
* @throws DatastoreException if could not commit the transaction or if no longer active
*/
Response commit();
@@ -112,12 +127,47 @@ interface Response {
/**
* Rollback the transaction.
*
+ * Example of rolling back a transaction. + *
{@code
+ * // create an entity
+ * KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ * Key key = datastore.allocateId(keyFactory.newKey());
+ * Entity entity = Entity.builder(key).set("description", "rollback()").build();
+ *
+ * // add the entity and rollback
+ * transaction.put(entity);
+ * transaction.rollback();
+ * // calling transaction.commit() now would fail
+ * }
+ *
* @throws DatastoreException if transaction was already committed
*/
void rollback();
/**
* Returns {@code true} if the transaction is still active (was not committed or rolledback).
+ *
+ * Example of verifying if a transaction is active. + *
{@code
+ * // create an entity
+ * KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ * Key key = datastore.allocateId(keyFactory.newKey());
+ * Entity entity = Entity.builder(key).set("description", "active()").build();
+ * // calling transaction.active() now would return true
+ * try {
+ * // add the entity and commit
+ * transaction.put(entity);
+ * transaction.commit();
+ * } finally {
+ * // if committing succeeded
+ * // then transaction.active() will be false
+ * if (transaction.active()) {
+ * // otherwise it's true and we need to rollback
+ * transaction.rollback();
+ * }
+ * }
+ * }
+ *
*/
@Override
boolean active();
diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java
new file mode 100644
index 000000000000..e81911992ac2
--- /dev/null
+++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java
@@ -0,0 +1,112 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Transaction's javadoc. Any change to this file should be reflected in
+ * Transaction's javadoc.
+ */
+
+package com.google.cloud.examples.datastore.snippets;
+
+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.Transaction;
+
+/**
+ * This class contains a number of snippets for the {@link Transaction} interface.
+ */
+public class TransactionSnippets {
+
+ private final Transaction transaction;
+
+ public TransactionSnippets(Transaction transaction) {
+ this.transaction = transaction;
+ }
+
+ /**
+ * Example of committing a transaction.
+ */
+ // [TARGET commit()]
+ public Key commit() {
+ Datastore datastore = transaction.datastore();
+ // [START commit]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "commit()").build();
+ // add the entity and commit
+ try {
+ transaction.put(entity);
+ transaction.commit();
+ } catch (DatastoreException ex) {
+ // handle exception
+ }
+ // [END commit]
+ return key;
+ }
+
+ /**
+ * Example of rolling back a transaction.
+ */
+ // [TARGET rollback()]
+ public Key rollback() {
+ Datastore datastore = transaction.datastore();
+ // [START rollback]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "rollback()").build();
+
+ // add the entity and rollback
+ transaction.put(entity);
+ transaction.rollback();
+ // calling transaction.commit() now would fail
+ // [END rollback]
+ return key;
+ }
+
+ /**
+ * Example of verifying if a transaction is active.
+ */
+ // [TARGET active()]
+ public Key active() {
+ Datastore datastore = transaction.datastore();
+ // [START active]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "active()").build();
+ // calling transaction.active() now would return true
+ try {
+ // add the entity and commit
+ transaction.put(entity);
+ transaction.commit();
+ } finally {
+ // if committing succeeded
+ // then transaction.active() will be false
+ if (transaction.active()) {
+ // otherwise it's true and we need to rollback
+ transaction.rollback();
+ }
+ }
+ // [END active]
+ return key;
+ }
+}
diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java
new file mode 100644
index 000000000000..dab72d63857f
--- /dev/null
+++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java
@@ -0,0 +1,68 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.examples.datastore.snippets;
+
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.Transaction;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class ITTransactionSnippets {
+
+ private static Datastore datastore;
+
+ @BeforeClass
+ public static void beforeClass() {
+ datastore = DatastoreOptions.defaultInstance().service();
+ }
+
+ @Test
+ public void testCommit() {
+ Transaction transaction = datastore.newTransaction();
+ TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
+ Key key = transactionSnippets.commit();
+ Entity result = datastore.get(key);
+ assertNotNull(result);
+ datastore.delete(key);
+ }
+
+ @Test
+ public void testRollback() {
+ Transaction transaction = datastore.newTransaction();
+ TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
+ Key key = transactionSnippets.rollback();
+ Entity result = datastore.get(key);
+ assertNull(result);
+ }
+
+ @Test
+ public void testActive() {
+ Transaction transaction = datastore.newTransaction();
+ TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
+ Key key = transactionSnippets.active();
+ Entity result = datastore.get(key);
+ assertNotNull(result);
+ datastore.delete(key);
+ }
+}