Skip to content

Commit 3c62510

Browse files
mziccardmziccard
authored
Add snippets for Transaction's commit(), rollback() and active() methods (#1248)
1 parent b0f734e commit 3c62510

File tree

3 files changed

+230
-0
lines changed

3 files changed

+230
-0
lines changed

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,19 +105,69 @@ interface Response {
105105
/**
106106
* Commit the transaction.
107107
*
108+
* <p>Example of committing a transaction.
109+
* <pre> {@code
110+
* // create an entity
111+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
112+
* Key key = datastore.allocateId(keyFactory.newKey());
113+
* Entity entity = Entity.builder(key).set("description", "commit()").build();
114+
* // add the entity and commit
115+
* try {
116+
* transaction.put(entity);
117+
* transaction.commit();
118+
* } catch (DatastoreException ex) {
119+
* // handle exception
120+
* }
121+
* }</pre>
122+
*
108123
* @throws DatastoreException if could not commit the transaction or if no longer active
109124
*/
110125
Response commit();
111126

112127
/**
113128
* Rollback the transaction.
114129
*
130+
* <p>Example of rolling back a transaction.
131+
* <pre> {@code
132+
* // create an entity
133+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
134+
* Key key = datastore.allocateId(keyFactory.newKey());
135+
* Entity entity = Entity.builder(key).set("description", "rollback()").build();
136+
*
137+
* // add the entity and rollback
138+
* transaction.put(entity);
139+
* transaction.rollback();
140+
* // calling transaction.commit() now would fail
141+
* }</pre>
142+
*
115143
* @throws DatastoreException if transaction was already committed
116144
*/
117145
void rollback();
118146

119147
/**
120148
* Returns {@code true} if the transaction is still active (was not committed or rolledback).
149+
*
150+
* <p>Example of verifying if a transaction is active.
151+
* <pre> {@code
152+
* // create an entity
153+
* KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
154+
* Key key = datastore.allocateId(keyFactory.newKey());
155+
* Entity entity = Entity.builder(key).set("description", "active()").build();
156+
* // calling transaction.active() now would return true
157+
* try {
158+
* // add the entity and commit
159+
* transaction.put(entity);
160+
* transaction.commit();
161+
* } finally {
162+
* // if committing succeeded
163+
* // then transaction.active() will be false
164+
* if (transaction.active()) {
165+
* // otherwise it's true and we need to rollback
166+
* transaction.rollback();
167+
* }
168+
* }
169+
* }</pre>
170+
*
121171
*/
122172
@Override
123173
boolean active();

‎google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/TransactionSnippets.java‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/*
18+
* EDITING INSTRUCTIONS
19+
* This file is referenced in Transaction's javadoc. Any change to this file should be reflected in
20+
* Transaction's javadoc.
21+
*/
22+
23+
package com.google.cloud.examples.datastore.snippets;
24+
25+
import com.google.cloud.datastore.Datastore;
26+
import com.google.cloud.datastore.DatastoreException;
27+
import com.google.cloud.datastore.Entity;
28+
import com.google.cloud.datastore.Key;
29+
import com.google.cloud.datastore.KeyFactory;
30+
import com.google.cloud.datastore.Transaction;
31+
32+
/**
33+
* This class contains a number of snippets for the {@link Transaction} interface.
34+
*/
35+
public class TransactionSnippets {
36+
37+
private final Transaction transaction;
38+
39+
public TransactionSnippets(Transaction transaction) {
40+
this.transaction = transaction;
41+
}
42+
43+
/**
44+
* Example of committing a transaction.
45+
*/
46+
// [TARGET commit()]
47+
public Key commit() {
48+
Datastore datastore = transaction.datastore();
49+
// [START commit]
50+
// create an entity
51+
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
52+
Key key = datastore.allocateId(keyFactory.newKey());
53+
Entity entity = Entity.builder(key).set("description", "commit()").build();
54+
// add the entity and commit
55+
try {
56+
transaction.put(entity);
57+
transaction.commit();
58+
} catch (DatastoreException ex) {
59+
// handle exception
60+
}
61+
// [END commit]
62+
return key;
63+
}
64+
65+
/**
66+
* Example of rolling back a transaction.
67+
*/
68+
// [TARGET rollback()]
69+
public Key rollback() {
70+
Datastore datastore = transaction.datastore();
71+
// [START rollback]
72+
// create an entity
73+
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
74+
Key key = datastore.allocateId(keyFactory.newKey());
75+
Entity entity = Entity.builder(key).set("description", "rollback()").build();
76+
77+
// add the entity and rollback
78+
transaction.put(entity);
79+
transaction.rollback();
80+
// calling transaction.commit() now would fail
81+
// [END rollback]
82+
return key;
83+
}
84+
85+
/**
86+
* Example of verifying if a transaction is active.
87+
*/
88+
// [TARGET active()]
89+
public Key active() {
90+
Datastore datastore = transaction.datastore();
91+
// [START active]
92+
// create an entity
93+
KeyFactory keyFactory = datastore.newKeyFactory().kind("someKind");
94+
Key key = datastore.allocateId(keyFactory.newKey());
95+
Entity entity = Entity.builder(key).set("description", "active()").build();
96+
// calling transaction.active() now would return true
97+
try {
98+
// add the entity and commit
99+
transaction.put(entity);
100+
transaction.commit();
101+
} finally {
102+
// if committing succeeded
103+
// then transaction.active() will be false
104+
if (transaction.active()) {
105+
// otherwise it's true and we need to rollback
106+
transaction.rollback();
107+
}
108+
}
109+
// [END active]
110+
return key;
111+
}
112+
}

‎google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITTransactionSnippets.java‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.examples.datastore.snippets;
18+
19+
import static org.junit.Assert.assertNotNull;
20+
import static org.junit.Assert.assertNull;
21+
22+
import com.google.cloud.datastore.Datastore;
23+
import com.google.cloud.datastore.DatastoreOptions;
24+
import com.google.cloud.datastore.Entity;
25+
import com.google.cloud.datastore.Key;
26+
import com.google.cloud.datastore.Transaction;
27+
28+
import org.junit.BeforeClass;
29+
import org.junit.Test;
30+
31+
public class ITTransactionSnippets {
32+
33+
private static Datastore datastore;
34+
35+
@BeforeClass
36+
public static void beforeClass() {
37+
datastore = DatastoreOptions.defaultInstance().service();
38+
}
39+
40+
@Test
41+
public void testCommit() {
42+
Transaction transaction = datastore.newTransaction();
43+
TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
44+
Key key = transactionSnippets.commit();
45+
Entity result = datastore.get(key);
46+
assertNotNull(result);
47+
datastore.delete(key);
48+
}
49+
50+
@Test
51+
public void testRollback() {
52+
Transaction transaction = datastore.newTransaction();
53+
TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
54+
Key key = transactionSnippets.rollback();
55+
Entity result = datastore.get(key);
56+
assertNull(result);
57+
}
58+
59+
@Test
60+
public void testActive() {
61+
Transaction transaction = datastore.newTransaction();
62+
TransactionSnippets transactionSnippets = new TransactionSnippets(transaction);
63+
Key key = transactionSnippets.active();
64+
Entity result = datastore.get(key);
65+
assertNotNull(result);
66+
datastore.delete(key);
67+
}
68+
}

0 commit comments

Comments
 (0)