Skip to content

Commit 35c9740

Browse files
mziccardmziccard
authored
---
yaml --- r: 7655 b: refs/heads/tswast-patch-1 c: b74284e h: refs/heads/master i: 7653: e597b75 7651: 84c6f3b 7647: 524e282
1 parent 8d496dc commit 35c9740

10 files changed

Lines changed: 672 additions & 35 deletions

File tree

‎[refs]‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,5 @@ refs/tags/v0.18.0: 9d193c4c4b9d1c6f21515dd8e50836b9194ec9bb
5757
refs/tags/v0.19.0: e67b56e4d8dad5f9a7b38c9b2107c23c828f2ed5
5858
refs/tags/v0.20.0: 839f7fb7156535146aa1cb2c5aadd8d375d854e8
5959
refs/tags/v0.20.1: 370471f437f1f4f68a11e068df5cd6bf39edb1fa
60-
refs/heads/tswast-patch-1: a963ef4045eac0316e5f21d1e4ba8b3a9e93a675
60+
refs/heads/tswast-patch-1: b74284e8750522614060730100cd5c0406c8dc72
6161
refs/heads/pubsub-streaming-pull: 19262b752ee874eb2ca3b950eb2aef44d5a5267b

‎branches/tswast-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,27 @@ interface Response {
4949
List<Key> getGeneratedKeys();
5050
}
5151

52+
/**
53+
* {@inheritDoc}
54+
*
55+
* <p>If an entity for {@code entity.getKey()} does not exists, {@code entity} is inserted.
56+
* Otherwise, {@link #submit()} will throw a {@link DatastoreException} with
57+
* {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}.
58+
*/
59+
@Override
60+
Entity add(FullEntity<?> entity);
61+
62+
/**
63+
* {@inheritDoc}
64+
*
65+
* <p>If none of entities' keys exist, all entities are inserted. If any of entities' keys already
66+
* exists, {@link #submit()} will throw a {@link DatastoreException} with
67+
* {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in
68+
* {@code entities} whose key did not exist are inserted.
69+
*/
70+
@Override
71+
List<Entity> add(FullEntity<?>... entities);
72+
5273
/**
5374
* Submit the batch to the Datastore.
5475
*

‎branches/tswast-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,72 @@ interface TransactionCallable<T> {
125125
*/
126126
List<Key> allocateId(IncompleteKey... keys);
127127

128+
/**
129+
* {@inheritDoc}
130+
*
131+
* <p>If an entity for {@code entity.getKey()} does not exists, {@code entity} is inserted.
132+
* Otherwise, a {@link DatastoreException} is thrown with {@link DatastoreException#getReason()}
133+
* equal to {@code "ALREADY_EXISTS"}.
134+
*
135+
* <p>Example of adding a single entity.
136+
* <pre> {@code
137+
* String keyName = "my_key_name";
138+
* Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
139+
* Entity.Builder entityBuilder = Entity.newBuilder(key);
140+
* entityBuilder.set("propertyName", "value");
141+
* Entity entity = entityBuilder.build();
142+
* try {
143+
* datastore.add(entity);
144+
* } catch (DatastoreException ex) {
145+
* if ("ALREADY_EXISTS".equals(ex.getReason())) {
146+
* // entity.getKey() already exists
147+
* }
148+
* }
149+
* }</pre>
150+
*
151+
* @throws DatastoreException upon failure or if an entity for {@code entity.getKey()} already
152+
* exists
153+
*/
154+
@Override
155+
Entity add(FullEntity<?> entity);
156+
157+
/**
158+
* {@inheritDoc}
159+
*
160+
* <p>If none of entities' keys exist, all entities are inserted. If any of entities' keys already
161+
* exists the method throws a {@link DatastoreException} with
162+
* {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in
163+
* {@code entities} whose key did not exist are inserted. To achieve a transactional behavior,
164+
* use {@link Transaction}.
165+
*
166+
* <p>Example of adding multiple entities.
167+
* <pre> {@code
168+
* String keyName1 = "my_key_name1";
169+
* String keyName2 = "my_key_name2";
170+
* Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
171+
* Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
172+
* entityBuilder1.set("propertyName", "value1");
173+
* Entity entity1 = entityBuilder1.build();
174+
*
175+
* Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
176+
* Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
177+
* entityBuilder2.set("propertyName", "value2");
178+
* Entity entity2 = entityBuilder2.build();
179+
*
180+
* try {
181+
* datastore.add(entity1, entity2);
182+
* } catch (DatastoreException ex) {
183+
* if ("ALREADY_EXISTS".equals(ex.getReason())) {
184+
* // at least one of entity1.getKey() and entity2.getKey() already exists
185+
* }
186+
* }
187+
* }</pre>
188+
*
189+
* @throws DatastoreException upon failure or if any of entities' keys already exists
190+
*/
191+
@Override
192+
List<Entity> add(FullEntity<?>... entities);
193+
128194
/**
129195
* {@inheritDoc}
130196
*

‎branches/tswast-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,23 +26,35 @@ interface DatastoreBatchWriter extends DatastoreWriter {
2626

2727
/**
2828
* Datastore add operation. This method will also allocate id for any entity with an incomplete
29-
* key. As opposed to {@link #add(FullEntity)}, this method will defer any necessary id allocation
30-
* to submit time.
29+
* key. As opposed to {@link #add(FullEntity)} and {@link #add(FullEntity...)}, this method will
30+
* defer any necessary id allocation to submit time.
3131
*
3232
* @throws IllegalArgumentException if any of the given entities is missing a key
3333
* @throws DatastoreException if a given entity with a complete key was already added to this
3434
* writer or if not active
3535
*/
3636
void addWithDeferredIdAllocation(FullEntity<?>... entities);
3737

38+
/**
39+
* {@inheritDoc}
40+
* If {@code entity} has a complete key and was already marked for deletion in this writer, the
41+
* operation will be changed to {@link #put}.
42+
*
43+
* @throws DatastoreException if a given entity with the same complete key was already added to
44+
* this writer, if writer is not active or if id allocation for an entity with an incomplete
45+
* key failed
46+
*/
47+
@Override
48+
Entity add(FullEntity<?> entity);
49+
3850
/**
3951
* {@inheritDoc}
4052
* For entities with complete keys that were marked for deletion in this writer the operation
4153
* will be changed to {@link #put}.
4254
*
4355
* @throws DatastoreException if a given entity with the same complete key was already added to
4456
* this writer, if writer is not active or if id allocation for an entity with an incomplete
45-
* key failed.
57+
* key failed
4658
*/
4759
@Override
4860
List<Entity> add(FullEntity<?>... entities);
@@ -69,19 +81,30 @@ interface DatastoreBatchWriter extends DatastoreWriter {
6981

7082
/**
7183
* Datastore put operation. This method will also allocate id for any entity with an incomplete
72-
* key. As opposed to {@link #put(FullEntity[])}, this method will defer any necessary id
73-
* allocation to submit time.
84+
* key. As opposed to {@link #put(FullEntity)} and {@link #put(FullEntity...)}, this method will
85+
* defer any necessary id allocation to submit time.
7486
*
7587
* @throws IllegalArgumentException if any of the given entities is missing a key
7688
* @throws DatastoreException if not active
7789
*/
7890
void putWithDeferredIdAllocation(FullEntity<?>... entities);
7991

92+
/**
93+
* {@inheritDoc}
94+
* This operation will also remove from this writer any prior writes for the same entity.
95+
*
96+
* @throws DatastoreException if not active or if id allocation for an entity with an incomplete
97+
* key failed
98+
*/
99+
@Override
100+
Entity put(FullEntity<?> entity);
101+
80102
/**
81103
* {@inheritDoc}
82104
* This operation will also remove from this writer any prior writes for the same entities.
83105
*
84-
* @throws DatastoreException if not active
106+
* @throws DatastoreException if not active or if id allocation for an entity with an incomplete
107+
* key failed
85108
*/
86109
@Override
87110
List<Entity> put(FullEntity<?>... entities);

‎branches/tswast-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreWriter.java‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@
2424
public interface DatastoreWriter {
2525

2626
/**
27-
* Datastore add operation. This method will automatically allocate an id if necessary.
27+
* Datastore add operation: inserts the provided entity. This method will automatically allocate
28+
* an id if necessary.
2829
*
2930
* @param entity the entity to add
3031
* @return an {@code Entity} with the same properties and a key that is either newly allocated
@@ -35,8 +36,8 @@ public interface DatastoreWriter {
3536
Entity add(FullEntity<?> entity);
3637

3738
/**
38-
* Datastore add operation. This method will automatically allocate id for any entity with an
39-
* incomplete key.
39+
* Datastore add operation: inserts the provided entities. This method will automatically allocate
40+
* id for any entity with an incomplete key.
4041
*
4142
* @return a list of {@code Entity} ordered by input with the same properties and a key that
4243
* is either newly allocated or the same one if was already complete
@@ -53,8 +54,8 @@ public interface DatastoreWriter {
5354
void update(Entity... entities);
5455

5556
/**
56-
* A Datastore put (a.k.a upsert) operation. This method will automatically allocate an id if
57-
* necessary.
57+
* A Datastore put (a.k.a upsert) operation: inserts an entity if it does not exist, updates it
58+
* otherwise. This method will automatically allocate an id if necessary.
5859
*
5960
* @param entity the entity to put
6061
* @return an {@code Entity} with the same properties and a key that is either newly allocated
@@ -65,8 +66,8 @@ public interface DatastoreWriter {
6566
Entity put(FullEntity<?> entity);
6667

6768
/**
68-
* A Datastore put (a.k.a upsert) operation. This method will automatically allocate id for any
69-
* entity with an incomplete key.
69+
* A Datastore put (a.k.a upsert) operation: creates an entity if it does not exist, updates it
70+
* otherwise. This method will automatically allocate id for any entity with an incomplete key.
7071
*
7172
* @return a list of updated or inserted {@code Entity}, ordered by input. Returned keys are
7273
* either newly allocated or the same one if was already complete.
@@ -76,7 +77,7 @@ public interface DatastoreWriter {
7677
List<Entity> put(FullEntity<?>... entities);
7778

7879
/**
79-
* A datastore delete operation. It is OK request a deletion of a non-existing entity.
80+
* A datastore delete operation. It is OK to request the deletion of a non-existing key.
8081
*/
8182
void delete(Key... keys);
8283
}

0 commit comments

Comments
 (0)