Add better javadoc and snippets for Datastore and Transaction

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

@@ -49,6 +49,27 @@ interface Response {
     List<Key> getGeneratedKeys();
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>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}
+   *
+   * <p>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<Entity> add(FullEntity<?>... entities);
+
   /**
    * Submit the batch to the Datastore.
    *

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

@@ -125,6 +125,72 @@ interface TransactionCallable<T> {
    */
   List<Key> allocateId(IncompleteKey... keys);
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>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"}.
+   *
+   * <p>Example of adding a single entity.
+   * <pre> {@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
+   *   }
+   * }
+   * }</pre>
+   *
+   * @throws DatastoreException upon failure or if an entity for {@code entity.getKey()} already
+   *     exists
+   */
+  @Override
+  Entity add(FullEntity<?> entity);
+
+  /**
+   * {@inheritDoc}
+   *
+   * <p>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}.
+   *
+   * <p>Example of adding multiple entities.
+   * <pre> {@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
+   *   }
+   * }
+   * }</pre>
+   *
+   * @throws DatastoreException upon failure or if any of entities' keys already exists
+   */
+  @Override
+  List<Entity> add(FullEntity<?>... entities);
+
   /**
    * {@inheritDoc}
    *

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

@@ -26,23 +26,35 @@ 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
    *     writer or if not active
    */
   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
    * 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.
+   *     key failed
    */
   @Override
   List<Entity> 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<Entity> put(FullEntity<?>... entities);

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