diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java index 184fd0831cc9..62d45aeb58d8 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java @@ -49,6 +49,27 @@ interface Response { List getGeneratedKeys(); } + /** + * {@inheritDoc} + * + *

If an entity for {@code entity.getKey()} does not exists, {@code entity} is inserted. + * Otherwise, {@link #submit()} will throw a {@link DatastoreException} with + * {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. + */ + @Override + Entity add(FullEntity entity); + + /** + * {@inheritDoc} + * + *

If none of entities' keys exist, all entities are inserted. If any of entities' keys already + * exists, {@link #submit()} will throw a {@link DatastoreException} with + * {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in + * {@code entities} whose key did not exist are inserted. + */ + @Override + List add(FullEntity... entities); + /** * Submit the batch to the Datastore. * diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java index afb0058c7fae..7ca32d5f6060 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java @@ -125,6 +125,72 @@ interface TransactionCallable { */ List allocateId(IncompleteKey... keys); + /** + * {@inheritDoc} + * + *

If an entity for {@code entity.getKey()} does not exists, {@code entity} is inserted. + * Otherwise, a {@link DatastoreException} is thrown with {@link DatastoreException#getReason()} + * equal to {@code "ALREADY_EXISTS"}. + * + *

Example of adding a single entity. + * 

 {@code
+   * String keyName = "my_key_name";
+   * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+   * Entity.Builder entityBuilder = Entity.newBuilder(key);
+   * entityBuilder.set("propertyName", "value");
+   * Entity entity = entityBuilder.build();
+   * try {
+   *   datastore.add(entity);
+   * } catch (DatastoreException ex) {
+   *   if ("ALREADY_EXISTS".equals(ex.getReason())) {
+   *     // entity.getKey() already exists
+   *   }
+   * }
+   * }
+ * + * @throws DatastoreException upon failure or if an entity for {@code entity.getKey()} already + * exists + */ + @Override + Entity add(FullEntity entity); + + /** + * {@inheritDoc} + * + *

If none of entities' keys exist, all entities are inserted. If any of entities' keys already + * exists the method throws a {@link DatastoreException} with + * {@link DatastoreException#getReason()} equal to {@code "ALREADY_EXISTS"}. All entities in + * {@code entities} whose key did not exist are inserted. To achieve a transactional behavior, + * use {@link Transaction}. + * + *

Example of adding multiple entities. + * 

 {@code
+   * String keyName1 = "my_key_name1";
+   * String keyName2 = "my_key_name2";
+   * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+   * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value1");
+   * Entity entity1 = entityBuilder1.build();
+   * 
+   * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+   * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value2");
+   * Entity entity2 = entityBuilder2.build();
+   * 
+   * try {
+   *   datastore.add(entity1, entity2);
+   * } catch (DatastoreException ex) {
+   *   if ("ALREADY_EXISTS".equals(ex.getReason())) {
+   *     // at least one of entity1.getKey() and entity2.getKey() already exists
+   *   }
+   * }
+   * }
+ * + * @throws DatastoreException upon failure or if any of entities' keys already exists + */ + @Override + List add(FullEntity... entities); + /** * {@inheritDoc} * diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java index 0900243569e8..74a9f13b72c3 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java @@ -26,8 +26,8 @@ interface DatastoreBatchWriter extends DatastoreWriter { /** * Datastore add operation. This method will also allocate id for any entity with an incomplete - * key. As opposed to {@link #add(FullEntity)}, this method will defer any necessary id allocation - * to submit time. + * key. As opposed to {@link #add(FullEntity)} and {@link #add(FullEntity...)}, this method will + * defer any necessary id allocation to submit time. * * @throws IllegalArgumentException if any of the given entities is missing a key * @throws DatastoreException if a given entity with a complete key was already added to this @@ -35,6 +35,18 @@ interface DatastoreBatchWriter extends DatastoreWriter { */ void addWithDeferredIdAllocation(FullEntity... entities); + /** + * {@inheritDoc} + * If {@code entity} has a complete key and was already marked for deletion in this writer, the + * operation will be changed to {@link #put}. + * + * @throws DatastoreException if a given entity with the same complete key was already added to + * this writer, if writer is not active or if id allocation for an entity with an incomplete + * key failed + */ + @Override + Entity add(FullEntity entity); + /** * {@inheritDoc} * For entities with complete keys that were marked for deletion in this writer the operation @@ -42,7 +54,7 @@ interface DatastoreBatchWriter extends DatastoreWriter { * * @throws DatastoreException if a given entity with the same complete key was already added to * this writer, if writer is not active or if id allocation for an entity with an incomplete - * key failed. + * key failed */ @Override List add(FullEntity... entities); @@ -69,19 +81,30 @@ interface DatastoreBatchWriter extends DatastoreWriter { /** * Datastore put operation. This method will also allocate id for any entity with an incomplete - * key. As opposed to {@link #put(FullEntity[])}, this method will defer any necessary id - * allocation to submit time. + * key. As opposed to {@link #put(FullEntity)} and {@link #put(FullEntity...)}, this method will + * defer any necessary id allocation to submit time. * * @throws IllegalArgumentException if any of the given entities is missing a key * @throws DatastoreException if not active */ void putWithDeferredIdAllocation(FullEntity... entities); + /** + * {@inheritDoc} + * This operation will also remove from this writer any prior writes for the same entity. + * + * @throws DatastoreException if not active or if id allocation for an entity with an incomplete + * key failed + */ + @Override + Entity put(FullEntity entity); + /** * {@inheritDoc} * This operation will also remove from this writer any prior writes for the same entities. * - * @throws DatastoreException if not active + * @throws DatastoreException if not active or if id allocation for an entity with an incomplete + * key failed */ @Override List put(FullEntity... entities); diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreWriter.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreWriter.java index 0c66149c2e2b..0078b08121d4 100644 --- a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreWriter.java +++ b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreWriter.java @@ -24,7 +24,8 @@ public interface DatastoreWriter { /** - * Datastore add operation. This method will automatically allocate an id if necessary. + * Datastore add operation: inserts the provided entity. This method will automatically allocate + * an id if necessary. * * @param entity the entity to add * @return an {@code Entity} with the same properties and a key that is either newly allocated @@ -35,8 +36,8 @@ public interface DatastoreWriter { Entity add(FullEntity entity); /** - * Datastore add operation. This method will automatically allocate id for any entity with an - * incomplete key. + * Datastore add operation: inserts the provided entities. This method will automatically allocate + * id for any entity with an incomplete key. * * @return a list of {@code Entity} ordered by input with the same properties and a key that * is either newly allocated or the same one if was already complete @@ -53,8 +54,8 @@ public interface DatastoreWriter { void update(Entity... entities); /** - * A Datastore put (a.k.a upsert) operation. This method will automatically allocate an id if - * necessary. + * A Datastore put (a.k.a upsert) operation: inserts an entity if it does not exist, updates it + * otherwise. This method will automatically allocate an id if necessary. * * @param entity the entity to put * @return an {@code Entity} with the same properties and a key that is either newly allocated @@ -65,8 +66,8 @@ public interface DatastoreWriter { Entity put(FullEntity entity); /** - * A Datastore put (a.k.a upsert) operation. This method will automatically allocate id for any - * entity with an incomplete key. + * A Datastore put (a.k.a upsert) operation: creates an entity if it does not exist, updates it + * otherwise. This method will automatically allocate id for any entity with an incomplete key. * * @return a list of updated or inserted {@code Entity}, ordered by input. Returned keys are * either newly allocated or the same one if was already complete. @@ -76,7 +77,7 @@ public interface DatastoreWriter { List put(FullEntity... entities); /** - * A datastore delete operation. It is OK request a deletion of a non-existing entity. + * A datastore delete operation. It is OK to request the deletion of a non-existing key. */ void delete(Key... keys); } 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 02cd7cf63ed8..590a0ec7ae69 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 @@ -175,6 +175,205 @@ interface Response { @Override QueryResults run(Query query); + /** + * Datastore add operation. This method will also allocate id for any entity with an incomplete + * key. As opposed to {@link #add(FullEntity)} and {@link #add(FullEntity...)}, this method will + * defer any necessary id allocation to commit time. + * + *

Example of adding multiple entities with deferred id allocation. + * 

 {@code
+   * IncompleteKey key1 = datastore.newKeyFactory().setKind("MyKind").newKey();
+   * FullEntity.Builder entityBuilder1 = FullEntity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value1");
+   * FullEntity entity1 = entityBuilder1.build();
+   * 
+   * IncompleteKey key2 = datastore.newKeyFactory().setKind("MyKind").newKey();
+   * FullEntity.Builder entityBuilder2 = FullEntity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value2");
+   * FullEntity entity2 = entityBuilder2.build();
+   * 
+   * transaction.addWithDeferredIdAllocation(entity1, entity2);
+   * Response response = transaction.commit();
+   * }
+ * + * @throws DatastoreException if a given entity with a complete key was already added to this + * transaction or if the transaction is no longer active + */ + void addWithDeferredIdAllocation(FullEntity... entities); + + /** + * {@inheritDoc} + * + *

Example of adding a single entity. + * 

 {@code
+   * String keyName = "my_key_name";
+   * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+   * Entity.Builder entityBuilder = Entity.newBuilder(key);
+   * entityBuilder.set("propertyName", "value");
+   * Entity entity = entityBuilder.build();
+   * transaction.add(entity);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException if a given entity with the same complete key was already added to + * this writer, if the transaction is no longer active or if id allocation for an entity with + * an incomplete key failed + */ + @Override + Entity add(FullEntity entity); + + /** + * {@inheritDoc} + * + *

Example of adding multiple entities. + * 

 {@code
+   * String keyName1 = "my_key_name1";
+   * String keyName2 = "my_key_name2";
+   * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+   * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value1");
+   * Entity entity1 = entityBuilder1.build();
+   * 
+   * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+   * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value2");
+   * Entity entity2 = entityBuilder2.build();
+   * 
+   * transaction.add(entity1, entity2);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException if a given entity with the same complete key was already added to + * this writer, if the transaction is no longer active or if id allocation for an entity with + * an incomplete key failed + */ + @Override + List add(FullEntity... entities); + + /** + * {@inheritDoc} + * This operation will be converted to {@link #put} operation for entities that were already + * added or put in this writer. + * + *

Example of updating multiple entities. + * 

 {@code
+   * String keyName1 = "my_key_name1";
+   * String keyName2 = "my_key_name2";
+   * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+   * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value3");
+   * Entity entity1 = entityBuilder1.build();
+   * 
+   * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+   * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value4");
+   * Entity entity2 = entityBuilder2.build();
+   * 
+   * transaction.update(entity1, entity2);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException if an entity is marked for deletion in this transaction or if the + * transaction is no longer active + */ + @Override + void update(Entity... entities); + + /** + * {@inheritDoc} + * This operation will also remove from this transaction any prior writes for entities with the + * same keys. + * + *

Example of deleting multiple entities. + * 

 {@code
+   * String keyName1 = "my_key_name1";
+   * String keyName2 = "my_key_name2";
+   * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+   * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+   * transaction.delete(key1, key2);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException upon failure or if no longer active + */ + @Override + void delete(Key... keys); + + /** + * Datastore put operation. This method will also allocate id for any entity with an incomplete + * key. As opposed to {@link #put(FullEntity)} and {@link #put(FullEntity...)}, this method will + * defer any necessary id allocation to commit time. + * + *

Example of putting multiple entities with deferred id allocation. + * 

 {@code
+   * IncompleteKey key1 = datastore.newKeyFactory().setKind("MyKind").newKey();
+   * FullEntity.Builder entityBuilder1 = FullEntity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value1");
+   * FullEntity entity1 = entityBuilder1.build();
+   * 
+   * IncompleteKey key2 = datastore.newKeyFactory().setKind("MyKind").newKey();
+   * FullEntity.Builder entityBuilder2 = FullEntity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value2");
+   * FullEntity entity2 = entityBuilder2.build();
+   * 
+   * transaction.putWithDeferredIdAllocation(entity1, entity2);
+   * Response response = transaction.commit();
+   * }
+ * + * @throws IllegalArgumentException if any of the given entities is missing a key + * @throws DatastoreException if no longer active + */ + void putWithDeferredIdAllocation(FullEntity... entities); + + /** + * {@inheritDoc} + * This operation will also remove from this transaction any prior writes for the same entity. + * + *

Example of putting a single entity. + * 

 {@code
+   * String keyName = "my_key_name";
+   * Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName);
+   * Entity.Builder entityBuilder = Entity.newBuilder(key);
+   * entityBuilder.set("propertyName", "value");
+   * Entity entity = entityBuilder.build();
+   * transaction.put(entity);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException if id allocation for an entity with an incomplete key failed or if + * the transaction is no longer active + */ + @Override + Entity put(FullEntity entity); + + /** + * {@inheritDoc} + * This operation will also remove from this transaction any prior writes for the same entities. + * + *

Example of putting multiple entities. + * 

 {@code
+   * String keyName1 = "my_key_name1";
+   * String keyName2 = "my_key_name2";
+   * Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1);
+   * Entity.Builder entityBuilder1 = Entity.newBuilder(key1);
+   * entityBuilder1.set("propertyName", "value1");
+   * Entity entity1 = entityBuilder1.build();
+   * 
+   * Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2);
+   * Entity.Builder entityBuilder2 = Entity.newBuilder(key2);
+   * entityBuilder2.set("propertyName", "value2");
+   * Entity entity2 = entityBuilder2.build();
+   * 
+   * transaction.put(entity1, entity2);
+   * transaction.commit();
+   * }
+ * + * @throws DatastoreException if id allocation for an entity with an incomplete key failed or if + * the transaction is no longer active + */ + @Override + List put(FullEntity... entities); + /** * Commit the transaction. * diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/DatastoreSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/DatastoreSnippets.java index 0233830f6606..1a77eea75fb7 100644 --- a/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/DatastoreSnippets.java +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/datastore/snippets/DatastoreSnippets.java @@ -25,6 +25,7 @@ import com.google.cloud.datastore.Batch; import com.google.cloud.datastore.Datastore; import com.google.cloud.datastore.Datastore.TransactionCallable; +import com.google.cloud.datastore.DatastoreException; import com.google.cloud.datastore.DatastoreReaderWriter; import com.google.cloud.datastore.Entity; import com.google.cloud.datastore.IncompleteKey; @@ -141,6 +142,55 @@ public void batchUpdateEntities(String keyName1, String keyName2) { // [END batchUpdateEntities] } + /** + * Example of adding a single entity. + */ + // [TARGET add(FullEntity)] + // [VARIABLE "my_key_name"] + public void addSingleEntity(String keyName) { + // [START addSingleEntity] + Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName); + Entity.Builder entityBuilder = Entity.newBuilder(key); + entityBuilder.set("propertyName", "value"); + Entity entity = entityBuilder.build(); + try { + datastore.add(entity); + } catch (DatastoreException ex) { + if ("ALREADY_EXISTS".equals(ex.getReason())) { + // entity.getKey() already exists + } + } + // [END addSingleEntity] + } + + /** + * Example of adding multiple entities. + */ + // [TARGET add(FullEntity...)] + // [VARIABLE "my_key_name1"] + // [VARIABLE "my_key_name2"] + public void batchAddEntities(String keyName1, String keyName2) { + // [START batchAddEntities] + Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1); + Entity.Builder entityBuilder1 = Entity.newBuilder(key1); + entityBuilder1.set("propertyName", "value1"); + Entity entity1 = entityBuilder1.build(); + + Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2); + Entity.Builder entityBuilder2 = Entity.newBuilder(key2); + entityBuilder2.set("propertyName", "value2"); + Entity entity2 = entityBuilder2.build(); + + try { + datastore.add(entity1, entity2); + } catch (DatastoreException ex) { + if ("ALREADY_EXISTS".equals(ex.getReason())) { + // at least one of entity1.getKey() and entity2.getKey() already exists + } + } + // [END batchAddEntities] + } + /** * Example of putting a single entity. */ 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 07b5577759b2..7f448a9fbda4 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 @@ -26,12 +26,15 @@ import com.google.cloud.datastore.Datastore; import com.google.cloud.datastore.DatastoreException; import com.google.cloud.datastore.Entity; +import com.google.cloud.datastore.FullEntity; +import com.google.cloud.datastore.IncompleteKey; import com.google.cloud.datastore.Key; import com.google.cloud.datastore.KeyFactory; import com.google.cloud.datastore.Query; import com.google.cloud.datastore.QueryResults; import com.google.cloud.datastore.StructuredQuery.PropertyFilter; import com.google.cloud.datastore.Transaction; +import com.google.cloud.datastore.Transaction.Response; import java.util.Iterator; import java.util.List; @@ -136,6 +139,174 @@ public List run(String parentKeyName) { return entities; } + /** + * Example of adding a single entity. + */ + // [TARGET add(FullEntity)] + // [VARIABLE "my_key_name"] + public void addSingleEntity(String keyName) { + Datastore datastore = transaction.getDatastore(); + // [START addSingleEntity] + Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName); + Entity.Builder entityBuilder = Entity.newBuilder(key); + entityBuilder.set("propertyName", "value"); + Entity entity = entityBuilder.build(); + transaction.add(entity); + transaction.commit(); + // [END addSingleEntity] + } + + /** + * Example of adding multiple entities. + */ + // [TARGET add(FullEntity...)] + // [VARIABLE "my_key_name1"] + // [VARIABLE "my_key_name2"] + public void multipleAddEntities(String keyName1, String keyName2) { + Datastore datastore = transaction.getDatastore(); + // [START multipleAddEntities] + Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1); + Entity.Builder entityBuilder1 = Entity.newBuilder(key1); + entityBuilder1.set("propertyName", "value1"); + Entity entity1 = entityBuilder1.build(); + + Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2); + Entity.Builder entityBuilder2 = Entity.newBuilder(key2); + entityBuilder2.set("propertyName", "value2"); + Entity entity2 = entityBuilder2.build(); + + transaction.add(entity1, entity2); + transaction.commit(); + // [END multipleAddEntities] + } + + /** + * Example of updating multiple entities. + */ + // [TARGET update(Entity...)] + // [VARIABLE "my_key_name1"] + // [VARIABLE "my_key_name2"] + public void multipleUpdateEntities(String keyName1, String keyName2) { + Datastore datastore = transaction.getDatastore(); + // [START multipleUpdateEntities] + Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1); + Entity.Builder entityBuilder1 = Entity.newBuilder(key1); + entityBuilder1.set("propertyName", "value3"); + Entity entity1 = entityBuilder1.build(); + + Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2); + Entity.Builder entityBuilder2 = Entity.newBuilder(key2); + entityBuilder2.set("propertyName", "value4"); + Entity entity2 = entityBuilder2.build(); + + transaction.update(entity1, entity2); + transaction.commit(); + // [END multipleUpdateEntities] + } + + /** + * Example of adding multiple entities with deferred id allocation. + */ + // [TARGET addWithDeferredIdAllocation(FullEntity...)] + public List multipleAddEntitiesDeferredId() { + Datastore datastore = transaction.getDatastore(); + // [START multipleAddEntitiesDeferredId] + IncompleteKey key1 = datastore.newKeyFactory().setKind("MyKind").newKey(); + FullEntity.Builder entityBuilder1 = FullEntity.newBuilder(key1); + entityBuilder1.set("propertyName", "value1"); + FullEntity entity1 = entityBuilder1.build(); + + IncompleteKey key2 = datastore.newKeyFactory().setKind("MyKind").newKey(); + FullEntity.Builder entityBuilder2 = FullEntity.newBuilder(key2); + entityBuilder2.set("propertyName", "value2"); + FullEntity entity2 = entityBuilder2.build(); + + transaction.addWithDeferredIdAllocation(entity1, entity2); + Response response = transaction.commit(); + // [END multipleAddEntitiesDeferredId] + return response.getGeneratedKeys(); + } + + /** + * Example of putting multiple entities with deferred id allocation. + */ + // [TARGET putWithDeferredIdAllocation(FullEntity...)] + public List multiplePutEntitiesDeferredId() { + Datastore datastore = transaction.getDatastore(); + // [START multiplePutEntitiesDeferredId] + IncompleteKey key1 = datastore.newKeyFactory().setKind("MyKind").newKey(); + FullEntity.Builder entityBuilder1 = FullEntity.newBuilder(key1); + entityBuilder1.set("propertyName", "value1"); + FullEntity entity1 = entityBuilder1.build(); + + IncompleteKey key2 = datastore.newKeyFactory().setKind("MyKind").newKey(); + FullEntity.Builder entityBuilder2 = FullEntity.newBuilder(key2); + entityBuilder2.set("propertyName", "value2"); + FullEntity entity2 = entityBuilder2.build(); + + transaction.putWithDeferredIdAllocation(entity1, entity2); + Response response = transaction.commit(); + // [END multiplePutEntitiesDeferredId] + return response.getGeneratedKeys(); + } + + /** + * Example of deleting multiple entities. + */ + // [TARGET delete(Key...)] + // [VARIABLE "my_key_name1"] + // [VARIABLE "my_key_name2"] + public void multipleDeleteEntities(String keyName1, String keyName2) { + Datastore datastore = transaction.getDatastore(); + // [START multipleDeleteEntities] + Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1); + Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2); + transaction.delete(key1, key2); + transaction.commit(); + // [END multipleDeleteEntities] + } + + /** + * Example of putting a single entity. + */ + // [TARGET put(FullEntity)] + // [VARIABLE "my_key_name"] + public void putSingleEntity(String keyName) { + Datastore datastore = transaction.getDatastore(); + // [START putSingleEntity] + Key key = datastore.newKeyFactory().setKind("MyKind").newKey(keyName); + Entity.Builder entityBuilder = Entity.newBuilder(key); + entityBuilder.set("propertyName", "value"); + Entity entity = entityBuilder.build(); + transaction.put(entity); + transaction.commit(); + // [END putSingleEntity] + } + + /** + * Example of putting multiple entities. + */ + // [TARGET put(FullEntity...)] + // [VARIABLE "my_key_name1"] + // [VARIABLE "my_key_name2"] + public void multiplePutEntities(String keyName1, String keyName2) { + Datastore datastore = transaction.getDatastore(); + // [START multiplePutEntities] + Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName1); + Entity.Builder entityBuilder1 = Entity.newBuilder(key1); + entityBuilder1.set("propertyName", "value1"); + Entity entity1 = entityBuilder1.build(); + + Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey(keyName2); + Entity.Builder entityBuilder2 = Entity.newBuilder(key2); + entityBuilder2.set("propertyName", "value2"); + Entity entity2 = entityBuilder2.build(); + + transaction.put(entity1, entity2); + transaction.commit(); + // [END multiplePutEntities] + } + /** * Example of committing a transaction. */ diff --git a/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITDatastoreSnippets.java b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITDatastoreSnippets.java index 8d96afd0c0e6..324525863d78 100644 --- a/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITDatastoreSnippets.java +++ b/google-cloud-examples/src/test/java/com/google/cloud/examples/datastore/snippets/ITDatastoreSnippets.java @@ -117,9 +117,17 @@ public void testAllocateIdMultiple() { assertEquals(2, keys.size()); } + @Test + public void testEntityAddGet() { + String key = registerKey("my_single_key_add"); + datastoreSnippets.addSingleEntity(key); + Entity entity = datastoreSnippets.getEntityWithKey(key); + assertEquals("value", entity.getString("propertyName")); + } + @Test public void testEntityPutGet() { - String key = registerKey("my_single_key"); + String key = registerKey("my_single_key_put"); datastoreSnippets.putSingleEntity(key); Entity entity = datastoreSnippets.getEntityWithKey(key); assertEquals("value", entity.getString("propertyName")); @@ -129,6 +137,17 @@ public void testEntityPutGet() { public void testBatchEntityCrud() { String key1 = registerKey("batch_key1"); String key2 = registerKey("batch_key2"); + + datastoreSnippets.batchAddEntities(key1, key2); + + assertNotNull(datastoreSnippets.getEntityWithKey(key1)); + assertNotNull(datastoreSnippets.getEntityWithKey(key2)); + + datastoreSnippets.batchDeleteEntities(key1, key2); + + assertNull(datastoreSnippets.getEntityWithKey(key1)); + assertNull(datastoreSnippets.getEntityWithKey(key2)); + datastoreSnippets.batchPutEntities(key1, key2); assertNotNull(datastoreSnippets.getEntityWithKey(key1)); 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 index 68f29e831608..0d16ef273d87 100644 --- 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 @@ -27,6 +27,7 @@ import com.google.cloud.datastore.Key; import com.google.cloud.datastore.PathElement; import com.google.cloud.datastore.Transaction; +import com.google.common.collect.ImmutableSet; import com.google.common.collect.Sets; import org.junit.After; @@ -69,38 +70,113 @@ public void afterTest() { } @Test - public void testGet() { - Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey("fetch_key_1"); - Entity entity1 = Entity.newBuilder(key1).set("description", "fetch1").build(); - datastore.put(entity1); - registerKey("fetch_key_1"); + public void testEntityAddGet() { + Transaction transaction = datastore.newTransaction(); + TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); + transactionSnippets.addSingleEntity(registerKey("add_get_key")); + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + Entity entity = transactionSnippets.get("add_get_key"); + assertEquals("value", entity.getString("propertyName")); + } + + @Test + public void testEntityPutGet() { Transaction transaction = datastore.newTransaction(); TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); - assertEquals(entity1, transactionSnippets.get("fetch_key_1")); + transactionSnippets.putSingleEntity(registerKey("put_get_key")); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + Entity entity = transactionSnippets.get("put_get_key"); + assertEquals("value", entity.getString("propertyName")); } @Test - public void testGetMultiple() { - Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey("fetch_key_1"); - Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey("fetch_key_2"); - Entity entity1 = Entity.newBuilder(key1).set("description", "fetch1").build(); - Entity entity2 = Entity.newBuilder(key2).set("description", "fetch2").build(); - datastore.put(entity1, entity2); - registerKey("fetch_key_1"); - registerKey("fetch_key_2"); + public void testAddGetUpdateMultiple() { + Transaction transaction = datastore.newTransaction(); + TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); + transactionSnippets.multipleAddEntities( + registerKey("add_get_multiple_key_1"), registerKey("add_get_multiple_key_2")); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + List entities = + transactionSnippets.getMultiple("add_get_multiple_key_1", "add_get_multiple_key_2"); + assertEquals(2, entities.size()); + Set values = ImmutableSet.of(entities.get(0).getString("propertyName"), + entities.get(1).getString("propertyName")); + assertTrue(values.contains("value1")); + assertTrue(values.contains("value2")); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + transactionSnippets.multipleUpdateEntities( + registerKey("add_get_multiple_key_1"), registerKey("add_get_multiple_key_2")); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + entities = transactionSnippets.getMultiple("add_get_multiple_key_1", "add_get_multiple_key_2"); + assertEquals(2, entities.size()); + values = ImmutableSet.of(entities.get(0).getString("propertyName"), + entities.get(1).getString("propertyName")); + assertTrue(values.contains("value3")); + assertTrue(values.contains("value4")); + } + @Test + public void testAddGetMultipleDeferredId() { Transaction transaction = datastore.newTransaction(); TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); - Set entities = - Sets.newHashSet(transactionSnippets.getMultiple("fetch_key_1", "fetch_key_2")); + List keys = transactionSnippets.multipleAddEntitiesDeferredId(); + assertEquals(2, keys.size()); + Key key1 = keys.get(0); + registerKey(key1); + Entity entity1 = datastore.get(key1); + assertEquals("value1", entity1.getString("propertyName")); + Key key2 = keys.get(1); + registerKey(key2); + Entity entity2 = datastore.get(key2); + assertEquals("value2", entity2.getString("propertyName")); + } + + @Test + public void testPutGetMultiple() { + Transaction transaction = datastore.newTransaction(); + TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); + transactionSnippets.multipleAddEntities( + registerKey("add_get_multiple_key_1"), registerKey("put_get_multiple_key_2")); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + List entities = + transactionSnippets.getMultiple("add_get_multiple_key_1", "put_get_multiple_key_2"); assertEquals(2, entities.size()); - assertTrue(entities.contains(entity1)); - assertTrue(entities.contains(entity2)); + Set values = ImmutableSet.of(entities.get(0).getString("propertyName"), + entities.get(1).getString("propertyName")); + assertTrue(values.contains("value1")); + assertTrue(values.contains("value2")); } @Test - public void testFetchEntitiesWithKeys() { + public void testPutGetMultipleDeferredId() { + Transaction transaction = datastore.newTransaction(); + TransactionSnippets transactionSnippets = new TransactionSnippets(transaction); + List keys = transactionSnippets.multiplePutEntitiesDeferredId(); + assertEquals(2, keys.size()); + Key key1 = keys.get(0); + registerKey(key1); + Entity entity1 = datastore.get(key1); + assertEquals("value1", entity1.getString("propertyName")); + Key key2 = keys.get(1); + registerKey(key2); + Entity entity2 = datastore.get(key2); + assertEquals("value2", entity2.getString("propertyName")); + } + + @Test + public void testFetchDeleteEntitiesWithKeys() { Key key1 = datastore.newKeyFactory().setKind("MyKind").newKey("fetch_key_1"); Key key2 = datastore.newKeyFactory().setKind("MyKind").newKey("fetch_key_2"); Entity entity1 = Entity.newBuilder(key1).set("description", "fetch1").build(); @@ -116,6 +192,17 @@ public void testFetchEntitiesWithKeys() { assertEquals(2, entities.size()); assertTrue(entities.contains(entity1)); assertTrue(entities.contains(entity2)); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + transactionSnippets.multipleDeleteEntities("fetch_key_1", "fetch_key_2"); + + transaction = datastore.newTransaction(); + transactionSnippets = new TransactionSnippets(transaction); + List deletedEntities = + transactionSnippets.fetchEntitiesWithKeys("fetch_key_1", "fetch_key_2"); + assertNull(deletedEntities.get(0)); + assertNull(deletedEntities.get(1)); } @Test