Migration Guide

SDK 3.5.4

Akka SDK 3.5.4 introduces a new @Component annotation, replacing the legacy @ComponentId for identifying components. This change streamlines component configuration and enables new features and improvements. The migration is straightforward and ensures backward compatibility for existing codebases.

Migrating from @ComponentId to @Component

The @ComponentId annotation is now deprecated in favor of the new @Component annotation. To migrate your codebase:

Replace usages of @ComponentId:

Remove the @ComponentId("your-id") annotation from your component classes.
Add the @Component annotation, specifying the required id and optionally name and description fields:

@Component(id = "your-id",
           name = "Your Name",
           description = "Description")
public class YourComponent { ... }

Update imports:

Change import akka.javasdk.annotations.ComponentId; to import akka.javasdk.annotations.Component;

Test backward compatibility:

The framework will continue to support @ComponentId for backward compatibility, but new features and improvements will only be available with @Component.

SDK 3.3.0

This release introduces support for Java 21 virtual threads across all user component and endpoint logic. As a result, it is now safe to perform blocking I/O operations without occupying underlying OS threads.

You no longer need to use CompletionStage or CompletableFuture composition when making calls using component clients, HTTP clients, or gRPC clients. Where services previously used .invokeAsync() and handled a future, you can now simply use .invoke() and work directly with the returned result.

Breaking Changes

To simplify usage and improve developer experience, this release includes a few breaking changes. If your service relies on any of the following features, you will need to update your implementation:

gRPC endpoints for unary and client streaming methods now return the response message directly, instead of wrapping it in a CompletionStage.
gRPC clients now return the response value directly for unary and client streaming calls. For asynchronous behavior, the request builder APIs (grpcClient.someMethod().invokeAsync(parameter)) are still available.

Deprecations

Timer scheduling and cancellation via TimerScheduler.startSingleTimer(…) and TimerScheduler.cancel() are now deprecated. Instead, use TimerScheduler.createSingleTimer(…) and TimerScheduler.delete(). Note that these two new methods are blocking operations that return void.

If you still prefer non-blocking operations, new asynchronous alternatives have been introduced: createSingleTimerAsync() and deleteAsync().

Blocking and Parallelism

To support parallel execution of blocking logic within completion stages, the Service Setup, Endpoints, Consumers, Timed Actions, and Workflows can now accept a java.util.concurrent.Executor via their constructors.

The Akka SDK provides a virtual-thread-enabled executor that is safe for running blocking operations. When using the standard Java CompletableFuture or CompletionStage APIs, you can supply this executor as an additional parameter to methods accepting lambdas, enabling safe parallelism for blocking tasks.