Package com.broadleafcommerce.dataexchange.service

Interface BatchItemHandler<T1 extends ExchangeObject,T2 extends ExchangeObject>

Type Parameters:
T1 - the parent type (e.g. ComprehensiveProduct)
T2 - The type of the item in the batch. This is a child of the parent type.
All Known Implementing Classes:
AbstractBatchItemHandler, InventoryBatchItemHandler, PriceDataBatchItemHandler, ProductAssetBatchItemHandler, ProductBatchItemHandler, ProductRelatedBatchItemHandler, ProductTagBatchItemHandler, VariantBatchItemHandler, VariantRelatedBatchItemHandler
public interface BatchItemHandler<T1 extends ExchangeObject,T2 extends ExchangeObject>
Implementations of this interface are responsible for handling items in a batch. That includes making any necessary changes and API calls related to the item and returning the updated item.

Most methods in this interface are optional, though typically implementations will implement preHandle(HandlerArgs), handleCreate(HandlerArgs), handleUpdate(HandlerArgs), handleDelete(HandlerArgs), and postHandle(HandlerArgs).

WARNING: If you have need to override/implement methods that return futures, it is important that any composed futures are not composed with async methods. Using async methods will almost certainly result in unexpected behavior, as futures will very likely still be executing when the parent future completes. When using the default implementation of createCompletableFuture(Runnable, HandlerArgs), this will create an async future. It's the composition that should not be async.

Incorrect: 

     
          @Override
          public CompletableFuture<Void> createSupplementalFutures(HandlerArgs<T1, T2> args) {
          Runnable runnable1 = ...;
          Runnable runnable2 = ...;
          Runnable runnable3 = ...;

          CompletableFuture<Void> future1 = createCompletableFuture(runnable1, args);
          return future1.thenComposeAsync((v) -> {
              CompletableFuture<Void> future2 = createCompletableFuture(runnable2, args);
              CompletableFuture<Void> future3 = createCompletableFuture(runnable3, args);
              return CompletableFuture.allOf(future2, future3);
           });
          }
Correct: 
       
            @Override
            public CompletableFuture<Void> createSupplementalFutures(HandlerArgs<T1, T2> args) {
            Runnable runnable1 = ...;
            Runnable runnable2 = ...;
            Runnable runnable3 = ...;

            CompletableFuture<Void> future1 = createCompletableFuture(runnable1, args);
            return future1.thenCompose((v) -> {
                CompletableFuture<Void> future2 = createCompletableFuture(runnable2, args);
                CompletableFuture<Void> future3 = createCompletableFuture(runnable3, args);
                return CompletableFuture.allOf(future2, future3);
             });
            }

  • Method Details

    • preHandle

      @Nullable default Runnable preHandle(HandlerArgs<T1,T2> args)
      Perform any necessary actions before the item is handled (e.g. fetching data, determining save/delete, etc.).
      Parameters:
      args - The handler arguments
      Returns:
      A runnable that will be executed before the item is handled. If no action is necessary, returns null.

    • handle

      @Nullable default Supplier<T2> handle(HandlerArgs<T1,T2> args)
      Perform the necessary actions on the item in the batch. Accepts an instance of HandlerArgs and returns the handled item, which is then passed to postHandle(HandlerArgs).
      Returns:
      A function that accepts an instance of HandlerArgs. If no further handling is necessary, this method or the supplier may return null.

    • handleCreate

      default T2 handleCreate(HandlerArgs<T1,T2> args)
      Handle the create operation. This method is called when HandlerArgs.getOperationType() is BatchItemOperationType.CREATE.

    • handleUpdate

      default T2 handleUpdate(HandlerArgs<T1,T2> args)
      Handle the update operation. This method is called when HandlerArgs.getOperationType() is BatchItemOperationType.UPDATE.

    • handleDelete

      @Nullable default T2 handleDelete(HandlerArgs<T1,T2> args)
      Handle the delete operation. This method is called when HandlerArgs.getOperationType() is BatchItemOperationType.DELETE.

      When performing a delete, unless there is additional logic that needs to be executed, the supplier should return null.

    • postHandle

      @Nullable Runnable postHandle(HandlerArgs<T1,T2> args)
      This method is called after the item has been saved. Any items that should be done after the item is saved should be done here. At minimum, the implementation should set the savedItem result on the parent. At this point, the item is considered "done" and no high risk operations (e.g. API calls) should be done here.
      Parameters:
      args - the handler arguments. Returns null if no action is necessary.

    • canHandle

      boolean canHandle(ExchangeObject exchangeObject)
      Determines if this handler can handle the given exchange object.
      Parameters:
      exchangeObject - the exchange object
      Returns:
      true if this handler can handle the exchange object, false otherwise

    • populateCorrelationId

      @Nullable default Runnable populateCorrelationId(HandlerArgs<T1,T2> args)
      Automatically called after the item is handled. By default, this will always execute last. This method sets the correlation ID on the savedItem and adds it to the batch context via BatchContext.addSavedEntity(ExchangeObject). This method will only set the value if the saved item is an instance of ExchangeObject and the correlation ID is not already set.

      If the saved item is not an instance of ExchangeObject and it needs a correlation ID, this method should be manually implemented to set the correlation ID. For example, if T2 is Collection, it is the implementation's responsibility to populate the correlation ID on the saved item.

      Parameters:
      args - the handler arguments.

    • execute

      CompletableFuture<Void> execute(T1 parent, ExchangeObject exchangeObject, BatchContext<T1> batchContext, org.springframework.core.task.AsyncTaskExecutor executor, org.springframework.retry.support.RetryTemplate retryTemplate)
      The entry point for the handler. Creates a CompletableFuture that will handle the item in the batch. By default, this executes the following steps:
      1. Execute the preHandleRunnable
      2. Execute the handleRunnable
      3. Execute the postHandleRunnable
      4. Execute the populateCorrelationIdRunnable
      AbstractBatchItemHandler contains an implementation, but users may override this method to customize the behavior. For example, if we're handling a product, we may want to execute additional futures after the product is handled.

      See class level documentation for important information about composing futures.

      Parameters:
      parent - the parent object (e.g. ComprehensiveProduct). This is not the saved instance. See BatchContext.getSavedEntity(String)
      exchangeObject - the item in the batch
      batchContext - the batch context
      executor - the executor to use for the future
      retryTemplate - the retry template to use for the future
      Returns:
      a CompletableFuture that will handle the item in the batch
      See Also:

    • execute

      CompletableFuture<Void> execute(T1 parent, ExchangeObject exchangeObject, BatchContext<T1> batchContext, org.springframework.core.task.AsyncTaskExecutor executor, org.springframework.retry.support.RetryTemplate retryTemplate, Map<String,Object> additionalArgs)
      The entry point for the handler. Creates a CompletableFuture that will handle the item in the batch. By default, this executes the following steps:
      1. Execute the preHandleRunnable
      2. Execute the handleRunnable
      3. Execute the postHandleRunnable
      4. Execute the populateCorrelationIdRunnable
      AbstractBatchItemHandler contains an implementation, but users may override this method to customize the behavior. For example, if we're handling a product, we may want to execute additional futures after the product is handled.

      See class level documentation for important information about composing futures.

      Parameters:
      parent - the parent object (e.g. ComprehensiveProduct). This is not the saved instance. See BatchContext.getSavedEntity(String)
      exchangeObject - the item in the batch
      batchContext - the batch context
      executor - the executor to use for the future
      retryTemplate - the retry template to use for the future
      additionalArgs - additional arguments to pass to the handler.
      Returns:
      a CompletableFuture that will handle the item in the batch
      See Also:

    • execute

      CompletableFuture<Void> execute(T1 parent, ExchangeObject exchangeObject, BatchContext<T1> batchContext, org.springframework.core.task.AsyncTaskExecutor executor, org.springframework.retry.support.RetryTemplate retryTemplate, BatchItemOperationType operationType)
      The entry point for the handler. Supports the caller determining the operation type. Creates a CompletableFuture that will handle the item in the batch. By default, this executes the following steps:
      1. Execute the preHandleRunnable
      2. Execute the handleRunnable
      3. Execute the postHandleRunnable
      4. Execute the populateCorrelationIdRunnable
      This method is used when the caller needs to specify the operation type. For example, the product handler is responsible for determining creates/updates/deletes of its children. If the handler is capable of determining the operation type itself and doesn't have any child related entities, the implementation in AbstractBatchItemHandler#execute(T1, ExchangeObject, BatchContext, AsyncTaskExecutor, RetryTemplate) is likely sufficient and the operation type may be determined in the preHandle(HandlerArgs) step.

      See class level documentation for important information about composing futures.

      Parameters:
      parent - the parent object (e.g. ComprehensiveProduct). This is not the saved instance. See BatchContext.getSavedEntity(String)
      exchangeObject - the item in the batch
      batchContext - the batch context
      executor - the executor to use for the future
      retryTemplate - the retry template to use for the future
      Returns:
      a CompletableFuture that will handle the item in the batch

    • execute

      CompletableFuture<Void> execute(T1 parent, ExchangeObject exchangeObject, BatchContext<T1> batchContext, org.springframework.core.task.AsyncTaskExecutor executor, org.springframework.retry.support.RetryTemplate retryTemplate, BatchItemOperationType operationType, Map<String,Object> additionalArgs)
      The entry point for the handler. Supports the caller determining the operation type. Creates a CompletableFuture that will handle the item in the batch. By default, this executes the following steps:
      1. Execute the preHandleRunnable
      2. Execute the handleRunnable
      3. Execute the postHandleRunnable
      4. Execute the populateCorrelationIdRunnable
      This method is used when the caller needs to specify the operation type. For example, the product handler is responsible for determining creates/updates/deletes of its children. If the handler is capable of determining the operation type itself and doesn't have any child related entities, the implementation in AbstractBatchItemHandler#execute(T1, ExchangeObject, BatchContext, AsyncTaskExecutor, RetryTemplate) is likely sufficient and the operation type may be determined in the preHandle(HandlerArgs) step.

      See class level documentation for important information about composing futures.

      Parameters:
      parent - the parent object (e.g. ComprehensiveProduct). This is not the saved instance. See BatchContext.getSavedEntity(String)
      exchangeObject - the item in the batch
      batchContext - the batch context
      executor - the executor to use for the future
      retryTemplate - the retry template to use for the future
      operationType - the operation type
      additionalArgs - additional arguments to pass to the handler.
      Returns:
      a CompletableFuture that will handle the item in the batch

    • createCompletableFuture

      default <R> CompletableFuture<Void> createCompletableFuture(@Nullable Supplier<R> supplier, HandlerArgs<T1,T2> args)
      Create a retryable CompletableFuture that will execute the given supplier. If the supplier is null, this will return a completed future.
      Parameters:
      supplier - The supplier to run
      args - The handler arguments
      Returns:
      A completable future that will run the given supplier

    • retryableSupplier

      @Nullable default <R> Runnable retryableSupplier(@Nullable Supplier<R> supplier, HandlerArgs<T1,T2> args)
      Create a retryable supplier that will run the given supplier. If the supplier is null, this will return null. If using the createCompletableFuture(Supplier, HandlerArgs) method, method, this will be automatically called.
      Parameters:
      supplier - The supplier to run
      args - The handler arguments
      Returns:
      A completable future that will run the given supplier

    • createCompletableFuture

      default CompletableFuture<Void> createCompletableFuture(@Nullable Runnable runnable, HandlerArgs<T1,T2> args)
      Create a CompletableFuture that will run the given runnable. If the runnable is null, this will return a completed future.
      Parameters:
      runnable - The runnable to run
      Returns:
      A completable future that will run the given runnable

    • retryableRunnable

      default Runnable retryableRunnable(Runnable runnable, HandlerArgs<T1,T2> args)
      Returns a retryable runnable. This is automatically called if using the createCompletableFuture(Runnable, HandlerArgs) method.
      Parameters:
      runnable - The runnable to retry
      args - The handler arguments
      Returns:
      A runnable that will retry the given runnable

    • createSupplementalFutures

      default CompletableFuture<Void> createSupplementalFutures(HandlerArgs<T1,T2> args)
      Create any supplemental futures that should be executed after the main future. This should be implemented to handle any child entities that need to be processed after the main entity is handled. CompletableFuture<Void> future1 = ... CompletableFuture<Void> future2 = ... return CompletableFuture.allOf(future1, future2);

      NOTE: See class level documentation for important information about composing futures.

      Parameters:
      args - The handler arguments
      Returns:
      A completable future that will execute any supplemental futures. By default, this returns a completed future.

    • completedFuture

      default <R> CompletableFuture<R> completedFuture()
      Returns a completed future.

    • shouldAbort

      default boolean shouldAbort(HandlerArgs<T1,T2> args)
      Returns true if the handler should abort. If using the built-in createCompletableFuture, retryableSupplier, or retryableRunnable methods, this will be automatically called before the supplier or runnable is executed.
      Parameters:
      args - The handler arguments
      Returns:
      true if the handler should abort