From 8e650d798e7ba5e91b8bc24ad3f6487a8c633039 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Wed, 4 Jun 2025 15:36:21 -0700 Subject: [PATCH 1/2] Add experimental flag to some APIs --- .../src/main/java/io/nexusrpc/Experimental.java | 12 ++++++++++++ .../src/main/java/io/nexusrpc/OperationInfo.java | 1 + .../src/main/java/io/nexusrpc/handler/Handler.java | 3 +++ .../io/nexusrpc/handler/HandlerResultContent.java | 3 +++ .../nexusrpc/handler/OperationFetchInfoDetails.java | 3 +++ .../handler/OperationFetchResultDetails.java | 2 ++ 6 files changed, 24 insertions(+) create mode 100644 nexus-sdk/src/main/java/io/nexusrpc/Experimental.java diff --git a/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java b/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java new file mode 100644 index 0000000..c42d03d --- /dev/null +++ b/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.RUNTIME) +@Target({ElementType.FIELD, ElementType.TYPE, ElementType.METHOD}) +public @interface Experimental {} diff --git a/nexus-sdk/src/main/java/io/nexusrpc/OperationInfo.java b/nexus-sdk/src/main/java/io/nexusrpc/OperationInfo.java index 860f1b3..20c0963 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/OperationInfo.java +++ b/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() { diff --git a/nexus-sdk/src/main/java/io/nexusrpc/handler/Handler.java b/nexus-sdk/src/main/java/io/nexusrpc/handler/Handler.java index 8c1f804..5d9595c 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/handler/Handler.java +++ b/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 startOperation( * *

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; diff --git a/nexus-sdk/src/main/java/io/nexusrpc/handler/HandlerResultContent.java b/nexus-sdk/src/main/java/io/nexusrpc/handler/HandlerResultContent.java index f4902f7..ca84e96 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/handler/HandlerResultContent.java +++ b/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() { diff --git a/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchInfoDetails.java b/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchInfoDetails.java index 6c8aa2a..5fa72d4 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchInfoDetails.java +++ b/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() { diff --git a/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchResultDetails.java b/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchResultDetails.java index e840a1c..2aab5a6 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/handler/OperationFetchResultDetails.java +++ b/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() { From 8fd156c6c15744576fdefe9a7e33523f0362937f Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Sat, 7 Jun 2025 17:48:02 -0700 Subject: [PATCH 2/2] Change retention to class --- nexus-sdk/src/main/java/io/nexusrpc/Experimental.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java b/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java index c42d03d..d305654 100644 --- a/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java +++ b/nexus-sdk/src/main/java/io/nexusrpc/Experimental.java @@ -7,6 +7,6 @@ * notice. This annotation is inherited. */ @Inherited -@Retention(RetentionPolicy.RUNTIME) +@Retention(RetentionPolicy.CLASS) @Target({ElementType.FIELD, ElementType.TYPE, ElementType.METHOD}) public @interface Experimental {}