Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ to docs, or any other relevant information.
- Experimental Event Groups associate related workflow commands so their history events can be
viewed together. Create a group with `Workflow.newEventGroup` and attach it by calling
`addEventGroups` on the command's options.
- `@TemporalOperation` methods can return their output directly for synchronous completion.
Existing methods returning `TemporalOperationResult`, including asynchronous results, remain
supported.

### Changed
- Updated Cloud API bindings to v0.27.0, including opt-in user group memberships, projects,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,14 +84,6 @@ private static void validateSignature(Method method) {
+ " must accept (TemporalNexusClient, I); got "
+ describeSignature(method));
}
if (!TemporalOperationResult.class.equals(method.getReturnType())) {
throw new IllegalArgumentException(
"@TemporalOperation method "
+ method.getName()
+ " must return TemporalOperationResult<?>; got "
+ method.getGenericReturnType().getTypeName()
+ ". Use @OperationImpl for custom handler shapes.");
}
for (Class<?> declared : method.getExceptionTypes()) {
if (!RuntimeException.class.isAssignableFrom(declared)
&& !Error.class.isAssignableFrom(declared)
Expand Down Expand Up @@ -119,22 +111,24 @@ private static void validateTypes(Method method, OperationDefinition operationDe
+ " but got "
+ declaredInputType.getTypeName());
}
Type returnType = method.getGenericReturnType();
if (!(returnType instanceof ParameterizedType)) {
throw new IllegalArgumentException(
"@TemporalOperation method "
+ method.getName()
+ " must use parameterized TemporalOperationResult<R>, not the raw type.");
Type resultType = method.getGenericReturnType();
if (method.getReturnType() == TemporalOperationResult.class) {
if (!(resultType instanceof ParameterizedType)) {
throw new IllegalArgumentException(
"@TemporalOperation method "
+ method.getName()
+ " must use parameterized TemporalOperationResult<R>, not the raw type.");
}
resultType = ((ParameterizedType) resultType).getActualTypeArguments()[0];
}
Type resultTypeArg = ((ParameterizedType) returnType).getActualTypeArguments()[0];
if (!typesMatch(resultTypeArg, operationDefinition.getOutputType())) {
if (!typesMatch(resultType, operationDefinition.getOutputType())) {
throw new IllegalArgumentException(
"@TemporalOperation method "
+ method.getName()
+ " output type mismatch: expected "
+ operationDefinition.getOutputType().getTypeName()
+ " but got "
+ resultTypeArg.getTypeName());
+ resultType.getTypeName());
}
}

Expand All @@ -143,7 +137,12 @@ private static void validateTypes(Method method, OperationDefinition operationDe
static TemporalOperationResult<Object> invokeStartHandler(
MethodHandle handle, TemporalNexusClient client, Object input) throws OperationException {
try {
return (TemporalOperationResult<Object>) handle.invoke(client, input);
Object result = handle.invoke(client, input);
// Use the declared return type so null direct results are wrapped, while existing wrapped
// handlers retain their behavior (including asynchronous results).
return TemporalOperationResult.class.equals(handle.type().returnType())
? (TemporalOperationResult<Object>) result
: TemporalOperationResult.sync(result);
} catch (RuntimeException | Error | OperationException e) {
// HandlerException is a RuntimeException and falls into the RuntimeException arm.
throw e;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,17 +35,16 @@
* }
* }</pre>
*
* <p>For synchronous operations, use {@link #getWorkflowClient()} directly and return a {@link
* TemporalOperationResult#sync} result. For example, to send a signal:
* <p>For synchronous {@link TemporalOperation} methods, use {@link #getWorkflowClient()} directly
* and return the output value, or use {@code void} when there is no output. Explicit {@link
* TemporalOperationResult#sync} results are also supported. For example, to send a signal:
*
* <pre>{@code
* @TemporalOperation
* public TemporalOperationResult<Void> cancelOrder(
* TemporalNexusClient client, CancelOrderInput input) {
* public void cancelOrder(TemporalNexusClient client, CancelOrderInput input) {
* client.getWorkflowClient()
* .newUntypedWorkflowStub("order-" + input.getOrderId())
* .signal("requestCancellation", input);
* return TemporalOperationResult.sync(null);
* }
* }</pre>
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
* <ul>
* <li>be {@code public},
* <li>accept exactly two parameters: {@link TemporalNexusClient} and the operation input type,
* <li>return {@link TemporalOperationResult}.
* <li>return the operation output type directly for synchronous completion, or {@link
* TemporalOperationResult} for explicit synchronous or asynchronous completion.
* </ul>
*
* <p>Workflow-run example:
Expand All @@ -41,6 +42,17 @@
* }
* }</pre>
*
* <p>A synchronous operation can return its output directly. The SDK wraps the returned value in
* {@link TemporalOperationResult#sync(Object)} internally. The returned value may be null. A {@code
* void} method is supported for an operation with no output.
*
* <pre>{@code
* @TemporalOperation
* public Greeting greet(TemporalNexusClient client, GreetingInput input) {
* return new Greeting("Hello, " + input.getName());
* }
* }</pre>
*
* <p>Access information about the current invocation through {@link NexusOperationContext#getInfo()
* Nexus.getOperationContext().getInfo()}, including its cancellation token and {@linkplain
* NexusOperationInfo#getRequestId() start request ID}.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,68 @@ public void happyPath_voidInputAndOutput() {
TemporalOperationProcessor.process(new VoidIo());
}

@Test
public void directReturns_registerAndWrapResults() throws Exception {
DirectReturn handler = new DirectReturn();
TemporalOperationProcessor.process(handler);
TemporalOperationResult<Object> result = invoke(handler, String.class, "direct");
Assert.assertTrue(result.isSync());
Assert.assertEquals("direct", result.getSyncResult());
}

@Test
public void directReturns_wrapNullAsSuccessfulSyncResult() throws Exception {
TemporalOperationResult<Object> result = invoke(new DirectReturn(), String.class, null);
Assert.assertNotNull(result);
Assert.assertTrue(result.isSync());
Assert.assertNull(result.getSyncResult());
}

@Test
public void directReturns_preserveCompositeGenericValidation() {
TemporalOperationProcessor.process(new DirectComposite());
IllegalArgumentException e =
assertInvalid(() -> TemporalOperationProcessor.process(new DirectCompositeBadOutput()));
Assert.assertTrue(e.getMessage(), e.getMessage().contains("output type mismatch"));
}

@Test
public void directReturns_supportPrimitiveAndVoidResults() throws Exception {
DirectPrimitive primitive = new DirectPrimitive();
TemporalOperationProcessor.process(primitive);
Assert.assertEquals(42, invoke(primitive, Integer.class, 42).getSyncResult());

DirectVoid noOutput = new DirectVoid();
TemporalOperationProcessor.process(noOutput);
TemporalOperationResult<Object> result = invoke(noOutput, Void.class, null);
Assert.assertTrue(result.isSync());
Assert.assertNull(result.getSyncResult());
Assert.assertTrue(noOutput.invoked);
}

@Test
public void directReturns_propagateOperationExceptionUnwrapped() throws Exception {
DirectFailure handler = new DirectFailure();
TemporalOperationProcessor.process(handler);
io.nexusrpc.OperationException thrown =
Assert.assertThrows(
io.nexusrpc.OperationException.class, () -> invoke(handler, String.class, "input"));
Assert.assertSame(handler.failure, thrown);
}

@Test
public void wrappedReturns_preserveSyncAndAsyncResults() throws Exception {
for (TemporalOperationResult<String> expected :
java.util.Arrays.asList(
TemporalOperationResult.sync("wrapped"),
TemporalOperationResult.<String>sync(null),
TemporalOperationResult.<String>async("token"))) {
WrappedReturn handler = new WrappedReturn(expected);
TemporalOperationProcessor.process(handler);
Assert.assertSame(expected, invoke(handler, String.class, "input"));
}
}

@Test
public void rejects_compositeGenericInputMismatch() {
IllegalArgumentException e =
Expand Down Expand Up @@ -116,6 +178,7 @@ public void invokeStartHandler_propagatesRuntimeExceptionUnwrapped() throws Exce
Assert.assertThrows(
IllegalStateException.class,
() -> TemporalOperationProcessor.invokeStartHandler(handle, null, "in"));
Assert.assertSame(instance.failure, thrown);
Assert.assertEquals("user-thrown", thrown.getMessage());
// First user frame is at the top — no reflective wrapper class in between.
Assert.assertEquals(ThrowingHandler.class.getName(), thrown.getStackTrace()[0].getClassName());
Expand All @@ -125,8 +188,7 @@ public void invokeStartHandler_propagatesRuntimeExceptionUnwrapped() throws Exce
public void rejects_badReturnType() {
IllegalArgumentException e =
assertInvalid(() -> TemporalOperationProcessor.process(new BadReturnType()));
Assert.assertTrue(
e.getMessage(), e.getMessage().contains("must return TemporalOperationResult"));
Assert.assertTrue(e.getMessage(), e.getMessage().contains("output type mismatch"));
}

@Test
Expand Down Expand Up @@ -173,6 +235,14 @@ private static IllegalArgumentException assertInvalid(Runnable action) {
return (IllegalArgumentException) wrapper.getCause();
}

private static TemporalOperationResult<Object> invoke(
Object instance, Class<?> inputType, Object input) throws Exception {
java.lang.reflect.Method method =
instance.getClass().getMethod("op", TemporalNexusClient.class, inputType);
return TemporalOperationProcessor.invokeStartHandler(
java.lang.invoke.MethodHandles.lookup().unreflect(method).bindTo(instance), null, input);
}

// ----- Fixtures -----

@ServiceImpl(service = SingleOpService.class)
Expand All @@ -185,12 +255,88 @@ public TemporalOperationResult<String> op(TemporalNexusClient client, String inp

@ServiceImpl(service = SingleOpService.class)
public static class BadReturnType {
@TemporalOperation
public Integer op(TemporalNexusClient client, String input) {
return 42;
}
}

@ServiceImpl(service = SingleOpService.class)
public static class DirectReturn {
@TemporalOperation
public String op(TemporalNexusClient client, String input) {
return input;
}
}

@ServiceImpl(service = CompositeGenericService.class)
public static class DirectComposite {
@TemporalOperation
public java.util.List<String> compose(
TemporalNexusClient client, java.util.Map<String, Integer> input) {
return java.util.Collections.emptyList();
}
}

@ServiceImpl(service = CompositeGenericService.class)
public static class DirectCompositeBadOutput {
@TemporalOperation
public java.util.List<Integer> compose(
TemporalNexusClient client, java.util.Map<String, Integer> input) {
return java.util.Collections.emptyList();
}
}

@Service
public interface PrimitiveService {
@Operation
Integer op(Integer input);
}

@ServiceImpl(service = PrimitiveService.class)
public static class DirectPrimitive {
@TemporalOperation
public int op(TemporalNexusClient client, Integer input) {
return input;
}
}

@ServiceImpl(service = VoidIoService.class)
public static class DirectVoid {
boolean invoked;

@TemporalOperation
public void op(TemporalNexusClient client, Void input) {
invoked = true;
}
}

@ServiceImpl(service = SingleOpService.class)
public static class WrappedReturn {
private final TemporalOperationResult<String> result;

WrappedReturn(TemporalOperationResult<String> result) {
this.result = result;
}

@TemporalOperation
public TemporalOperationResult<String> op(TemporalNexusClient client, String input) {
return result;
}
}

@ServiceImpl(service = SingleOpService.class)
public static class DirectFailure {
final io.nexusrpc.OperationException failure =
io.nexusrpc.OperationException.failed(new IllegalArgumentException("direct failure"));

@TemporalOperation
public String op(TemporalNexusClient client, String input)
throws io.nexusrpc.OperationException {
throw failure;
}
}

@ServiceImpl(service = SingleOpService.class)
public static class BadArity {
@TemporalOperation
Expand Down Expand Up @@ -269,9 +415,11 @@ public TemporalOperationResult<String> op(TemporalNexusClient client, String inp

@ServiceImpl(service = SingleOpService.class)
public static class ThrowingHandler {
final IllegalStateException failure = new IllegalStateException("user-thrown");

@TemporalOperation
public TemporalOperationResult<String> op(TemporalNexusClient client, String input) {
throw new IllegalStateException("user-thrown");
throw failure;
}
}

Expand Down
Loading
Loading