Feedback

sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/api.kt

@@ -244,8 +244,8 @@ suspend inline fun <reified T : Any> Context.awakeable(): Awakeable<T> {
 }
 
 /**
- * This interface extends [Context] adding access to the virtual object instance key-value state
- * storage.
+ * This interface can be used only within shared handlers of virtual objects. It extends [Context]
+ * adding access to the virtual object instance key-value state storage.
  */
 sealed interface SharedObjectContext : Context {
 
@@ -270,8 +270,8 @@ sealed interface SharedObjectContext : Context {
 }
 
 /**
- * This interface extends [Context] adding access to the virtual object instance key-value state
- * storage.
+ * This interface can be used only within exclusive handlers of virtual objects. It extends
+ * [Context] adding access to the virtual object instance key-value state storage.
  */
 sealed interface ObjectContext : SharedObjectContext {
 
@@ -295,10 +295,8 @@ sealed interface ObjectContext : SharedObjectContext {
 }
 
 /**
- * This interface extends [Context] adding access to the workflow instance key-value state storage
- * and to the [DurablePromise] API.
- *
- * This interface can be used only within shared handlers of workflow classes/interfaces.
+ * This interface can be used only within shared handlers of workflow. It extends [Context] adding
+ * access to the workflow instance key-value state storage and to the [DurablePromise] API.
  *
  * NOTE: This interface MUST NOT be accessed concurrently since it can lead to different orderings
  * of user actions, corrupting the execution of the invocation.
@@ -327,10 +325,8 @@ sealed interface SharedWorkflowContext : SharedObjectContext {
 }
 
 /**
- * This interface extends [Context] adding access to the workflow instance key-value state storage
- * and to the [DurablePromise] API.
- *
- * This interface can be used only within workflow handlers of workflow classes/interfaces.
+ * This interface can be used only within workflow handlers of workflow. It extends [Context] adding
+ * access to the workflow instance key-value state storage and to the [DurablePromise] API.
  *
  * NOTE: This interface MUST NOT be accessed concurrently since it can lead to different orderings
  * of user actions, corrupting the execution of the invocation.
@@ -348,7 +344,7 @@ class RestateRandom(seed: Long, private val syscalls: Syscalls) : Random() {
     return r.nextBits(bitCount)
   }
 
-  /** Generate a UUID */
+  /** Generate a UUID that is stable across retries and replays. */
   fun nextUUID(): UUID {
     return UUID(this.nextLong(), this.nextLong())
   }
@@ -361,7 +357,7 @@ class RestateRandom(seed: Long, private val syscalls: Syscalls) : Random() {
  * The result can be either a success or a failure. In case of a failure, [await] will throw a
  * [dev.restate.sdk.core.TerminalException].
  *
- * @param T type of the awaitable result
+ * @param T type o1f the awaitable result
  */
 sealed interface Awaitable<T> {
   suspend fun await(): T

sdk-api/src/main/java/dev/restate/sdk/ObjectContext.java

@@ -12,8 +12,8 @@
 import org.jspecify.annotations.NonNull;
 
 /**
- * This interface extends {@link Context} adding access to the virtual object instance key-value
- * state storage
+ * This interface can be used only within exclusive handlers of virtual objects. It extends {@link
+ * Context} adding access to the virtual object instance key-value state storage.
  *
  * <p>NOTE: This interface MUST NOT be accessed concurrently since it can lead to different
  * orderings of user actions, corrupting the execution of the invocation.

sdk-api/src/main/java/dev/restate/sdk/RestateRandom.java

@@ -48,7 +48,7 @@ public synchronized void setSeed(long seed) {
   }
 
   /**
-   * @return a UUID generated using this RNG.
+   * @return a UUID generated using this RNG that is stable across retries and replays.
    */
   public UUID nextUUID() {
     return new UUID(this.nextLong(), this.nextLong());

sdk-api/src/main/java/dev/restate/sdk/SharedObjectContext.java

@@ -14,8 +14,8 @@
 import java.util.Optional;
 
 /**
- * This interface extends {@link Context} adding access to the virtual object instance key-value
- * state storage
+ * This interface can be used only within shared handlers of virtual objects. It extends {@link
+ * Context} adding access to the virtual object instance key-value state storage.
  *
  * <p>NOTE: This interface MUST NOT be accessed concurrently since it can lead to different
  * orderings of user actions, corrupting the execution of the invocation.

sdk-api/src/main/java/dev/restate/sdk/SharedWorkflowContext.java

@@ -11,8 +11,9 @@
 import dev.restate.sdk.common.DurablePromiseKey;
 
 /**
- * This interface extends {@link Context} adding access to the workflow instance key-value state
- * storage and to the {@link DurablePromise} API.
+ * This interface can be used only within shared handlers of workflow. It extends {@link Context}
+ * adding access to the workflow instance key-value state storage and to the {@link DurablePromise}
+ * API.
  *
  * <p>NOTE: This interface MUST NOT be accessed concurrently since it can lead to different
  * orderings of user actions, corrupting the execution of the invocation.

sdk-api/src/main/java/dev/restate/sdk/WorkflowContext.java

@@ -9,8 +9,9 @@
 package dev.restate.sdk;
 
 /**
- * This interface extends {@link Context} adding access to the workflow instance key-value state
- * storage and to the {@link DurablePromise} API.
+ * This interface can be used only within workflow handlers of workflow. It extends {@link Context}
+ * adding access to the workflow instance key-value state storage and to the {@link DurablePromise}
+ * API.
  *
  * <p>NOTE: This interface MUST NOT be accessed concurrently since it can lead to different
  * orderings of user actions, corrupting the execution of the invocation.

sdk-common/src/main/java/dev/restate/sdk/annotation/Shared.java

@@ -15,7 +15,12 @@
 
 /**
  * Defines a method as a Shared handler. It can be used only on methods of either {@link
- * VirtualObject} or {@link Workflow}. This implies the annotation {@link Handler}.
+ * VirtualObject} or {@link Workflow}.
+ *
+ * <p>Shared handlers can execute concurrently with the other handlers of Virtual Objects or
+ * Workflows. They can therefore not set or clear state.
+ *
+ * <p>This implies the annotation {@link Handler}.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.SOURCE)