Package dev.restate.sdk

Class Restate

java.lang.Object

dev.restate.sdk.Restate

@Experimental
public final class Restate
extends Object

This class exposes the Restate functionalities to Restate services using the reflection-based API. It can be used to interact with other Restate services, record non-deterministic closures, execute timers, and synchronize with external systems.

This is the entry point for the new reflection-based API where services are defined using annotations and methods can access Restate features through static methods on this class.

Example Usage

 @Service
 public class Greeter {

   @Handler
   public String greet(String input) {
     // Use Restate features via static methods
     String result = Restate.run(
       "external-call",
       String.class,
       () -> externalService.call(input)
     );

     return "You said hi to " + req.name + "!";
   }
 }
 

Error handling

All methods of this class throws either TerminalException or AbortedExecutionException, where the former can be caught and acted upon, while the latter MUST NOT be caught, but simply propagated for clean up purposes.

Serialization and Deserialization

The methods of this class that need to serialize or deserialize payloads have an overload both accepting Class or TypeTag. Depending on your case, you might use the Class overload for simple types, and TypeRef for generic types.

By default, Jackson Databind will be used for all serialization/deserialization. Check SerdeFactory for more details on how to customize that.

Thread safety

This class MUST NOT be accessed concurrently since it can lead to different orderings of user actions, corrupting the execution of the invocation.

See Also:

• Context

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Restate.State	EXPERIMENTAL API: Interface to interact with this Virtual Object/Workflow state.

Constructor Summary

Constructors

Constructor	Description
Restate()

Method Summary

Modifier and Type	Method	Description
static <T> Awakeable<T>	awakeable(TypeTag<T> typeTag)	Create an Awakeable, addressable through Awakeable.id().
static <T> Awakeable<T>	awakeable(Class<T> clazz)	Create an Awakeable, addressable through Awakeable.id().
static AwakeableHandle	awakeableHandle(String id)	Create a new AwakeableHandle for the provided identifier.
static Instant	instantNow()	Returns the current time as a deterministic Instant.
static InvocationHandle<Slice>	invocationHandle(String invocationId)	Like invocationHandle(String, Class), without providing a response parser
static <R> InvocationHandle<R>	invocationHandle(String invocationId, TypeTag<R> responseTypeTag)
static <R> InvocationHandle<R>	invocationHandle(String invocationId, Class<R> responseClazz)	Get an InvocationHandle for an already existing invocation.
static String	key()	EXPERIMENTAL API
static <T> DurablePromise<T>	promise(DurablePromiseKey<T> key)	EXPERIMENTAL API: Create a DurablePromise for the given key.
static <T> DurablePromiseHandle<T>	promiseHandle(DurablePromiseKey<T> key)	EXPERIMENTAL API: Create a new DurablePromiseHandle for the provided key.
static RestateRandom	random()	Returns a deterministic random.
static HandlerRequest	request()
static void	run(String name, ThrowingRunnable runnable)	Like run(String, Class, ThrowingSupplier) without output.
static void	run(String name, RetryPolicy retryPolicy, ThrowingRunnable runnable)	Like run(String, ThrowingRunnable), but without a return value and using a custom retry policy.
static <T> T	run(String name, TypeTag<T> typeTag, ThrowingSupplier<T> action)	Like run(String, Class, ThrowingSupplier), but providing a TypeTag.
static <T> T	run(String name, TypeTag<T> typeTag, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like run(String, TypeTag, ThrowingSupplier), but using a custom retry policy.
static <T> T	run(String name, Class<T> clazz, ThrowingSupplier<T> action)	Execute a closure, recording the result value in the journal.
static <T> T	run(String name, Class<T> clazz, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like run(String, Class, ThrowingSupplier), but using a custom retry policy.
static DurableFuture<Void>	runAsync(String name, ThrowingRunnable runnable)	Like runAsync(String, Class, ThrowingSupplier) without output.
static DurableFuture<Void>	runAsync(String name, RetryPolicy retryPolicy, ThrowingRunnable runnable)	Like runAsync(String, Class, ThrowingSupplier), but without an output and using a custom retry policy.
static <T> DurableFuture<T>	runAsync(String name, TypeTag<T> typeTag, ThrowingSupplier<T> action)	Like runAsync(String, Class, ThrowingSupplier), but providing a TypeTag.
static <T> DurableFuture<T>	runAsync(String name, TypeTag<T> typeTag, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like runAsync(String, TypeTag, ThrowingSupplier), but using a custom retry policy.
static <T> DurableFuture<T>	runAsync(String name, Class<T> clazz, ThrowingSupplier<T> action)	Execute a closure asynchronously.
static <T> DurableFuture<T>	runAsync(String name, Class<T> clazz, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like runAsync(String, Class, ThrowingSupplier), but using a custom retry policy.
static <SVC> SVC	service(Class<SVC> clazz)	EXPERIMENTAL API: Simple API to invoke a Restate service.
static <SVC> ServiceHandle<SVC>	serviceHandle(Class<SVC> clazz)	EXPERIMENTAL API: Advanced API to invoke a Restate service with full control.
static void	sleep(Duration duration)	Causes the current execution of the function invocation to sleep for the given duration.
static Restate.State	state()	EXPERIMENTAL API: Access to this Virtual Object/Workflow state.
static DurableFuture<Void>	timer(String name, Duration duration)	Causes the start of a timer for the given duration.
static <SVC> SVC	virtualObject(Class<SVC> clazz, String key)	EXPERIMENTAL API: Simple API to invoke a Restate Virtual Object.
static <SVC> ServiceHandle<SVC>	virtualObjectHandle(Class<SVC> clazz, String key)	EXPERIMENTAL API: Advanced API to invoke a Restate Virtual Object with full control.
static <SVC> SVC	workflow(Class<SVC> clazz, String key)	EXPERIMENTAL API: Simple API to invoke a Restate Workflow.
static <SVC> ServiceHandle<SVC>	workflowHandle(Class<SVC> clazz, String key)	EXPERIMENTAL API: Advanced API to invoke a Restate Workflow with full control.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Restate

public Restate()

Method Details

request

@Experimental
public static HandlerRequest request()

See Also:

• Context.request()

random

@Experimental
public static RestateRandom random()

Returns a deterministic random.

See Also:

• RestateRandom
• Context.random()

instantNow

@Experimental
public static Instant instantNow()

Returns the current time as a deterministic Instant.

This method returns the current timestamp in a way that is consistent across replays. The time is captured using run(java.lang.String, java.lang.Class<T>, dev.restate.common.function.ThrowingSupplier<T>), ensuring that the same value is returned during replay as was returned during the original execution.

Returns:

the recorded Instant

See Also:

• Instant.now()

invocationHandle

@Experimental
public static <R> InvocationHandle<R> invocationHandle(String invocationId,
 TypeTag<R> responseTypeTag)

See Also:

• Context.invocationHandle(String, TypeTag)

invocationHandle

@Experimental
public static <R> InvocationHandle<R> invocationHandle(String invocationId,
 Class<R> responseClazz)

Get an InvocationHandle for an already existing invocation. This will let you interact with a running invocation, for example to cancel it or retrieve its result.

Parameters:

invocationId - The invocation to interact with.

responseClazz - The response class.

See Also:

• Context.invocationHandle(String, Class)

invocationHandle

@Experimental
public static InvocationHandle<Slice> invocationHandle(String invocationId)

Like invocationHandle(String, Class), without providing a response parser

See Also:

• Context.invocationHandle(String)

sleep

@Experimental
public static void sleep(Duration duration)

Causes the current execution of the function invocation to sleep for the given duration.

Parameters:

duration - for which to sleep.

See Also:

• Context.sleep(Duration)

timer

@Experimental
public static DurableFuture<Void> timer(String name,
 Duration duration)

Causes the start of a timer for the given duration. You can await on the timer end by invoking DurableFuture.await().

Parameters:

name - name used for observability

duration - for which to sleep.

See Also:

• Context.timer(String, Duration)

run

@Experimental
public static <T> T run(String name,
 Class<T> clazz,
 ThrowingSupplier<T> action)
                 throws TerminalException

Execute a closure, recording the result value in the journal. The result value will be re-played in case of re-invocation (e.g. because of failure recovery or suspension point) without re-executing the closure.

If the result type contains generic types, e.g. a List<String>, you should use run(String, TypeTag, ThrowingSupplier). See Context for more details about serialization and deserialization.

You can name this closure using the name parameter. This name will be available in the observability tools.

The closure should tolerate retries, that is Restate might re-execute the closure multiple times until it records a result. You can control and limit the amount of retries using run(String, Class, RetryPolicy, ThrowingSupplier).

Error handling: Errors occurring within this closure won't be propagated to the caller, unless they are TerminalException. To propagate run failures to the call-site, make sure to wrap them in TerminalException.

Type Parameters:

T - type of the return value.

Parameters:

name - name of the side effect.

clazz - the class of the return value, used to serialize/deserialize it.

action - closure to execute.

Returns:

value of the run operation.

Throws:

TerminalException

See Also:

• Context.run(String, Class, ThrowingSupplier)

run

@Experimental
public static <T> T run(String name,
 TypeTag<T> typeTag,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
                 throws TerminalException

Like run(String, TypeTag, ThrowingSupplier), but using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.run(String, TypeTag, RetryPolicy, ThrowingSupplier)

run

@Experimental
public static <T> T run(String name,
 Class<T> clazz,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
                 throws TerminalException

Like run(String, Class, ThrowingSupplier), but using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.run(String, Class, RetryPolicy, ThrowingSupplier)

run

@Experimental
public static <T> T run(String name,
 TypeTag<T> typeTag,
 ThrowingSupplier<T> action)
                 throws TerminalException

Like run(String, Class, ThrowingSupplier), but providing a TypeTag.

See Context for more details about serialization and deserialization.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• Context.run(String, TypeTag, ThrowingSupplier)

run

@Experimental
public static void run(String name,
 RetryPolicy retryPolicy,
 ThrowingRunnable runnable)
                throws TerminalException

Like run(String, ThrowingRunnable), but without a return value and using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.run(String, RetryPolicy, ThrowingRunnable)

run

@Experimental
public static void run(String name,
 ThrowingRunnable runnable)
                throws TerminalException

Like run(String, Class, ThrowingSupplier) without output.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• Context.run(String, ThrowingRunnable)

runAsync

@Experimental
public static <T> DurableFuture<T> runAsync(String name,
 Class<T> clazz,
 ThrowingSupplier<T> action)
                                     throws TerminalException

Execute a closure asynchronously. This is like run(String, Class, ThrowingSupplier), but it returns a DurableFuture that you can combine and select.

Throws:

TerminalException

See Also:

• run(String, Class, ThrowingSupplier)
• Context.runAsync(String, Class, ThrowingSupplier)

runAsync

@Experimental
public static <T> DurableFuture<T> runAsync(String name,
 TypeTag<T> typeTag,
 ThrowingSupplier<T> action)
                                     throws TerminalException

Like runAsync(String, Class, ThrowingSupplier), but providing a TypeTag.

See Context for more details about serialization and deserialization.

Throws:

TerminalException

See Also:

• runAsync(String, Class, ThrowingSupplier)
• Context.runAsync(String, TypeTag, ThrowingSupplier)

runAsync

@Experimental
public static <T> DurableFuture<T> runAsync(String name,
 Class<T> clazz,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
                                     throws TerminalException

Like runAsync(String, Class, ThrowingSupplier), but using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• runAsync(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.runAsync(String, Class, RetryPolicy, ThrowingSupplier)

runAsync

@Experimental
public static <T> DurableFuture<T> runAsync(String name,
 TypeTag<T> typeTag,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
                                     throws TerminalException

Like runAsync(String, TypeTag, ThrowingSupplier), but using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• runAsync(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.runAsync(String, TypeTag, RetryPolicy, ThrowingSupplier)

runAsync

@Experimental
public static DurableFuture<Void> runAsync(String name,
 RetryPolicy retryPolicy,
 ThrowingRunnable runnable)
                                    throws TerminalException

Like runAsync(String, Class, ThrowingSupplier), but without an output and using a custom retry policy.

When a retry policy is not specified, the run will be retried using the Restate invoker retry policy, which by default retries indefinitely.

Throws:

TerminalException

See Also:

• runAsync(String, Class, ThrowingSupplier)
• RetryPolicy
• Context.runAsync(String, RetryPolicy, ThrowingRunnable)

runAsync

@Experimental
public static DurableFuture<Void> runAsync(String name,
 ThrowingRunnable runnable)
                                    throws TerminalException

Like runAsync(String, Class, ThrowingSupplier) without output.

Throws:

TerminalException

See Also:

• Context.runAsync(String, ThrowingRunnable)

awakeable

@Experimental
public static <T> Awakeable<T> awakeable(Class<T> clazz)

Create an Awakeable, addressable through Awakeable.id().

You can use this feature to implement external asynchronous systems interactions, for example you can send a Kafka record including the Awakeable.id(), and then let another service consume from Kafka the responses of given external system interaction by using awakeableHandle(String).

Parameters:

clazz - the response type to use for deserializing the Awakeable result. When using generic types, use awakeable(TypeTag) instead.

Returns:

the Awakeable to await on.

See Also:

• Awakeable
• Context.awakeable(Class)

awakeable

@Experimental
public static <T> Awakeable<T> awakeable(TypeTag<T> typeTag)

Create an Awakeable, addressable through Awakeable.id().

You can use this feature to implement external asynchronous systems interactions, for example you can send a Kafka record including the Awakeable.id(), and then let another service consume from Kafka the responses of given external system interaction by using awakeableHandle(String).

Parameters:

typeTag - the response type tag to use for deserializing the Awakeable result.

Returns:

the Awakeable to await on.

See Also:

• Awakeable
• Context.awakeable(TypeTag)

awakeableHandle

@Experimental
public static AwakeableHandle awakeableHandle(String id)

Create a new AwakeableHandle for the provided identifier. You can use it to AwakeableHandle.resolve(TypeTag, Object) or AwakeableHandle.reject(String) the linked Awakeable.

See Also:

• Awakeable
• Context.awakeableHandle(String)

service

@Experimental
public static <SVC> SVC service(Class<SVC> clazz)

EXPERIMENTAL API: Simple API to invoke a Restate service.

Create a proxy client that allows calling service methods directly and synchronously. This is the recommended approach for straightforward request-response interactions.

 var greeterProxy = Restate.service(Greeter.class);
 GreetingResponse response = greeterProxy.greet(new Greeting("Alice"));
 

For advanced use cases requiring asynchronous request handling, composable futures, or invocation options (such as idempotency keys), use serviceHandle(Class) instead.

Parameters:

clazz - the service class annotated with Service

Returns:

a proxy client to invoke the service

serviceHandle

@Experimental
public static <SVC> ServiceHandle<SVC> serviceHandle(Class<SVC> clazz)

EXPERIMENTAL API: Advanced API to invoke a Restate service with full control.

Create a handle that provides advanced invocation capabilities including:

• Composable futures for asynchronous request handling
• Invocation options such as InvocationOptions.idempotencyKey(String)
• Fire-and-forget requests via send()
• Deferred response handling

 // 1. Use call() with method reference and await the result
 GreetingResponse response = Restate.serviceHandle(Greeter.class)
   .call(Greeter::greet, new Greeting("Alice"))
   .await();

 // 2. Use send() for one-way invocation without waiting
 InvocationHandle<GreetingResponse> handle = Restate.serviceHandle(Greeter.class)
   .send(Greeter::greet, new Greeting("Alice"));
 

For simple synchronous request-response interactions, consider using service(Class) instead.

Parameters:

clazz - the service class annotated with Service

Returns:

a handle to invoke the service with advanced options

virtualObject

@Experimental
public static <SVC> SVC virtualObject(Class<SVC> clazz,
 String key)

EXPERIMENTAL API: Simple API to invoke a Restate Virtual Object.

Create a proxy client that allows calling virtual object methods directly and synchronously. This is the recommended approach for straightforward request-response interactions.

 var counterProxy = Restate.virtualObject(Counter.class, "my-counter");
 int count = counterProxy.increment();
 

For advanced use cases requiring asynchronous request handling, composable futures, or invocation options (such as idempotency keys), use virtualObjectHandle(Class, String) instead.

Parameters:

clazz - the virtual object class annotated with VirtualObject

key - the key identifying the specific virtual object instance

Returns:

a proxy client to invoke the virtual object

virtualObjectHandle

@Experimental
public static <SVC> ServiceHandle<SVC> virtualObjectHandle(Class<SVC> clazz,
 String key)

EXPERIMENTAL API: Advanced API to invoke a Restate Virtual Object with full control.

Create a handle that provides advanced invocation capabilities including:

• Composable futures for asynchronous request handling
• Invocation options such as InvocationOptions.idempotencyKey(String)
• Fire-and-forget requests via send()
• Deferred response handling

 // 1. Use call() with method reference and await the result
 int count = Restate.virtualObjectHandle(Counter.class, "my-counter")
   .call(Counter::increment)
   .await();

 // 2. Use send() for one-way invocation without waiting
 InvocationHandle<Integer> handle = Restate.virtualObjectHandle(Counter.class, "my-counter")
   .send(Counter::increment);
 

For simple synchronous request-response interactions, consider using virtualObject(Class, String) instead.

Parameters:

clazz - the virtual object class annotated with VirtualObject

key - the key identifying the specific virtual object instance

Returns:

a handle to invoke the virtual object with advanced options

workflow

@Experimental
public static <SVC> SVC workflow(Class<SVC> clazz,
 String key)

EXPERIMENTAL API: Simple API to invoke a Restate Workflow.

Create a proxy client that allows calling workflow methods directly and synchronously. This is the recommended approach for straightforward request-response interactions.

 var workflowProxy = Restate.workflow(OrderWorkflow.class, "order-123");
 workflowProxy.start(new OrderRequest(...));
 

For advanced use cases requiring asynchronous request handling, composable futures, or invocation options (such as idempotency keys), use workflowHandle(Class, String) instead.

Parameters:

clazz - the workflow class annotated with Workflow

key - the key identifying the specific workflow instance

Returns:

a proxy client to invoke the workflow

workflowHandle

@Experimental
public static <SVC> ServiceHandle<SVC> workflowHandle(Class<SVC> clazz,
 String key)

EXPERIMENTAL API: Advanced API to invoke a Restate Workflow with full control.

Create a handle that provides advanced invocation capabilities including:

• Composable futures for asynchronous request handling
• Invocation options such as InvocationOptions.idempotencyKey(String)
• Fire-and-forget requests via send()
• Deferred response handling

 // 1. Use call() with method reference and await the result
 Restate.workflowHandle(OrderWorkflow.class, "order-123")
   .call(OrderWorkflow::start, new OrderRequest(...))
   .await();

 // 2. Use send() for one-way invocation without waiting
 InvocationHandle<Void> handle = Restate.workflowHandle(OrderWorkflow.class, "order-123")
   .send(OrderWorkflow::start, new OrderRequest(...));
 

For simple synchronous request-response interactions, consider using workflow(Class, String) instead.

Parameters:

clazz - the workflow class annotated with Workflow

key - the key identifying the specific workflow instance

Returns:

a handle to invoke the workflow with advanced options

key

@Experimental
public static String key()

EXPERIMENTAL API

Returns:

this Virtual Object/Workflow key

Throws:

IllegalStateException - if called from a regular Service handler.

state

@Experimental
public static Restate.State state()

EXPERIMENTAL API: Access to this Virtual Object/Workflow state.

Returns:

Restate.State for this Virtual Object/Workflow

Throws:

IllegalStateException - if called from a regular Service handler.

promise

@Experimental
public static <T> DurablePromise<T> promise(DurablePromiseKey<T> key)

EXPERIMENTAL API: Create a DurablePromise for the given key.

You can use this feature to implement interaction between different workflow handlers, e.g. to send a signal from a shared handler to the workflow handler.

Returns:

the DurablePromise.

Throws:

IllegalStateException - if called from a non-Workflow handler

See Also:

• DurablePromise

promiseHandle

@Experimental
public static <T> DurablePromiseHandle<T> promiseHandle(DurablePromiseKey<T> key)

EXPERIMENTAL API: Create a new DurablePromiseHandle for the provided key. You can use it to DurablePromiseHandle.resolve(Object) or DurablePromiseHandle.reject(String) the given DurablePromise.

Throws:

IllegalStateException - if called from a non-Workflow handler

See Also:

• DurablePromise