Transaction snippets from omaray

google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java

@@ -105,19 +105,75 @@ interface Response {
   /**
    * Commit the transaction.
    *
+   * <p>Example of committing a transaction
+   * <pre> {@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
+   * }
+   * }</pre>
+   *
    * @throws DatastoreException if could not commit the transaction or if no longer active
    */
   Response commit();
 
   /**
    * Rollback the transaction.
    *
+   * <p>Example of rolling back a Transaction
+   * <pre> {@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
+   * }</pre>
+   *
    * @throws DatastoreException if transaction was already committed
    */
   void rollback();
 
   /**
    * Returns {@code true} if the transaction is still active (was not committed or rolledback).
+   *
+   * <p>Example of verifying if a Transaction is active
+   * <pre> {@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();
+   *   }
+   * }
+   * }</pre>
+   *
    */
   @Override
   boolean active();

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;
+  }
+}

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);
+  }
+}