Constructor Detail

Method Detail

• persist

  @Suspendable() abstract void persist(@NotNull() String deduplicationId, @NotNull() Object entity)

  Persists a single entity to the store. There is an automatic transient failure retry mechanism backing this method which can sometimes lead to the persistence service internally making multiple requests to persist the same entities. In order that the same entities are not erroneously persisted more than once, a de-duplication mechanism is in place to filter duplicate requests that were already successful. In order for the persistence service to be able to employ this mechanism, this ID must be:

  • Unique within the context of the flow;
  • Deterministic at the time of the function call (I.e., a UUID should not be used).
  • 128 characters or fewer in length.

  For example:

  private static final String MY_ENTITY_DEDUPE_ID = "entity1dedupeId";
  
  private void persistEntity() {
      persistenceService.persist(MY_ENTITY_DEDUPE_ID, entitiy);
  }
  

  It is up to the caller of this function to ensure that the above criteria is fulfilled where de-duplication of retries is a hard requirement. Otherwise, the caller should expect duplication might occur.

  Parameters:

  deduplicationId - A unique identifier used to deduplicate persistence requests.

  entity - The entity to persist.

• persist

  @Suspendable() abstract void persist(@NotNull() String deduplicationId, @NotNull() List<out Object> entities)

  Persists multiple entities in the persistence context in a single transaction. There is an automatic transient failure retry mechanism backing this method which can sometimes lead to the persistence service internally making multiple requests to persist the same entities. In order that the same entities are not erroneously persisted more than once, a de-duplication mechanism is in place to filter duplicate requests that were already successful. In order for the persistence service to be able to employ this mechanism, this ID must be:

  • Unique within the context of the flow;
  • Deterministic at the time of the function call (I.e., a UUID should not be used).
  • 128 characters or fewer in length.

  For example:

  private static final String MY_ENTITY_DEDUPE_ID = "entity1dedupeId";
  
  private void persistEntities() {
      persistenceService.persist(MY_ENTITY_DEDUPE_ID, entities);
  }
  

  It is up to the caller of this function to ensure that the above criteria is fulfilled where de-duplication of retries is a hard requirement. Otherwise, the caller should expect duplication might occur.

  Parameters:

  deduplicationId - A unique identifier used to deduplicate persistence requests.

  entities - List of entities to be persisted.

• merge

  @Suspendable()@Nullable() abstract <T> T merge(@NotNull() T entity)

  Merges a single entity in the persistence context in a transaction.

  Parameters:

  entity - The entity to merge.

  Returns:

  The merged entity.

• merge

  @Suspendable()@NotNull() abstract <T> List<T> merge(@NotNull() List<T> entities)

  Merges multiple entities in the persistence context in a single transaction.

  Parameters:

  entities - List of entities to be merged.

  Returns:

  The list of merged entities.

• remove

  @Suspendable() abstract void remove(@NotNull() Object entity)

  Removes a single entity from the persistence context in a transaction.

  Parameters:

  entity - The entity to remove.

• remove

  @Suspendable() abstract void remove(@NotNull() List<out Object> entities)

  Removes multiple entities from the persistence context in a single transaction.

  Parameters:

  entities - List of entities to be removed.

• find

  @Suspendable()@Nullable() abstract <T> T find(@NotNull() Class<T> entityClass, @NotNull() Object primaryKey)

  Finds a single entity in the persistence context of the specified entity type [T] and with the specified primaryKey.

  Parameters:

  entityClass - The type of entity to find.

  primaryKey - The primary key of the entity to find.

  Returns:

  The found entity. Null if it could not be found in the persistence context.

• find

  @Suspendable()@NotNull() abstract <T> List<T> find(@NotNull() Class<T> entityClass, @NotNull() List<out Object> primaryKeys)

  Finds multiple entities of the same type with different primary keys in a single transaction.

  Parameters:

  entityClass - The type of the entities to find.

  primaryKeys - List of primary keys to find with the given entityClass type.

  Returns:

  List of entities found. Empty list if none were found.

• findAll

  @Suspendable()@NotNull() abstract <T> PagedQuery<T> findAll(@NotNull() Class<T> entityClass)

  Creates a PagedQuery to find all entities of the same type from the persistence context in a single transaction.

  Parameters:

  entityClass - The type of the entities to find.

  Returns:

  A PagedQuery That returns the list of entities found.

• query

  @Suspendable()@NotNull() abstract <T> ParameterizedQuery<T> query(@NotNull() String queryName, @NotNull() Class<T> entityClass)

  Creates a ParameterizedQuery to support a named query to return a list of entities of the given type in a single transaction. Casts result set to the specified type [T].

  Example usage:

  • Kotlin:

    
    // For JPA Entity:
    
    
    
    = "DOGS")
    = "find_by_name_and_age", query = "SELECT d FROM Dog d WHERE d.name = :name AND d.age <= :maxAge")
    class Dog {
        
        private val id: UUID? = null
    
        = "DOG_NAME", length = 50, nullable = false, unique = false)
        private val name: String? = null
    
        = "DOG_AGE")
        private val age: Int? = null // getters and setters
        // ...
    }
    
    // Create a named query that returns pages of up to 100 records
    val pagedQuery = persistenceService
        .query("find_by_name_and_age", Dog::class.java)
        .setParameter("name", "Felix")
        .setParameter("maxAge", 5)
        .setLimit(100)
        .setOffset(0)
    
    // Execute the query and return a ResultSet
    val resultSet = pagedQuery.execute()
    
    processResultsWithApplicationLogic(resultSet.results)
    
    while (resultSet.hasNext()) {
        val results = resultSet.next()
        processResultsWithApplicationLogic(results)
    }
    

  • Java:

    
    // For JPA Entity:
    
    
    = "DOGS")
    = "find_by_name_and_age", query = "SELECT d FROM Dog d WHERE d.name = :name AND d.age <= :maxAge")
    class Dog {
        
        private UUID id;
        = "DOG_NAME", length = 50, nullable = false, unique = false)
        private String name;
        = "DOG_AGE")
        private Integer age;
    
        // getters and setters
         ...
    }
    
    // Create a named query that returns pages of up to 100 records
    ParameterizedQuery<Dog> pagedQuery = persistenceService
            .query("find_by_name_and_age", Dog.class)
            .setParameter("name", "Felix")
            .setParameter("maxAge", 5)
            .setLimit(100)
            .setOffset(0);
    
    // Execute the query and return a ResultSet
    ResultSet<Dog> resultSet = pagedQuery.execute();
    
    processResultsWithApplicationLogic(resultSet.getResults());
    
    while (resultSet.hasNext()) {
        List<Integer> results = resultSet.next();
        processResultsWithApplicationLogic(results);
    }
    

  Parameters:

  queryName - The name of the named query registered in the persistence context.

  entityClass - The type of the entities to find.

  Returns:

  A ParameterizedQuery that returns the list of entities found. Empty list if none were found.