Java SDK Async Migration Guide

Who is this guide for?

The migration steps detailed below are only necessary for Java SDKs generated before version 1.606.10 that are opting into async support.

Prerequisites

Speakeasy CLI version 1.606.10 or higher
Java 11 or higher
Existing Java SDK generated by Speakeasy
Access to your .speakeasy/gen.yaml configuration file

Step 1: Enable Async Support in Configuration

Enable the following flag in your .speakeasy/gen.yaml:

Then regenerate your SDK with compilation skipped:

This generates the async hooks and adapters necessary for Step 2. We skip compilation because the SDKHooks file is not touched by the generator, and async SDK initialization requires an additional method that needs to be added manually to that file.

Step 2: Add Async Hook Registration Method

The async feature introduces new hook interfaces that work with CompletableFuture. You’ll need to add a new initialization method to your SDKHooks class.

Locate Your SDKHooks File

Open ./src/main/java/<package>/hooks/SDKHooks.java in your Java SDK project.

Add the Async Initialize Method

Add this method to your SDKHooks class (org.openapis.openapi is a placeholder for your package):

Your SDKHooks class should now look like this:

Step 3: Migrate Existing Hooks (If Applicable)

If you don’t have existing hooks, skip to Step 4. If you do have hooks, choose one of the following migration options:

Hook Parity

Ensure hook parity across sync and async variants. Hooks are not automatically applied across both - you need to register them separately for each variant.

Option A: Quick Migration with HookAdapters

Use HookAdapters to automatically convert your existing synchronous hooks to async:

When to use this option:

Quick migration with minimal code changes
CPU-bound hooks
Low to moderate throughput applications

Performance Consideration

HookAdapters uses the global ForkJoinPool, which may become a bottleneck for I/O-bound hooks in high-throughput applications.

Option B: Full Async Implementation

Reimplement your hooks using async APIs and non-blocking operations:

When to use this option:

High-throughput applications
I/O-bound operations (HTTP calls, database queries, etc.)
Maximum performance requirements

Step 4: Compile the SDK

After making the configuration and code changes, run speakeasy run again to compile and verify the changes are correct:

🚀 Ready to Generate?

Run speakeasy run to compile your SDK with async support!

Then test your application to ensure async functionality works as expected.

Available Async Hook Interfaces

The async support provides three hook interfaces that mirror the synchronous ones:

AsyncHook.BeforeRequest

AsyncHook.AfterSuccess

AsyncHook.AfterError

Best Practices

Choose the right migration option based on your application’s throughput requirements and hook complexity
Test thoroughly after migration to ensure async behavior meets your expectations
Monitor performance to validate that async support provides the expected benefits
Use appropriate async APIs in Option B implementations (async HTTP clients, reactive database drivers, etc.)

Troubleshooting

Missing async initialize method

Ensure you’ve added the initialize(AsyncHooks hooks) method to your SDKHooks class.

Performance issues with HookAdapters

Consider migrating to Option B for I/O-bound hooks in high-throughput scenarios.

Next Steps

After successful migration, your Java SDK will support both synchronous and asynchronous operations, allowing you to leverage non-blocking I/O for improved performance in concurrent applications.