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", "calling commit()").build();
+ *
+ * // add the entity and commit
+ * Transaction txn = datastore.newTransaction();
+ * try {
+ * txn.put(entity);
+ * txn.commit();
+ * } catch (DatastoreException ex) {
+ * // handle exception
+ * }
+ * }
+ *
* @throws DatastoreException if could not commit the transaction or if no longer active
*/
Response commit();
@@ -112,12 +129,51 @@ 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", "calling active()").build();
+ *
+ * // add the entity and rollback
+ * Transaction txn = datastore.newTransaction();
+ * txn.put(entity);
+ * txn.rollback();
+ * // calling txn.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", "calling active()").build();
+ *
+ * // create a transaction
+ * Transaction txn = datastore.newTransaction();
+ * // calling txn.active() now would return true
+ * try {
+ * // add the entity and commit
+ * txn.put(entity);
+ * txn.commit();
+ * } finally {
+ * // if committing succeeded
+ * // then txn.active() will be false
+ * if (txn.active()) {
+ * // otherwise it's true and we need to rollback
+ * txn.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..222b2a53eff9
--- /dev/null
+++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java
@@ -0,0 +1,118 @@
+/*
+ * 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 commitTransaction() {
+ Datastore datastore = transaction.datastore();
+ // [START commitTransaction]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "calling commit()").build();
+
+ // add the entity and commit
+ Transaction txn = datastore.newTransaction();
+ try {
+ txn.put(entity);
+ txn.commit();
+ } catch (DatastoreException ex) {
+ // handle exception
+ }
+ // [END commitTransaction]
+ return key;
+ }
+
+ /**
+ * Example of rolling back a Transaction
+ */
+ // [TARGET rollback()]
+ public Key rollbackTransaction() {
+ Datastore datastore = transaction.datastore();
+ // [START rollbackTransaction]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "calling active()").build();
+
+ // add the entity and rollback
+ Transaction txn = datastore.newTransaction();
+ txn.put(entity);
+ txn.rollback();
+ // calling txn.commit() now would fail
+ // [END rollbackTransaction]
+ return key;
+ }
+
+ /**
+ * Example of verifying if a Transaction is active
+ */
+ // [TARGET active()]
+ public Key activeTransaction() {
+ Datastore datastore = transaction.datastore();
+ // [START activeTransaction]
+ // create an entity
+ KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
+ Key key = datastore.allocateId(keyFactory.newKey());
+ Entity entity = Entity.builder(key).set("description", "calling active()").build();
+
+ // create a transaction
+ Transaction txn = datastore.newTransaction();
+ // calling txn.active() now would return true
+ try {
+ // add the entity and commit
+ txn.put(entity);
+ txn.commit();
+ } finally {
+ // if committing succeeded
+ // then txn.active() will be false
+ if (txn.active()) {
+ // otherwise it's true and we need to rollback
+ txn.rollback();
+ }
+ }
+ // [END activeTransaction]
+ return key;
+ }
+}
\ No newline at end of file
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..5f5a7ed4df9a
--- /dev/null
+++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java
@@ -0,0 +1,74 @@
+/*
+ * 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 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 static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+public class ITTransactionSnippets {
+
+ private static Datastore datastore;
+ private static Transaction transaction;
+ private static TransactionSnippets transactionSnippets;
+
+ @BeforeClass
+ public static void beforeClass() {
+ datastore = DatastoreOptions.defaultInstance().service();
+ transaction = datastore.newTransaction();
+ transactionSnippets = new TransactionSnippets(transaction);
+ }
+
+ @Test
+ public void testCommitTransaction() {
+ Key key = transactionSnippets.commitTransaction();
+ Entity result = datastore.get(key);
+ assertNotNull(result);
+ datastore.delete(key);
+ }
+
+ @Test
+ public void testRollbackTransaction() {
+ Key key = transactionSnippets.rollbackTransaction();
+ Entity result = datastore.get(key);
+ assertNull(result);
+ if (result != null) {
+ datastore.delete(key);
+ }
+ }
+
+ @Test
+ public void testActiveTransaction() {
+ Key key = transactionSnippets.activeTransaction();
+ Entity result = datastore.get(key);
+ assertNotNull(result);
+ datastore.delete(key);
+ }
+}
\ No newline at end of file