Package dev.restate.sdk

Interface RestateContext

  • @NotThreadSafe
public interface RestateContext
    This interface exposes the Restate functionalities to Restate services. It can be used to access the service instance key-value state storage, interact with other Restate services, record side effects, execute timers and synchronize with external systems.

    To use it within your Restate service, implement RestateService and get an instance with RestateService.restateContext().

    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

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      <T> Awakeable<T> awakeable​(dev.restate.sdk.common.Serde<T> serde)
      Create an Awakeable, addressable through Awakeable.id().
      AwakeableHandle awakeableHandle​(java.lang.String id)
      Create a new AwakeableHandle for the provided identifier.
      <T,​R>
      Awaitable<R>      		 call​(io.grpc.MethodDescriptor<T,​R> methodDescriptor, T parameter)
      Invoke another Restate service method.
      void clear​(dev.restate.sdk.common.StateKey<?> key)
      Clears the state stored under key.
      <T> void delayedCall​(io.grpc.MethodDescriptor<T,​?> methodDescriptor, T parameter, java.time.Duration delay)
      Invoke another Restate service without waiting for the response after the provided delay has elapsed.
      static RestateContext fromSyscalls​(dev.restate.sdk.common.syscalls.Syscalls syscalls)
      Build a RestateContext from the underlying Syscalls object.
      <T> java.util.Optional<T> get​(dev.restate.sdk.common.StateKey<T> key)
      Gets the state stored under key, deserializing the raw value using the Serde in the StateKey.
      default io.grpc.Channel grpcChannel()
      Create a Channel to use with generated blocking stubs to invoke other Restate services.
      <T> void oneWayCall​(io.grpc.MethodDescriptor<T,​?> methodDescriptor, T parameter)
      Invoke another Restate service without waiting for the response.
      RestateRandom random()  
      <T> void set​(dev.restate.sdk.common.StateKey<T> key, T value)
      Sets the given value under the given key, serializing the value using the Serde in the StateKey.
      default void sideEffect​(dev.restate.sdk.common.function.ThrowingRunnable runnable)
      Like sideEffect(Serde, ThrowingSupplier), but without returning a value.
      <T> T sideEffect​(dev.restate.sdk.common.Serde<T> serde, dev.restate.sdk.common.function.ThrowingSupplier<T> action)
      Execute a non-deterministic closure, recording the result value in the journal.
      default void sleep​(java.time.Duration duration)
      Causes the current execution of the function invocation to sleep for the given duration.
      Awaitable<java.lang.Void> timer​(java.time.Duration duration)
      Causes the start of a timer for the given duration.

    • Method Detail

      • get

        <T> java.util.Optional<T> get​(dev.restate.sdk.common.StateKey<T> key)
        Gets the state stored under key, deserializing the raw value using the Serde in the StateKey.
        Parameters:
        key - identifying the state to get and its type.
        Returns:
        an Optional containing the stored state deserialized or an empty Optional if not set yet.
        Throws:
        java.lang.RuntimeException - when the state cannot be deserialized.

      • clear

        void clear​(dev.restate.sdk.common.StateKey<?> key)
        Clears the state stored under key.
        Parameters:
        key - identifying the state to clear.

      • set

        <T> void set​(dev.restate.sdk.common.StateKey<T> key,
             @Nonnull
             T value)
        Sets the given value under the given key, serializing the value using the Serde in the StateKey.
        Parameters:
        key - identifying the value to store and its type.
        value - to store under the given key. MUST NOT be null.

      • sleep

        default void sleep​(java.time.Duration duration)
        Causes the current execution of the function invocation to sleep for the given duration.
        Parameters:
        duration - for which to sleep.

      • timer

        Awaitable<java.lang.Void> timer​(java.time.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.

      • call

        <T,​R> Awaitable<R> call​(io.grpc.MethodDescriptor<T,​R> methodDescriptor,
                              T parameter)
        Invoke another Restate service method.
        Parameters:
        methodDescriptor - The method descriptor of the method to invoke. This is found in the generated `*Grpc` class.
        parameter - the invocation request parameter.
        Returns:
        an Awaitable that wraps the Restate service method result.

      • grpcChannel

        default io.grpc.Channel grpcChannel()
        Create a Channel to use with generated blocking stubs to invoke other Restate services.

        The returned Channel will execute the requests using the call(MethodDescriptor, Object) method.

        Please note that errors will be propagated as TerminalException and not as StatusRuntimeException.

        Returns:
        a Channel to send requests through Restate.

      • oneWayCall

        <T> void oneWayCall​(io.grpc.MethodDescriptor<T,​?> methodDescriptor,
                    T parameter)
        Invoke another Restate service without waiting for the response.
        Parameters:
        methodDescriptor - The method descriptor of the method to invoke. This is found in the generated `*Grpc` class.
        parameter - the invocation request parameter.

      • delayedCall

        <T> void delayedCall​(io.grpc.MethodDescriptor<T,​?> methodDescriptor,
                     T parameter,
                     java.time.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:
        methodDescriptor - The method descriptor of the method to invoke. This is found in the generated *Grpc class.
        parameter - the invocation request parameter.
        delay - time to wait before executing the call.

      • sideEffect

        <T> T sideEffect​(dev.restate.sdk.common.Serde<T> serde,
                 dev.restate.sdk.common.function.ThrowingSupplier<T> action)
          throws dev.restate.sdk.common.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.

        The closure should tolerate retries, that is Restate might re-execute the closure multiple times until it records a result.

        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 side effect
 try {
     ctx.sideEffect(() -> {
         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 side effect
 try {
     ctx.sideEffect(() -> {
         throw new TerminalException("my error");
     });
 } catch (TerminalException e) {
     // This is invoked
 }
        To propagate side effects failures to the side effect call-site, make sure to wrap them in TerminalException.
        Type Parameters:
        T - type of the return value.
        Parameters:
        serde - the type tag of the return value, used to serialize/deserialize it.
        action - to execute for its side effects.
        Returns:
        value of the side effect operation.
        Throws:
        dev.restate.sdk.common.TerminalException

      • sideEffect

        default void sideEffect​(dev.restate.sdk.common.function.ThrowingRunnable runnable)
                 throws dev.restate.sdk.common.TerminalException
        Like sideEffect(Serde, ThrowingSupplier), but without returning a value.
        Throws:
        dev.restate.sdk.common.TerminalException

      • awakeable

        <T> Awakeable<T> awakeable​(dev.restate.sdk.common.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

      • fromSyscalls

        static RestateContext fromSyscalls​(dev.restate.sdk.common.syscalls.Syscalls syscalls)
        Build a RestateContext from the underlying Syscalls object.

        This method is used by code-generation, you should not use it directly but rather use RestateService.restateContext().