DeferredSaver.java

package com.googlecode.objectify.cmd;

/**
 * <p>Element in the command chain for deferred saving of entities. Note that all methods return void;
 * there is no way to force synchronous execution.</p>
 *
 * @author Jeff Schnitzer <jeff@infohazard.org>
 */
public interface DeferredSaver
{
	/**
	 * <p>Save a single entity in the datastore at the end of the current unit-of-work.</p>
	 *
	 * <p>This method can be called multiple times on a single entity; that will produce a single save.
	 * If deferred saves and deletes are applied to an entity, the last one wins.<p>
	 *
	 * <p>If the entity has a null Long id, the value will be autogenerated and populated on the entity object
	 * when the operation completes. Since this is a deferred operation, that will be past the end of your
	 * unit-of-work (transaction boundary).</p>
	 *
	 * <p>Saves do not cascade.</p>
	 *
	 * @param entity must be a registered entity type
	 */
	void entity(Object entity);

	/**
	 * <p>Save a batch of entities in the datastore at the end of the current unit-of-work.</p>
	 *
	 * <p>This method can be called multiple times on a single entity; that will produce a single save.
	 * If deferred saves and deletes are applied to an entity, the last one wins.<p>
	 *
	 * <p>If any entities have null Long ids, the values will be autogenerated and populated on the entity objects
	 * when the operation completes. Since this is a deferred operation, that will be past the end of your
	 * unit-of-work (transaction boundary).</p>
	 *
	 * <p>Saves do not cascade.</p>
	 *
	 * @param entities must be registered entity types
	 */
	void entities(Iterable<?> entities);

	/**
	 * A convenience method for entities(Iterable)
	 */
	void entities(Object... entities);
}