diff --git a/README.md b/README.md index 0b8ff8b12..1cbf700c9 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,9 @@ See the README.md file in each main sample directory for cut/paste Gradle comman - [**Custom Annotation**](/core/src/main/java/io/temporal/samples/customannotation): Demonstrates how to create a custom annotation using an interceptor. +- [**Asnyc Packet Delivery**](/core/src/main/java/io/temporal/samples/packetdelivery): Demonstrates running multiple execution paths async within single execution. + + #### API demonstrations - [**Async Untyped Child Workflow**](/core/src/main/java/io/temporal/samples/asyncuntypedchild): Demonstrates how to invoke an untyped child workflow async, that can complete after parent workflow is already completed. diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/Packet.java b/core/src/main/java/io/temporal/samples/packetdelivery/Packet.java new file mode 100644 index 000000000..2d7ee91d4 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/Packet.java @@ -0,0 +1,21 @@ +package io.temporal.samples.packetdelivery; + +public class Packet { + private int id; + private String content; + + public Packet() {} + + public Packet(int id, String content) { + this.id = id; + this.content = content; + } + + public int getId() { + return id; + } + + public String getContent() { + return content; + } +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketDelivery.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDelivery.java new file mode 100644 index 000000000..334d21bcb --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDelivery.java @@ -0,0 +1,124 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.activity.ActivityOptions; +import io.temporal.failure.ActivityFailure; +import io.temporal.failure.CanceledFailure; +import io.temporal.workflow.*; +import java.time.Duration; +import org.slf4j.Logger; + +public class PacketDelivery { + private Packet packet; + private boolean deliveryConfirmation = false; + private boolean needDeliveryConfirmation = false; + private CompletablePromise delivered = Workflow.newPromise(); + private CancellationScope cancellationScope; + + private Logger logger = Workflow.getLogger(this.getClass().getName()); + + private final PacketDeliveryActivities activities = + Workflow.newActivityStub( + PacketDeliveryActivities.class, + ActivityOptions.newBuilder() + .setStartToCloseTimeout(Duration.ofSeconds(5)) + .setHeartbeatTimeout(Duration.ofSeconds(2)) + .build()); + + private final PacketDeliveryActivities compensationActivities = + Workflow.newActivityStub( + PacketDeliveryActivities.class, + ActivityOptions.newBuilder().setStartToCloseTimeout(Duration.ofSeconds(3)).build()); + + public PacketDelivery(Packet packet) { + this.packet = packet; + processDeliveryAsync(); + } + + public Promise getDelivered() { + return delivered; + } + + public void processDeliveryAsync() { + delivered.completeFrom(Async.procedure(this::processDelivery)); + } + + public void processDelivery() { + cancellationScope = + Workflow.newCancellationScope( + () -> { + String deliveryConfirmationResult = ""; + while (!deliveryConfirmationResult.equals(PacketUtils.COMPLETION_SUCCESS)) { + // Step 1 perform delivery + logger.info( + "** Performing delivery for packet: " + + packet.getId() + + " - " + + packet.getContent()); + activities.performDelivery(packet); + // Step 2 wait for delivery confirmation + logger.info( + "** Delivery for packet: " + + packet.getId() + + " - " + + packet.getContent() + + " awaiting delivery confirmation"); + needDeliveryConfirmation = true; + Workflow.await(() -> deliveryConfirmation); + logger.info( + "** Delivery for packet: " + + packet.getId() + + " - " + + packet.getContent() + + " received confirmation"); + // Step 3 complete delivery processing + logger.info( + "** Completing delivery for packet: " + + packet.getId() + + " - " + + packet.getContent()); + deliveryConfirmationResult = activities.completeDelivery(packet); + // Reset deliveryConfirmation and needDeliveryConfirmation + deliveryConfirmation = false; + needDeliveryConfirmation = false; + } + }); + + try { + cancellationScope.run(); + } catch (Exception e) { + if (e instanceof ActivityFailure) { + ActivityFailure activityFailure = (ActivityFailure) e; + if (activityFailure.getCause() instanceof CanceledFailure) { + // Run compensation activity and complete + compensationActivities.compensateDelivery(packet); + } + } + // Just for show for example that cancel could come in while we are waiting on approval signal + // too + else if (e instanceof CanceledFailure) { + needDeliveryConfirmation = false; + // Run compensation activity and complete + compensationActivities.compensateDelivery(packet); + } + return; + } + } + + public void confirmDelivery() { + this.deliveryConfirmation = true; + } + + public void cancelDelivery(String reason) { + if (cancellationScope != null) { + cancellationScope.cancel(reason); + } + } + + public boolean isNeedDeliveryConfirmation() { + return needDeliveryConfirmation; + } + + public Packet getPacket() { + return packet; + } +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivities.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivities.java new file mode 100644 index 000000000..b2e67dbab --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivities.java @@ -0,0 +1,15 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.activity.ActivityInterface; +import java.util.List; + +@ActivityInterface +public interface PacketDeliveryActivities { + List generatePackets(); + + void performDelivery(Packet packet); + + String completeDelivery(Packet packet); + + String compensateDelivery(Packet packet); +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivitiesImpl.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivitiesImpl.java new file mode 100644 index 000000000..655223501 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryActivitiesImpl.java @@ -0,0 +1,161 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.activity.Activity; +import io.temporal.activity.ActivityExecutionContext; +import io.temporal.client.ActivityCompletionException; +import io.temporal.client.WorkflowClient; +import java.util.*; + +public class PacketDeliveryActivitiesImpl implements PacketDeliveryActivities { + private List packets = + Arrays.asList( + new Packet(1, "books"), + new Packet(2, "jewelry"), + new Packet(3, "furniture"), + new Packet(4, "food"), + new Packet(5, "electronics")); + private WorkflowClient client; + + public PacketDeliveryActivitiesImpl(WorkflowClient client) { + this.client = client; + } + + @Override + public List generatePackets() { + return packets; + } + + @Override + public void performDelivery(Packet packet) { + ActivityExecutionContext context = Activity.getExecutionContext(); + System.out.println( + "** Activity - Performing delivery for packet: " + + packet.getId() + + " with content: " + + packet.getContent()); + for (int i = 0; i < 4; i++) { + try { + // Perform the heartbeat. Used to notify the workflow that activity execution is alive + context.heartbeat(i); + } catch (ActivityCompletionException e) { + System.out.println( + "** Activity - Canceling delivery activity for packet: " + + packet.getId() + + " with content: " + + packet.getContent()); + throw e; + } + } + } + + @Override + public String completeDelivery(Packet packet) { + ActivityExecutionContext context = Activity.getExecutionContext(); + System.out.println( + "** Activity - Completing delivery for package: " + + packet.getId() + + " with content: " + + packet.getContent()); + for (int i = 0; i < 4; i++) { + try { + // Perform the heartbeat. Used to notify the workflow that activity execution is alive + context.heartbeat(i); + } catch (ActivityCompletionException e) { + System.out.println( + "** Activity - Canceling complete delivery activity for packet: " + + packet.getId() + + " with content: " + + packet.getContent()); + throw e; + } + } + // For sample we just confirm + return randomCompletionDeliveryResult(packet); + } + + @Override + public String compensateDelivery(Packet packet) { + System.out.println( + "** Activity - Compensating delivery for package: " + + packet.getId() + + " with content: " + + packet.getContent()); + sleep(1); + return PacketUtils.COMPENSATION_COMPLETED; + } + + /** + * For this sample activity completion result can drive if 1. Delivery confirmation is completed, + * in which case we complete delivery 2. Delivery confirmation is failed, in which case we run the + * delivery again 3. Delivery confirmation is cancelled, in which case we want to cancel delivery + * and perform "cleanup activity" Note that any delivery can cancel itself OR another delivery, so + * for example Furniure delivery can cancel the Food delivery. For sample we have some specific + * rules Which delivery can cancel which + */ + private String randomCompletionDeliveryResult(Packet packet) { + Random random = new Random(); + double randomValue = random.nextDouble(); + if (randomValue < 0.10) { // 10% chance for delivery completion to be canceled + int toCancelDelivery = determineCancelRules(packet); + System.out.println( + "** Activity - Delivery completion result for package: " + + packet.getId() + + " with content: " + + packet.getContent() + + ": " + + "Cancelling delivery: " + + toCancelDelivery); + + // send cancellation signal for packet to be canceled + PacketDeliveryWorkflow packetWorkflow = + client.newWorkflowStub( + PacketDeliveryWorkflow.class, + Activity.getExecutionContext().getInfo().getWorkflowId()); + packetWorkflow.cancelDelivery(toCancelDelivery, "canceled from delivery " + packet.getId()); + + return PacketUtils.COMPLETION_CANCELLED; + } + if (randomValue < 0.20) { // 20% chance for delivery completion to fail + System.out.println( + "** Activity - Delivery completion result for package: " + + packet.getId() + + " with content: " + + packet.getContent() + + ": " + + "Failed"); + return PacketUtils.COMPLETION_FAILURE; + } + + System.out.println( + "** Activity - Delivery completion result for package: " + + packet.getId() + + " with content: " + + packet.getContent() + + ": " + + "Successful"); + return PacketUtils.COMPLETION_SUCCESS; + } + + private void sleep(int seconds) { + try { + Thread.sleep(seconds * 1000L); + } catch (Exception e) { + System.out.println(e.getMessage()); + } + } + + /** + * Sample rules for canceling different deliveries We just rotate the list 1-5 (packet ids) by + * packet id and return first result + */ + private int determineCancelRules(Packet packet) { + List list = new ArrayList<>(Arrays.asList(1, 2, 3, 4, 5)); + Collections.rotate(list, packet.getId()); + System.out.println( + "** Activity - Package delivery : " + + packet.getId() + + " canceling package delivery: " + + list.get(0)); + return list.get(0); + } +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflow.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflow.java new file mode 100644 index 000000000..1f48fac08 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflow.java @@ -0,0 +1,22 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.workflow.QueryMethod; +import io.temporal.workflow.SignalMethod; +import io.temporal.workflow.WorkflowInterface; +import io.temporal.workflow.WorkflowMethod; +import java.util.List; + +@WorkflowInterface +public interface PacketDeliveryWorkflow { + @WorkflowMethod + String execute(); + + @SignalMethod + void confirmDelivery(int deliveryId); + + @SignalMethod + void cancelDelivery(int deliveryId, String reason); + + @QueryMethod + List deliveryConfirmationPackets(); +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflowImpl.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflowImpl.java new file mode 100644 index 000000000..6236458d3 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketDeliveryWorkflowImpl.java @@ -0,0 +1,79 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.activity.ActivityOptions; +import io.temporal.workflow.Promise; +import io.temporal.workflow.Workflow; +import java.time.Duration; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import org.slf4j.Logger; + +public class PacketDeliveryWorkflowImpl implements PacketDeliveryWorkflow { + private final Map packetDeliveries = new HashMap<>(); + private final Logger logger = Workflow.getLogger(this.getClass().getName()); + + private final PacketDeliveryActivities activities = + Workflow.newActivityStub( + PacketDeliveryActivities.class, + ActivityOptions.newBuilder() + .setStartToCloseTimeout(Duration.ofSeconds(5)) + .setHeartbeatTimeout(Duration.ofSeconds(2)) + .build()); + + @Override + public String execute() { + List> packetsDelivered = new ArrayList<>(); + // Step 1 - upload initial packets to deliver + List initialPackets = activities.generatePackets(); + // Step 2 - set up delivery processing + for (Packet packet : initialPackets) { + PacketDelivery delivery = new PacketDelivery(packet); + packetDeliveries.put(packet.getId(), delivery); + packetsDelivered.add(delivery.getDelivered()); + } + + // Wait for all packet deliveries to complete + Promise.allOf(packetsDelivered).get(); + return "completed"; + } + + @Override + public void confirmDelivery(int deliveryId) { + if (packetDeliveries.containsKey(deliveryId)) { + packetDeliveries.get(deliveryId).confirmDelivery(); + } + } + + @Override + public void cancelDelivery(int deliveryId, String reason) { + if (packetDeliveries.containsKey(deliveryId)) { + // Only makes sense to cancel if delivery is not done yet + if (!packetDeliveries.get(deliveryId).getDelivered().isCompleted()) { + logger.info("Sending cancellation for delivery : " + deliveryId + " and reason: " + reason); + packetDeliveries.get(deliveryId).cancelDelivery(reason); + } + logger.info( + "Bypassing sending cancellation for delivery : " + + deliveryId + + " and reason: " + + reason + + " because delivery already completed"); + } + } + + @Override + public List deliveryConfirmationPackets() { + List confirmationPackets = new ArrayList<>(); + packetDeliveries + .values() + .forEach( + p -> { + if (p.isNeedDeliveryConfirmation()) { + confirmationPackets.add(p.getPacket()); + } + }); + return confirmationPackets; + } +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/PacketUtils.java b/core/src/main/java/io/temporal/samples/packetdelivery/PacketUtils.java new file mode 100644 index 000000000..193a2f4be --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/PacketUtils.java @@ -0,0 +1,8 @@ +package io.temporal.samples.packetdelivery; + +public class PacketUtils { + public static String COMPLETION_SUCCESS = "Delivery Completion Successful"; + public static String COMPLETION_FAILURE = "Delivery Completion Failed"; + public static String COMPLETION_CANCELLED = "Delivery Completion Cancelled"; + public static String COMPENSATION_COMPLETED = "Delivery Compensation Completed"; +} diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/README.md b/core/src/main/java/io/temporal/samples/packetdelivery/README.md new file mode 100644 index 000000000..d43309990 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/README.md @@ -0,0 +1,24 @@ +# Async Package Delivery Sample + +This sample show how to run multiple "paths" of execution async within single workflow. +Sample starts deliveries of 5 items in parallel. Each item performs an activity +and then waits for a confirmation signal, then performs second activity. + +Workflow waits until all packets have been delivered. Each packet delivery path can choose to +also "cancel" delivery of another item. This is done via signal and cancellation of the +CancellationScope. + +## Notes +1. In this sample we do not handle event history count and size partitioning via ContinueAsNew. It is assumed +that the total number of paths and path lengths (in terms of activity executions) would not exceed it. +For your use case you might need to add ContinueAsNew checks to deal with this situation. +2. Use this sample as all other ones as reference for your implementation. It was not tested on high scale +so using it as-is without load testing is not recommended. + +## Start the Sample: +```bash +./gradlew -q execute -PmainClass=io.temporal.samples.packetdelivery.Starter +``` + +Run sample multiple times to see different scenarios (delivery failure and retry and delivery cancelation) +There is a 10% chance delivery is going to be canceled and 20% chane it will fail. \ No newline at end of file diff --git a/core/src/main/java/io/temporal/samples/packetdelivery/Starter.java b/core/src/main/java/io/temporal/samples/packetdelivery/Starter.java new file mode 100644 index 000000000..e1d97e621 --- /dev/null +++ b/core/src/main/java/io/temporal/samples/packetdelivery/Starter.java @@ -0,0 +1,70 @@ +package io.temporal.samples.packetdelivery; + +import io.temporal.client.WorkflowClient; +import io.temporal.client.WorkflowNotFoundException; +import io.temporal.client.WorkflowOptions; +import io.temporal.client.WorkflowStub; +import io.temporal.serviceclient.WorkflowServiceStubs; +import io.temporal.worker.Worker; +import io.temporal.worker.WorkerFactory; +import java.util.Collections; +import java.util.List; + +public class Starter { + public static void main(String[] args) { + WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs(); + WorkflowClient client = WorkflowClient.newInstance(service); + WorkerFactory factory = WorkerFactory.newInstance(client); + Worker worker = factory.newWorker("packet-delivery-taskqueue"); + + worker.registerWorkflowImplementationTypes(PacketDeliveryWorkflowImpl.class); + worker.registerActivitiesImplementations(new PacketDeliveryActivitiesImpl(client)); + + factory.start(); + + PacketDeliveryWorkflow workflow = + client.newWorkflowStub( + PacketDeliveryWorkflow.class, + WorkflowOptions.newBuilder() + .setWorkflowId("packet-delivery-workflow") + .setTaskQueue("packet-delivery-taskqueue") + .build()); + + WorkflowClient.start(workflow::execute); + + // start completing package deliveries (send confirmations) + // Query workflow for packets that need confirmation, confirm until none need confirmation any + // more + while (true) { + sleep(3); + List packets = workflow.deliveryConfirmationPackets(); + if (packets.isEmpty()) { + break; + } + // for "fun", reverse the list we get from delivery confirmation list + Collections.reverse(packets); + + for (Packet p : packets) { + try { + workflow.confirmDelivery(p.getId()); + } catch (WorkflowNotFoundException e) { + // In some cases with cancellations happening, workflow could be completed by now + // We just ignore and exit out of loop + break; + } + } + } + + // wait for workflow to complete + String result = WorkflowStub.fromTyped(workflow).getResult(String.class); + System.out.println("** Workflow Result: " + result); + } + + private static void sleep(int seconds) { + try { + Thread.sleep(seconds * 1000L); + } catch (Exception e) { + System.out.println(e.getMessage()); + } + } +}