Support for Generic entities

Update most of the entityManager methods to support receiving an extra
ParameterizedType in case the user need to persist a Generic entity.

The type lost by erasure will then be reified using the informations
from the Parameterized type and the fields will be introspected as
normal.

Previous behaviour is not impacted and no breaking change was needed.

Author: Developer Environment

src/main/java/com/jmethods/catatumbo/DatastoreAccess.java

@@ -16,6 +16,7 @@
 
 package com.jmethods.catatumbo;
 
+import java.lang.reflect.Type;
 import java.util.List;
 
 /**
@@ -25,7 +26,7 @@
  * (read/write) within a transaction. Transactions are committed with the call to
  * {@link DatastoreTransaction#commit()} method. Transactions can be rolled back with a call to
  * {@link DatastoreTransaction#rollback()}.
- * 
+ *
  * @author Sai Pullabhotla
  *
  */
@@ -34,7 +35,7 @@ public interface DatastoreTransaction extends DatastoreAccess {
   /**
    * Inserts the given entity. ID allocation is deferred to the submit time. Generated key, if any,
    * can be retrieved by calling {@link DatastoreTransaction.Response#getGeneratedKeys()}.
-   * 
+   *
    * @param entity
    *          the entity to insert.
    * @throws EntityManagerException
@@ -43,10 +44,24 @@ public interface DatastoreTransaction extends DatastoreAccess {
    */
   <E> void insertWithDeferredIdAllocation(E entity);
 
+  /**
+   * Inserts the given entity. ID allocation is deferred to the submit time. Generated key, if any,
+   * can be retrieved by calling {@link DatastoreTransaction.Response#getGeneratedKeys()}.
+   *
+   * @param entity
+   *          the entity to insert.
+   * @param entityType
+   *          the entity type
+   * @throws EntityManagerException
+   *           if the entity has a String Identifier or any other error occurs while accessing the
+   *           underlying Datastore.
+   */
+  <E> void insertWithDeferredIdAllocation(E entity, Type entityType);
+
   /**
    * Inserts the given entities. ID allocation is deferred to the submit time. Generated keys, if
    * any, can be retrieved by calling {@link DatastoreTransaction.Response#getGeneratedKeys()}.
-   * 
+   *
    * @param entities
    *          the entities to insert
    * @throws EntityManagerException
@@ -55,12 +70,26 @@ public interface DatastoreTransaction extends DatastoreAccess {
    */
   <E> void insertWithDeferredIdAllocation(List<E> entities);
 
+  /**
+   * Inserts the given entities. ID allocation is deferred to the submit time. Generated keys, if
+   * any, can be retrieved by calling {@link DatastoreTransaction.Response#getGeneratedKeys()}.
+   *
+   * @param entities
+   *          the entities to insert
+   * @param entityType
+   *          the entity type
+   * @throws EntityManagerException
+   *           if the entity has a String Identifier or any other error occurs while accessing the
+   *           underlying Datastore.
+   */
+  <E> void insertWithDeferredIdAllocation(List<E> entities, Type entityType);
+
   /**
    * Updates or inserts the given entity. ID allocation is deferred to the submit time. Generated
    * key, if any, can be retrieved by calling
    * {@link DatastoreTransaction.Response#getGeneratedKeys()}.
-   * 
-   * 
+   *
+   *
    * @param entity
    *          the entity to update or insert.
    * @throws EntityManagerException
@@ -69,12 +98,28 @@ public interface DatastoreTransaction extends DatastoreAccess {
    */
   <E> void upsertWithDeferredIdAllocation(E entity);
 
+  /**
+   * Updates or inserts the given entity. ID allocation is deferred to the submit time. Generated
+   * key, if any, can be retrieved by calling
+   * {@link DatastoreTransaction.Response#getGeneratedKeys()}.
+   *
+   *
+   * @param entity
+   *          the entity to update or insert.
+   * @param entityType
+   *          the entity type
+   * @throws EntityManagerException
+   *           if the entity has a String Identifier or any other error occurs while accessing the
+   *           underlying Datastore.
+   */
+  <E> void upsertWithDeferredIdAllocation(E entity, Type entityType);
+
   /**
    * Updates or Inserts the given entities. ID allocation is deferred to the submit time. Generated
    * keys, if any, can be retrieved by calling
    * {@link DatastoreTransaction.Response#getGeneratedKeys()}.
-   * 
-   * 
+   *
+   *
    * @param entities
    *          the entities to update or insert
    * @throws EntityManagerException
@@ -83,27 +128,43 @@ public interface DatastoreTransaction extends DatastoreAccess {
    */
   <E> void upsertWithDeferredIdAllocation(List<E> entities);
 
+  /**
+   * Updates or Inserts the given entities. ID allocation is deferred to the submit time. Generated
+   * keys, if any, can be retrieved by calling
+   * {@link DatastoreTransaction.Response#getGeneratedKeys()}.
+   *
+   *
+   * @param entities
+   *          the entities to update or insert
+   * @param entityType
+   *          the entity type
+   * @throws EntityManagerException
+   *           if the entity has a String Identifier or any other error occurs while accessing the
+   *           underlying Datastore.
+   */
+  <E> void upsertWithDeferredIdAllocation(List<E> entities, Type entityType);
+
   /**
    * Tells if this DatastoreTransaction is still active.
-   * 
+   *
    * @return <code>true</code>, if this DatastoreTransaction is still active; <code>false</code>,
    *         otherwise.
    */
   boolean isActive();
 
   /**
    * Commits changes made within this transaction.
-   * 
+   *
    * @return Response. The response contains any generated.
-   * 
+   *
    * @throws EntityManagerException
    *           if the commit fails.
    */
   Response commit();
 
   /**
    * Rolls back the changes made in this transaction.
-   * 
+   *
    * @throws EntityManagerException
    *           if this transaction was already committed.
    */
@@ -112,14 +173,14 @@ public interface DatastoreTransaction extends DatastoreAccess {
   /**
    * Transaction's commit Response. Used for returning generated keys for entities whose id
    * allocation was deferred until submit/commit time.
-   * 
+   *
    * @author Sai Pullabhotla
    *
    */
   interface Response {
     /**
      * Returns a list of generated keys.
-     * 
+     *
      * @return a list of generated keys.
      */
     List<DatastoreKey> getGeneratedKeys();

src/main/java/com/jmethods/catatumbo/DatastoreBatch.java

@@ -16,27 +16,28 @@
 
 package com.jmethods.catatumbo;
 
+import java.lang.reflect.Type;
 import java.util.List;
 
 /**
  * Manages mapping and persistence of entities. EntityManager objects are created using the
  * {@link EntityManagerFactory}.
- * 
+ *
  * @author Sai Pullabhotla
  *
  */
 public interface EntityManager extends DatastoreAccess {
 
   /**
    * Deletes all entities of given Kind.
-   * 
-   * @param entityClass
-   *          the entity class - The entity Kind will be determined from this class.
+   *
+   * @param entityType
+   *          the entity type - The entity Kind will be determined from this class.
    * @return the number of entities that were deleted
    * @throws EntityManagerException
    *           if any error occurs while deleting.
    */
-  <E> long deleteAll(Class<E> entityClass);
+  <E> long deleteAll(Type entityType);
 
   /**
    * Deletes all entities of given Kind.
@@ -51,15 +52,15 @@ public interface EntityManager extends DatastoreAccess {
 
   /**
    * Returns a new Transaction that can be used to perform a set of operations.
-   * 
+   *
    * @return a new Transaction that can be used to perform a set of operations.
    */
   DatastoreTransaction newTransaction();
 
   /**
    * Creates and returns a new {@link DatastoreBatch} that can be used for processing multiple write
    * operations in one request.
-   * 
+   *
    * @return a new <code>DatastoreBatch</code> for processing multiple write operations in one
    *         request.
    */
@@ -71,18 +72,18 @@ public interface EntityManager extends DatastoreAccess {
    * created {@link DatastoreTransaction} to perform reads/writes from/to the Cloud Datastore. When
    * the {@link TransactionalTask} finishes, the transaction is committed. If any error occurs
    * during the execution of the {@link TransactionalTask}, the transaction will be rolled back.
-   * 
+   *
    * @param task
    *          the task (or call back) to execute
    * @return the return value from the execution of
    *         {@link TransactionalTask#execute(DatastoreTransaction)}.
-   * 
+   *
    */
   <T> T executeInTransaction(TransactionalTask<T> task);
 
   /**
    * Registers the given entity lifecycle listeners with this entity manager.
-   * 
+   *
    * @param classes
    *          the classes that should receive entity lifecycle events. Lifecycle callbacks are
    *          executed for all types of entities that are managed by this EntityManager.
@@ -91,15 +92,15 @@ public interface EntityManager extends DatastoreAccess {
 
   /**
    * Returns the {@link DatastoreMetadata} object that can be used to retrieve metadata information.
-   * 
+   *
    * @return the {@link DatastoreMetadata} object that can be used to retrieve metadata information.
    */
   DatastoreMetadata getDatastoreMetadata();
 
   /**
    * Returns the {@link DatastoreStats} object that can be used to retrieve various statistics on
    * the data stored in the Datastore.
-   * 
+   *
    * @return the {@link DatastoreStats} object that can be used to retrieve various statistics on
    *         the data stored in the Datastore.
    */
@@ -108,7 +109,7 @@ public interface EntityManager extends DatastoreAccess {
   /**
    * Allocates IDs for the given entities and returns the allocated IDs. Each entity in the list
    * must have a its identifier of type numeric (long/Long).
-   * 
+   *
    * @param entities
    *          the entities
    * @return a list of {@link DatastoreKey}s.
@@ -120,10 +121,27 @@ public interface EntityManager extends DatastoreAccess {
    */
   List<DatastoreKey> allocateId(List<Object> entities);
 
+  /**
+   * Allocates IDs for the given entities and returns the allocated IDs. Each entity in the list
+   * must have a its identifier of type numeric (long/Long).
+   *
+   * @param entities
+   *          the entities
+   * @param entityType
+   *          the entity type
+   * @return a list of {@link DatastoreKey}s.
+   * @throws IllegalArgumentException
+   *           if any of the entities in the list do not have a numeric ID type or a valid ID is
+   *           already set.
+   * @throws EntityManagerException
+   *           if any error occurs during key allocation
+   */
+  List<DatastoreKey> allocateId(List<Object> entities, Type entityType);
+
   /**
    * Allocates ID for the given entity and returns the allocated ID. The entity must have its
    * identifier of type numeric (long/Long).
-   * 
+   *
    * @param entity
    *          the the entity.
    * @return the allocated ID {@link DatastoreKey}.
@@ -135,4 +153,21 @@ public interface EntityManager extends DatastoreAccess {
    */
   DatastoreKey allocateId(Object entity);
 
+  /**
+   * Allocates ID for the given entity and returns the allocated ID. The entity must have its
+   * identifier of type numeric (long/Long).
+   *
+   * @param entity
+   *          the the entity.
+   * @param entityType
+   *          the entity type
+   * @return the allocated ID {@link DatastoreKey}.
+   * @throws IllegalArgumentException
+   *           if the ID type of the entity is not numeric, or if the entity has a valid ID
+   *           (non-null and non-zero).
+   * @throws EntityManagerException
+   *           if any error occurs during ID allocation
+   */
+  DatastoreKey allocateId(Object entity, Type entityType);
+
 }