AWS Lambda Durable Execution SDK for Java

Build resilient, long-running AWS Lambda functions that automatically checkpoint progress and resume after failures. Durable functions can run for up to one year while you pay only for active compute time.

Key Features

Automatic Checkpointing – Progress is saved after each step; failures resume from the last checkpoint
Cost-Effective Waits – Suspend execution for minutes, hours, or days without compute charges
Configurable Retries – Built-in retry strategies with exponential backoff and jitter
Replay Safety – Functions deterministically resume from checkpoints after interruptions
Type Safety – Full generic type support for step results
Data-Driven Concurrency – Apply a function across a collection with map(), with per-item error isolation and configurable completion criteria

How It Works

Your durable function extends DurableHandler<I, O> and implements handleRequest(I input, DurableContext ctx). The DurableContext is your interface to durable operations:

ctx.step() – Execute code and checkpoint the result
ctx.wait() – Suspend execution without compute charges
ctx.createCallback() – Wait for external events (approvals, webhooks)
ctx.waitForCallback() – Simplify callback handling by combining callback creation and submission in one operation
ctx.invoke() – Invoke another Lambda function, durable or standard, and wait for the result
ctx.runInChildContext() – Run an isolated child context with its own checkpoint log
ctx.map() – Apply a function to each item in a collection concurrently
ctx.parallel() - Run multiple operations concurrently with optional concurrency control
ctx.waitForCondition() – Poll a condition function until it signals done, suspending between polls

Quick Start

Installation

<dependency>
    <groupId>software.amazon.lambda.durable</groupId>
    <artifactId>aws-durable-execution-sdk-java</artifactId>
    <version>VERSION</version>
</dependency>

Your First Durable Function

public class OrderProcessor extends DurableHandler<Order, OrderResult> {

    @Override
    protected OrderResult handleRequest(Order order, DurableContext ctx) {
        // Step 1: Validate and reserve inventory
        var reservation = ctx.step("reserve-inventory", Reservation.class, 
            stepCtx -> inventoryService.reserve(order.getItems()));

        // Step 2: Process payment
        var payment = ctx.step("process-payment", Payment.class,
            stepCtx -> paymentService.charge(order.getPaymentMethod(), order.getTotal()));

        // Wait for warehouse processing (no compute charges)
        ctx.wait(null, Duration.ofHours(2));

        // Step 3: Confirm shipment
        var shipment = ctx.step("confirm-shipment", Shipment.class,
            stepCtx -> shippingService.ship(reservation, order.getAddress()));

        return new OrderResult(order.getId(), shipment.getTrackingNumber());
    }
}

Deployment

See examples/README.md for complete instructions on local testing and running cloud integration tests.

See Deploy and invoke Lambda durable functions with the AWS CLI for more information on deploying and invoking durable functions.

See Deploy Lambda durable functions with Infrastructure as Code for more information on deploying durable functions using infrastructure-as-code.

Documentation

AWS Documentation – Official AWS Lambda durable functions guide
Best Practices – Patterns and recommendations
FAQ - Frequently asked questions for the Java SDK
Javadoc - API reference for the Java SDK
SDK Design – Details of SDK internal architecture

Core Operations

Steps – Execute code with automatic checkpointing and retry support
Wait - Pause execution without blocking Lambda resources
Callbacks - Wait for external systems to respond
Invoke - Call durable functions or standard Lambda functions
Child Contexts - Organize complex workflows into isolated units
Map - Apply a function across a collection concurrently
Parallel - Run multiple operations concurrently with optional concurrency control
Wait for Condition - Poll a condition until it’s met, with configurable backoff

Examples

Examples - Working examples of each operation

Advanced Topics

Configuration - Customize SDK behaviour
Error Handling - SDK exceptions for handling failures
Logging - How to use DurableLogger
Migrating from 1.x to 2.x - Upgrade guide for breaking changes since v1.2.1
Release Process - Prepare and publish Maven releases
Testing - Utilities for local development and cloud-based integration testing

Security

See CONTRIBUTING for information about reporting security issues.

License

This project is licensed under the Apache-2.0 License. See LICENSE for details.