Add experimental flag to some APIs

nexus-sdk/src/main/java/io/nexusrpc/Experimental.java

@@ -0,0 +1,12 @@
+package io.nexusrpc;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation that specifies that an element is experimental, has unstable API or may change without
+ * notice. This annotation is inherited.
+ */
+@Inherited
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.FIELD, ElementType.TYPE, ElementType.METHOD})
+public @interface Experimental {}

nexus-sdk/src/main/java/io/nexusrpc/OperationInfo.java

@@ -4,6 +4,7 @@
 import org.jspecify.annotations.Nullable;
 
 /** Information about an operation. */
+@Experimental
 public class OperationInfo {
   /** Create a builder. */
   public static Builder newBuilder() {

nexus-sdk/src/main/java/io/nexusrpc/handler/Handler.java

@@ -3,6 +3,7 @@
 import io.nexusrpc.OperationException;
 import io.nexusrpc.OperationInfo;
 import io.nexusrpc.OperationStillRunningException;
+import io.nexusrpc.Experimental;
 
 /** Top-level handler for service calls. */
 public interface Handler {
@@ -23,6 +24,7 @@ OperationStartResult<HandlerResultContent> startOperation(
    *
    * <p>If the result is an output stream, it will be closed later by the caller.
    */
+  @Experimental
   HandlerResultContent fetchOperationResult(
       OperationContext context, OperationFetchResultDetails details)
       throws OperationStillRunningException, OperationException, HandlerException;
@@ -31,6 +33,7 @@ HandlerResultContent fetchOperationResult(
    * Fetch information about the asynchronously started operation. See {@link
    * OperationHandler#fetchInfo} for details.
    */
+  @Experimental
   OperationInfo fetchOperationInfo(OperationContext context, OperationFetchInfoDetails details)
       throws HandlerException;
 

nexus-sdk/src/main/java/io/nexusrpc/handler/HandlerResultContent.java

@@ -3,9 +3,12 @@
 import java.io.InputStream;
 import java.util.*;
 import java.util.stream.Collectors;
+
+import io.nexusrpc.Experimental;
 import org.jspecify.annotations.Nullable;
 
 /** Content that can be fixed or streaming as a result of an operation. */
+@Experimental
 public class HandlerResultContent {
   /** Create a builder for content. */
   public static Builder newBuilder() {

nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchInfoDetails.java

@@ -1,9 +1,12 @@
 package io.nexusrpc.handler;
 
 import java.util.Objects;
+
+import io.nexusrpc.Experimental;
 import org.jspecify.annotations.Nullable;
 
 /** Details for handling operation fetch info. */
+@Experimental
 public class OperationFetchInfoDetails {
   /** Create a builder. */
   public static Builder newBuilder() {

nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchResultDetails.java

@@ -1,11 +1,13 @@
 package io.nexusrpc.handler;
 
+import io.nexusrpc.Experimental;
 import io.nexusrpc.OperationStillRunningException;
 import java.time.Duration;
 import java.util.Objects;
 import org.jspecify.annotations.Nullable;
 
 /** Details for handling operation fetch result. */
+@Experimental
 public class OperationFetchResultDetails {
   /** Create a builder. */
   public static Builder newBuilder() {