Package dev.restate.sdk

Interface Context

All Known Subinterfaces:

ObjectContext, SharedObjectContext, SharedWorkflowContext, WorkflowContext

public interface Context

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

All methods of this interface, and related interfaces, 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.

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

Method Summary

Modifier and Type	Method	Description
<T> Awakeable<T>	awakeable(Serde<T> serde)	Create an Awakeable, addressable through Awakeable.id().
AwakeableHandle	awakeableHandle(String id)	Create a new AwakeableHandle for the provided identifier.
default Awaitable<byte[]>	call(Target target, byte[] parameter)	Like call(Target, Serde, Serde, Object) with raw input/output.
<T, R> Awaitable<R>	call(Target target, Serde<T> inputSerde, Serde<R> outputSerde, T parameter)	Invoke another Restate service method.
RestateRandom	random()
Request	request()
default void	run(ThrowingRunnable runnable)	Like run(String, ThrowingRunnable), but without a name.
default void	run(RetryPolicy retryPolicy, ThrowingRunnable runnable)	Like run(ThrowingRunnable), but using a custom retry policy.
default <T> T	run(Serde<T> serde, ThrowingSupplier<T> action)	Like run(String, Serde, ThrowingSupplier), but without a name.
default <T> T	run(Serde<T> serde, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like run(Serde, ThrowingSupplier), but using a custom retry policy.
default void	run(String name, ThrowingRunnable runnable)	Like run(String, Serde, ThrowingSupplier), but without returning a value.
default void	run(String name, RetryPolicy retryPolicy, ThrowingRunnable runnable)	Like run(String, ThrowingRunnable), but using a custom retry policy.
default <T> T	run(String name, Serde<T> serde, ThrowingSupplier<T> action)	Execute a non-deterministic closure, recording the result value in the journal.
<T> T	run(String name, Serde<T> serde, RetryPolicy retryPolicy, ThrowingSupplier<T> action)	Like run(String, Serde, ThrowingSupplier), but using a custom retry policy.
default void	send(Target target, byte[] parameter)	Like send(Target, Serde, Object) with bytes input.
default void	send(Target target, byte[] parameter, Duration delay)	Like send(Target, Serde, Object, Duration) with bytes input.
<T> void	send(Target target, Serde<T> inputSerde, T parameter)	Invoke another Restate service without waiting for the response.
<T> void	send(Target target, Serde<T> inputSerde, T parameter, Duration delay)	Invoke another Restate service without waiting for the response after the provided delay has elapsed.
default void	sleep(Duration duration)	Causes the current execution of the function invocation to sleep for the given duration.
Awaitable<Void>	timer(Duration duration)	Causes the start of a timer for the given duration.

Method Details

request

Request request()

call

<T,
R> Awaitable<R> call(Target target,
 Serde<T> inputSerde,
 Serde<R> outputSerde,
 T parameter)

Invoke another Restate service method.

Parameters:

target - the address of the callee

inputSerde - Input serde

outputSerde - Output serde

parameter - the invocation request parameter.

Returns:

an Awaitable that wraps the Restate service method result.

call

default Awaitable<byte[]> call(Target target,
 byte[] parameter)

Like call(Target, Serde, Serde, Object) with raw input/output.

send

<T> void send(Target target,
 Serde<T> inputSerde,
 T parameter)

Invoke another Restate service without waiting for the response.

Parameters:

target - the address of the callee

inputSerde - Input serde

parameter - the invocation request parameter.

send

default void send(Target target,
 byte[] parameter)

Like send(Target, Serde, Object) with bytes input.

send

<T> void send(Target target,
 Serde<T> inputSerde,
 T parameter,
 Duration delay)

Invoke another Restate service without waiting for the response after the provided delay has elapsed.

This method returns immediately, as the timer is executed and awaited on Restate.

Parameters:

target - the address of the callee

inputSerde - Input serde

parameter - the invocation request parameter.

delay - time to wait before executing the call.

send

default void send(Target target,
 byte[] parameter,
 Duration delay)

Like send(Target, Serde, Object, Duration) with bytes input.

sleep

default void sleep(Duration duration)

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

Parameters:

duration - for which to sleep.

timer

Awaitable<Void> timer(Duration duration)

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

Parameters:

duration - for which to sleep.

run

default <T> T run(String name,
 Serde<T> serde,
 ThrowingSupplier<T> action)
           throws TerminalException

Execute a non-deterministic 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. Use this feature if you want to perform non-deterministic operations.

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, Serde, RetryPolicy, ThrowingSupplier).

Error handling: Errors occurring within this closure won't be propagated to the caller, unless they are TerminalException. Consider the following code:

 // Bad usage of try-catch outside the run
 try {
     ctx.run(() -> {
         throw new IllegalStateException();
     });
 } catch (IllegalStateException e) {
     // This will never be executed,
     // but the error will be retried by Restate,
     // following the invocation retry policy.
 }

 // Good usage of try-catch outside the run
 try {
     ctx.run(() -> {
         throw new TerminalException("my error");
     });
 } catch (TerminalException e) {
     // This is invoked
 }
 

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.

serde - the type tag of the return value, used to serialize/deserialize it.

action - closure to execute.

Returns:

value of the run operation.

Throws:

TerminalException

run

<T> T run(String name,
 Serde<T> serde,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
   throws TerminalException

Like run(String, Serde, 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:

• RetryPolicy

run

default void run(String name,
 RetryPolicy retryPolicy,
 ThrowingRunnable runnable)
          throws TerminalException

Like run(String, ThrowingRunnable), 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:

• RetryPolicy

run

default <T> T run(Serde<T> serde,
 RetryPolicy retryPolicy,
 ThrowingSupplier<T> action)
           throws TerminalException

Like run(Serde, 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:

• RetryPolicy

run

default void run(RetryPolicy retryPolicy,
 ThrowingRunnable runnable)
          throws TerminalException

Like run(ThrowingRunnable), 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:

• RetryPolicy

run

default void run(String name,
 ThrowingRunnable runnable)
          throws TerminalException

Like run(String, Serde, ThrowingSupplier), but without returning a value.

Throws:

TerminalException

run

default <T> T run(Serde<T> serde,
 ThrowingSupplier<T> action)
           throws TerminalException

Like run(String, Serde, ThrowingSupplier), but without a name.

Throws:

TerminalException

run

default void run(ThrowingRunnable runnable)
          throws TerminalException

Like run(String, ThrowingRunnable), but without a name.

Throws:

TerminalException

awakeable

<T> Awakeable<T> awakeable(Serde<T> serde)

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:

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

Returns:

the Awakeable to await on.

See Also:

• Awakeable

awakeableHandle

AwakeableHandle awakeableHandle(String id)

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

See Also:

• Awakeable

random

RestateRandom random()

See Also:

• RestateRandom