From 645707c694346fd6039e3450cef8690c9a017108 Mon Sep 17 00:00:00 2001 From: omaray Date: Fri, 16 Sep 2016 03:49:13 -0700 Subject: [PATCH 1/4] First commit for the TransactionSnippets.java --- .../snippets/TransactionSnippets.java | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java 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..acb301371fcc --- /dev/null +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java @@ -0,0 +1,115 @@ +/* + * 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 Datastore datastore; + + public TransactionSnippets(Datastore datastore) { + this.datastore = datastore; + } + + /** + * Example of committing a transaction + */ + // [TARGET commit()] + public Key commitTransaction() { + // [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() { + // [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() { + // [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 From f932648a2d7966e60479e238882bf3c116780afa Mon Sep 17 00:00:00 2001 From: omaray Date: Fri, 16 Sep 2016 03:54:20 -0700 Subject: [PATCH 2/4] Passing a Transaction interface instead of a Datastore interface to the constructor --- .../examples/datastore/snippets/TransactionSnippets.java | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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 index acb301371fcc..222b2a53eff9 100644 --- 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 @@ -34,10 +34,10 @@ */ public class TransactionSnippets { - private final Datastore datastore; + private final Transaction transaction; - public TransactionSnippets(Datastore datastore) { - this.datastore = datastore; + public TransactionSnippets(Transaction transaction) { + this.transaction = transaction; } /** @@ -45,6 +45,7 @@ public TransactionSnippets(Datastore datastore) { */ // [TARGET commit()] public Key commitTransaction() { + Datastore datastore = transaction.datastore(); // [START commitTransaction] // create an entity KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind"); @@ -68,6 +69,7 @@ public Key commitTransaction() { */ // [TARGET rollback()] public Key rollbackTransaction() { + Datastore datastore = transaction.datastore(); // [START rollbackTransaction] // create an entity KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind"); @@ -88,6 +90,7 @@ public Key rollbackTransaction() { */ // [TARGET active()] public Key activeTransaction() { + Datastore datastore = transaction.datastore(); // [START activeTransaction] // create an entity KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind"); From bd8a0161501655aae8cb46f09733c3060d448218 Mon Sep 17 00:00:00 2001 From: omaray Date: Fri, 16 Sep 2016 04:26:45 -0700 Subject: [PATCH 3/4] Adding the Integration Test file --- .../snippets/ITTransactionSnippets.java | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java 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 From 96adb6be911d768230042ecf0521fbc5df0aab8c Mon Sep 17 00:00:00 2001 From: omaray Date: Fri, 16 Sep 2016 04:38:33 -0700 Subject: [PATCH 4/4] Running the add_snippets tool to insert snippets --- .../google/cloud/datastore/Transaction.java | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java index 9ecf2c8caeb6..fbbec396c5e2 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java @@ -105,6 +105,23 @@ interface Response { /** * Commit the transaction. * + *

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();