Javadocs and README (#462)

Author: slinkydeveloper

README.md

@@ -32,7 +32,7 @@ This SDK features:
 
 ### tl;dr Use project templates
 
-To get started, follow the [Java quickstart](https://docs.restate.dev/get_started/quickstart).
+To get started, follow the [Java quickstart](https://docs.restate.dev/get_started/quickstart?sdk=java) or the [Kotlin quickstart](https://docs.restate.dev/get_started/quickstart?sdk=kotlin).
 
 ### Setup a project (Java)
 
@@ -42,11 +42,15 @@ Scaffold a project using the build tool of your choice. For example, with Gradle
 gradle init --type java-application
 ```
 
-Add the runtime dependency [sdk-api](sdk-api) and the annotation processor dependency [sdk-api-gen](sdk-api-gen):
+Add the annotation processor dependency [sdk-api-gen](sdk-api-gen), and then, depending on whether you want to deploy using HTTP or Lambda, use the appropriate dependency:
 
-```
-annotationProcessor("dev.restate:sdk-api-gen:1.2.0")
-implementation("dev.restate:sdk-api:1.2.0")
+```kotlin
+annotationProcessor("dev.restate:sdk-api-gen:2.0.0")
+
+// For HTTP services
+implementation("dev.restate:sdk-java-http:2.0.0")
+// For Lambda services
+// implementation("dev.restate:sdk-java-lambda:2.0.0")
 ```
 
 ### Setup a project (Kotlin)
@@ -65,11 +69,15 @@ plugins {
 }
 ```
 
-Add the runtime dependency [sdk-api-kotlin](sdk-api-kotlin) and the ksp dependency [sdk-api-gen](sdk-api-kotlin-gen):
+Add the ksp dependency [sdk-api-gen](sdk-api-kotlin-gen), and then, depending on whether you want to deploy using HTTP or Lambda, use the appropriate dependency:
 
-```
-ksp("dev.restate:sdk-api-kotlin-gen:1.2.0")
-implementation("dev.restate:sdk-api-kotlin:1.2.0")
+```kotlin
+ksp("dev.restate:sdk-api-kotlin-gen:2.0.0")
+
+// For HTTP services
+implementation("dev.restate:sdk-kotlin-http:2.0.0")
+// For Lambda services
+// implementation("dev.restate:sdk-kotlin-lambda:2.0.0")
 ```
 
 ### Implement your first Restate component (Java)
@@ -80,13 +88,12 @@ Implement your first virtual object in a new class, for example:
 import dev.restate.sdk.ObjectContext;
 import dev.restate.sdk.annotation.Handler;
 import dev.restate.sdk.annotation.VirtualObject;
-import dev.restate.sdk.JsonSerdes;
 import dev.restate.sdk.common.StateKey;
 
 @VirtualObject
 public class Greeter {
 
-  private static final StateKey<Long> COUNT = StateKey.of("total", JsonSerdes.LONG);
+  private static final StateKey<Long> COUNT = StateKey.of("total", Long.class);
 
   @Handler
   public String greet(ObjectContext ctx, String name) {
@@ -98,31 +105,20 @@ public class Greeter {
 }
 ```
 
-When using composite types/POJOs for input/output, [Jackson Databind](https://github.com/FasterXML/jackson) will be used. The Jackson dependency is not automatically included, you must add it with [`sdk-serde-jackson`](sdk-serde-jackson):
-
-```
-implementation("dev.restate:sdk-serde-jackson:1.2.0")
-```
-
-If you want to store types/POJOs in state, use `JacksonSerdes`:
-
-```java
-private static final StateKey<Person> PERSON = StateKey.of("person", JacksonSerdes.of(Person.class));
-```
+By default, [Jackson Databind](https://github.com/FasterXML/jackson) will be used for serialization/deserialization. You can override this configuration by customizing the `SerdeFactory`, check out the javadocs for more details.
 
 ### Implement your first Restate component (Kotlin)
 
 Implement your first virtual object in a new class, for example:
 
 ```kotlin
-import dev.restate.sdk.annotation.Handler
-import dev.restate.sdk.annotation.VirtualObject
+import dev.restate.sdk.annotation.*
 import dev.restate.sdk.kotlin.*
 
 @VirtualObject
 class Greeter {
   companion object {
-    private val COUNT = KtStateKey.json<Long>("total")
+    private val COUNT = stateKey("total")
   }
 
   @Handler
@@ -134,33 +130,29 @@ class Greeter {
 }
 ```
 
-When using composite data types for input/output, [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization?tab=readme-ov-file#setup) will be used.
+By default [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization?tab=readme-ov-file#setup) will be used for serialization/deserialization. You can override this configuration by customizing the `SerdeFactory`, check out the javadocs for more details.
 
 ### Deploy the service (HTTP Server)
 
-To deploy the Restate service as HTTP server, add [`sdk-http-vertx`](sdk-http-vertx) to the dependencies. For example, in Gradle:
-
-```
-implementation("dev.restate:sdk-http-vertx:1.2.0")
-```
-
-To deploy the service, add the following code to the `main`. For example in Java:
+To deploy the Restate service as HTTP server, add the following code to the `main`. For example in Java:
 
 ```java
 public static void main(String[] args) {
-  RestateHttpEndpointBuilder.builder()
-        .bind(new Greeter())
-        .buildAndListen();
+  RestateHttpServer.listen(
+    Endpoint.bind(new Greeter())
+  );
 }
 ```
 
 In Kotlin:
 
 ```kotlin
 fun main() {
-  RestateHttpEndpointBuilder.builder()
-          .bind(Greeter())
-          .buildAndListen()
+  RestateHttpServer.listen(
+    endpoint {
+      bind(Greeter())
+    }
+  )
 }
 ```
 
@@ -172,13 +164,8 @@ gradle run
 
 ### Deploy the service (AWS Lambda)
 
-To deploy the Restate service as Lambda, add [`sdk-lambda`](sdk-lambda) to the dependencies. For example, in Gradle:
-
-```
-implementation("dev.restate:sdk-lambda:1.2.0")
-```
-
-Configure the build tool to generate Fat-JARs, which are required by AWS Lambda to correctly load the JAR. For example, using Gradle:
+To deploy the Restate service as Lambda, configure the build tool to generate Fat-JARs, which are required by AWS Lambda to correctly load the JAR.
+For example, using Gradle:
 
 ```
 plugins {
@@ -194,7 +181,7 @@ Now create the Lambda handler invoking the service. For example, in Java:
 ```java
 public class MyLambdaHandler extends BaseRestateLambdaHandler {
   @Override
-  public void register(RestateLambdaEndpointBuilder builder) {
+  public void register(Endpoint.Builder builder) {
     builder.bind(new Greeter());
   }
 }
@@ -204,7 +191,7 @@ In Kotlin:
 
 ```kotlin
 class MyLambdaHandler : BaseRestateLambdaHandler {
-  override fun register(builder: RestateLambdaEndpointBuilder) {
+  override fun register(builder: Endpoint.Builder) {
     builder.bind(Greeter())
   }
 }
@@ -222,13 +209,7 @@ You can now upload the generated Jar in AWS Lambda, and configure `MyLambdaHandl
 
 #### Logging
 
-The SDK uses log4j2 as logging facade. To enable logging, add the `log4j2` implementation to the dependencies:
-
-```
-implementation("org.apache.logging.log4j:log4j-core:2.23.0")
-```
-
-And configure the logging adding the file `resources/log4j2.properties`:
+The SDK uses log4j2 as logging facade, to configure it add the file `resources/log4j2.properties`:
 
 ```
 # Set to debug or trace if log4j initialization is failing
@@ -265,13 +246,15 @@ The SDK injects the following additional metadata to the logging context that ca
 * `restateInvocationId`: Invocation identifier, to be used in Restate observability tools. See https://docs.restate.dev/operate/invocation#invocation-identifier.
 * `restateInvocationStatus`: Invocation status, can be `WAITING_START`, `REPLAYING`, `PROCESSING`, `CLOSED`.
 
+The dependencies `sdk-java-http`, `sdk-java-lambda`, `sdk-kotlin-http` and `sdk-kotlin-lambda` bring in `log4j-core` by default, but you can easily exclude/override that if you need to.
+
 When assembling fat-jars, make sure to enable merging META-INF/services files. For more info, see https://github.com/apache/logging-log4j2/issues/2099.
 
 #### Tracing with OpenTelemetry
 
-The SDK can generate additional tracing information on top of what Restate already publishes. See https://docs.restate.dev/operate/monitoring/tracing to configure Restate tracing.
+The SDK automatically propagates the OpenTelemetry `Context` from the `restate-server` into your handler. You can use that to create custom spans.
 
-You can the additional SDK tracing information by configuring the `OpenTelemetry` in the `RestateHttpEndpointBuilder`/`LambdaRestateServer`.
+To configure the `OpenTelemetry` that should be used by the SDK to publish traces, configure it in the `Endpoint.Builder` object.
 
 For example, to set up tracing using environment variables, add the following modules to your dependencies:
 
@@ -280,7 +263,7 @@ implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.38.
 implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.38.0")
 ```
 
-And then configure it in the Restate builder:
+And then configure it in the endpoint builder:
 
 ```java
 .withOpenTelemetry(AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk())
@@ -294,7 +277,9 @@ export OTEL_TRACES_SAMPLER=always_on
 export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:14250
 ```
 
-Please refer to the [Opentelemetry manual instrumentation documentation](https://opentelemetry.io/docs/instrumentation/java/manual/#manual-instrumentation-setup) and the [autoconfigure documentation](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md) for more info.
+Please refer to the [Opentelemetry manual instrumentation documentation](https://opentelemetry.io/docs/instrumentation/java/manual/#manual-instrumentation-setup) and the [autoconfigure documentation](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md) for more info. 
+
+See https://docs.restate.dev/operate/monitoring/tracing to configure Restate tracing.
 
 ## Versions
 
@@ -338,9 +323,3 @@ To publish local snapshots of the project:
 ```shell
 ./gradlew -DskipSigning publishToMavenLocal
 ```
-
-To update the [`service-protocol`](https://github.com/restatedev/service-protocol/) git subtree:
-
-```shell
-git subtree pull --prefix sdk-core/src/main/service-protocol/ git@github.com:restatedev/service-protocol.git main --squash
-```

common/build.gradle.kts

@@ -13,3 +13,5 @@ dependencies {
   testImplementation(libs.junit.jupiter)
   testImplementation(libs.assertj)
 }
+
+tasks.withType<Javadoc> { isFailOnError = false }

common/src/main/java/dev/restate/common/Request.java

@@ -16,6 +16,12 @@
 import java.util.Objects;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Object encapsulating request parameters.
+ *
+ * @param <Req> the request type
+ * @param <Res> the response type
+ */
 public sealed class Request<Req, Res> permits SendRequest {
 
   private final Target target;
@@ -67,21 +73,25 @@ public Map<String, String> headers() {
     return headers;
   }
 
+  /**
+   * Create a new {@link Builder} for the given {@link Target}, request and response {@link TypeTag}
+   * and {@code request} object.
+   *
+   * <p>When using the annotation processor, you can rely on the generated {@code Client} class or
+   * the generated {@code Requests} class, instead of manually using this builder.
+   */
   public static <Req, Res> Builder<Req, Res> of(
       Target target, TypeTag<Req> reqTypeTag, TypeTag<Res> resTypeTag, Req request) {
     return new Builder<>(target, reqTypeTag, resTypeTag, request);
   }
 
-  public static <Req> Builder<Req, Void> withNoResponseBody(
-      Target target, TypeTag<Req> reqTypeTag, Req request) {
-    return new Builder<>(target, reqTypeTag, Serde.VOID, request);
-  }
-
-  public static <Res> Builder<Void, Res> withNoRequestBody(Target target, TypeTag<Res> resTypeTag) {
-    return new Builder<>(target, Serde.VOID, resTypeTag, null);
-  }
-
-  public static Builder<byte[], byte[]> ofRaw(Target target, byte[] request) {
+  /**
+   * Create a new {@link Builder} for the given {@link Target} and {@code request} byte array.
+   *
+   * <p>When using the annotation processor, you can rely on the generated {@code Client} class or
+   * the generated {@code Requests} class, instead of manually using this builder.
+   */
+  public static Builder<byte[], byte[]> of(Target target, byte[] request) {
     return new Builder<>(target, TypeTag.of(Serde.RAW), TypeTag.of(Serde.RAW), request);
   }
 
@@ -153,6 +163,9 @@ public Builder<Req, Res> headers(Map<String, String> newHeaders) {
       return idempotencyKey;
     }
 
+    /**
+     * @param idempotencyKey Idempotency key to attach in the request.
+     */
     public Builder<Req, Res> setIdempotencyKey(@Nullable String idempotencyKey) {
       return idempotencyKey(idempotencyKey);
     }
@@ -161,20 +174,32 @@ public Builder<Req, Res> setIdempotencyKey(@Nullable String idempotencyKey) {
       return headers;
     }
 
+    /**
+     * @param headers headers to send together with the request.
+     */
     public Builder<Req, Res> setHeaders(@Nullable Map<String, String> headers) {
       return headers(headers);
     }
 
+    /**
+     * @return build the request as send request.
+     */
     public SendRequest<Req, Res> asSend() {
       return new SendRequest<>(
           target, reqTypeTag, resTypeTag, request, idempotencyKey, headers, null);
     }
 
+    /**
+     * @return build the request as send request delayed by the given {@code delay}.
+     */
     public SendRequest<Req, Res> asSendDelayed(Duration delay) {
       return new SendRequest<>(
           target, reqTypeTag, resTypeTag, request, idempotencyKey, headers, delay);
     }
 
+    /**
+     * @return build the request as send request.
+     */
     public Request<Req, Res> build() {
       return new Request<>(
           this.target,
@@ -196,11 +221,17 @@ public Builder<Req, Res> toBuilder() {
         this.headers);
   }
 
+  /**
+   * @return copy this request as send.
+   */
   public SendRequest<Req, Res> asSend() {
     return new SendRequest<>(
         target, reqTypeTag, resTypeTag, request, idempotencyKey, headers, null);
   }
 
+  /**
+   * @return copy this request as send request delayed by the given {@code delay}.
+   */
   public SendRequest<Req, Res> asSendDelayed(Duration delay) {
     return new SendRequest<>(
         target, reqTypeTag, resTypeTag, request, idempotencyKey, headers, delay);

common/src/main/java/dev/restate/common/SendRequest.java

@@ -14,6 +14,13 @@
 import java.util.Objects;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Object encapsulating request parameters, including the parameters exclusive to one way calls
+ * (also referred as send).
+ *
+ * @param <Req> the request type
+ * @param <Res> the response type
+ */
 public final class SendRequest<Req, Res> extends Request<Req, Res> {
 
   @Nullable private final Duration delay;

common/src/main/java/dev/restate/common/Slice.java

@@ -11,6 +11,7 @@
 import java.nio.ByteBuffer;
 import java.nio.charset.StandardCharsets;
 
+/** Wrapper type for byte slices. */
 public interface Slice {
 
   int readableBytes();
@@ -27,6 +28,7 @@ public interface Slice {
 
   byte[] toByteArray();
 
+  /** Wrap a {@link ByteBuffer}. This will not copy the buffer. */
   static Slice wrap(ByteBuffer byteBuffer) {
     return new Slice() {
       @Override