Skip to content

Updating Java Nexus docs with testing samples #4347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jsundai merged 3 commits into from
Apr 6, 2026
Merged

Updating Java Nexus docs with testing samples #4347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2cef2df
Updating Java Nexus docs with testing samples
Evanthx Mar 26, 2026
fa3430b
Adding snippets
Evanthx Apr 2, 2026
b261247
Merge branch 'main' into nexus-mocking-docs-2
jsundai Apr 6, 2026
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
64 changes: 32 additions & 32 deletions docs/develop/java/nexus/feature-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,10 +97,10 @@ In a polyglot environment, that is where more than one language and SDK is being
This example uses Java classes serialized into JSON.

<!--SNIPSTART samples-java-nexus-service-->
[core/src/main/java/io/temporal/samples/nexus/service/NexusService.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/service/NexusService.java)
[core/src/main/java/io/temporal/samples/nexus/service/SampleNexusService.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/service/SampleNexusService.java)
```java
@Service
public interface NexusService {
public interface SampleNexusService {
enum Language {
EN,
FR,
Expand Down Expand Up @@ -204,23 +204,23 @@ Use `Nexus.getOperationContext().getWorkflowClient(ctx)` to get the Temporal Cli
Implementations can also make other calls, but handlers should be reliable to avoid tripping the [circuit breaker](/nexus/operations#circuit-breaking).

{/* SNIPSTART samples-java-nexus-handler {"selectedLines": ["1-16", "43"]} */}
[core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java)
[core/src/main/java/io/temporal/samples/nexus/handler/SampleNexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/handler/SampleNexusServiceImpl.java)
```java
// To create a service implementation, annotate the class with @ServiceImpl and provide the
// interface that the service implements. The service implementation class should have methods that
// return OperationHandler that correspond to the operations defined in the service interface.
@ServiceImpl(service = NexusService.class)
public class NexusServiceImpl {
@ServiceImpl(service = SampleNexusService.class)
public class SampleNexusServiceImpl {
@OperationImpl
public OperationHandler<NexusService.EchoInput, NexusService.EchoOutput> echo() {
public OperationHandler<SampleNexusService.EchoInput, SampleNexusService.EchoOutput> echo() {
// OperationHandler.sync is a meant for exposing simple RPC handlers.
return OperationHandler.sync(
// The method is for making arbitrary short calls to other services or databases, or
// perform simple computations such as this one. Users can also access a workflow client by
// calling
// Nexus.getOperationContext().getWorkflowClient(ctx) to make arbitrary calls such as
// signaling, querying, or listing workflows.
(ctx, details, input) -> new NexusService.EchoOutput(input.getMessage()));
(ctx, details, input) -> new SampleNexusService.EchoOutput(input.getMessage()));
}
// ...
}
Expand All @@ -238,16 +238,16 @@ All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-o
Use the `WorkflowRunOperation.fromWorkflowMethod` method, which is the easiest way to expose a Workflow as an operation.

<!--SNIPSTART samples-java-nexus-handler {"selectedLines": ["1-5", "18-40"]}-->
[core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/handler/NexusServiceImpl.java)
[core/src/main/java/io/temporal/samples/nexus/handler/SampleNexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexus/handler/SampleNexusServiceImpl.java)
```java
// To create a service implementation, annotate the class with @ServiceImpl and provide the
// interface that the service implements. The service implementation class should have methods that
// return OperationHandler that correspond to the operations defined in the service interface.
@ServiceImpl(service = NexusService.class)
public class NexusServiceImpl {
@ServiceImpl(service = SampleNexusService.class)
public class SampleNexusServiceImpl {
// ...
@OperationImpl
public OperationHandler<NexusService.HelloInput, NexusService.HelloOutput> hello() {
public OperationHandler<SampleNexusService.HelloInput, SampleNexusService.HelloOutput> hello() {
// Use the WorkflowRunOperation.fromWorkflowMethod constructor, which is the easiest
// way to expose a workflow as an operation. To expose a workflow with a different input
// parameters then the operation or from an untyped stub, use the
Expand Down Expand Up @@ -285,27 +285,27 @@ Workflow IDs should typically be business-meaningful IDs and are used to dedupe
A Nexus Operation can only take one input parameter. If you want a Nexus Operation to start a Workflow that takes multiple arguments use the `WorkflowRunOperation.fromWorkflowHandle` method.

<!--SNIPSTART samples-java-nexus-handler-multiargs-->
[core/src/main/java/io/temporal/samples/nexusmultipleargs/handler/NexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexusmultipleargs/handler/NexusServiceImpl.java)
[core/src/main/java/io/temporal/samples/nexusmultipleargs/handler/SampleNexusServiceImpl.java](https://github.com/temporalio/samples-java/blob/nexus-snip-sync/core/src/main/java/io/temporal/samples/nexusmultipleargs/handler/SampleNexusServiceImpl.java)
```java
// To create a service implementation, annotate the class with @ServiceImpl and provide the
// interface that the service implements. The service implementation class should have methods that
// return OperationHandler that correspond to the operations defined in the service interface.
@ServiceImpl(service = NexusService.class)
public class NexusServiceImpl {
@ServiceImpl(service = SampleNexusService.class)
public class SampleNexusServiceImpl {
@OperationImpl
public OperationHandler<NexusService.EchoInput, NexusService.EchoOutput> echo() {
public OperationHandler<SampleNexusService.EchoInput, SampleNexusService.EchoOutput> echo() {
// OperationHandler.sync is a meant for exposing simple RPC handlers.
return OperationHandler.sync(
// The method is for making arbitrary short calls to other services or databases, or
// perform simple computations such as this one. Users can also access a workflow client by
// calling
// Nexus.getOperationContext().getWorkflowClient(ctx) to make arbitrary calls such as
// signaling, querying, or listing workflows.
(ctx, details, input) -> new NexusService.EchoOutput(input.getMessage()));
(ctx, details, input) -> new SampleNexusService.EchoOutput(input.getMessage()));
}

@OperationImpl
public OperationHandler<NexusService.HelloInput, NexusService.HelloOutput> hello() {
public OperationHandler<SampleNexusService.HelloInput, SampleNexusService.HelloOutput> hello() {
// If the operation input parameters are different from the workflow input parameters,
// use the WorkflowRunOperation.fromWorkflowHandler constructor and the appropriate constructor
// method on WorkflowHandle to map the Nexus input to the workflow parameters.
Expand Down Expand Up @@ -363,7 +363,7 @@ public class HandlerWorker {

Worker worker = factory.newWorker(DEFAULT_TASK_QUEUE_NAME);
worker.registerWorkflowImplementationTypes(HelloHandlerWorkflowImpl.class);
worker.registerNexusServiceImplementation(new NexusServiceImpl());
worker.registerNexusServiceImplementation(new SampleNexusServiceImpl());

factory.start();
}
Expand All @@ -380,16 +380,16 @@ Import the Service API package that has the necessary service and operation name
```java
package io.temporal.samples.nexus.caller;

import io.temporal.samples.nexus.service.NexusService;
import io.temporal.samples.nexus.service.SampleNexusService;
import io.temporal.workflow.NexusOperationOptions;
import io.temporal.workflow.NexusServiceOptions;
import io.temporal.workflow.Workflow;
import java.time.Duration;

public class EchoCallerWorkflowImpl implements EchoCallerWorkflow {
NexusService nexusService =
SampleNexusService sampleNexusService =
Workflow.newNexusServiceStub(
NexusService.class,
SampleNexusService.class,
NexusServiceOptions.newBuilder()
.setOperationOptions(
NexusOperationOptions.newBuilder()
Expand All @@ -399,7 +399,7 @@ public class EchoCallerWorkflowImpl implements EchoCallerWorkflow {

@Override
public String echo(String message) {
return nexusService.echo(new NexusService.EchoInput(message)).getMessage();
return sampleNexusService.echo(new SampleNexusService.EchoInput(message)).getMessage();
}
}
```
Expand All @@ -410,17 +410,17 @@ public class EchoCallerWorkflowImpl implements EchoCallerWorkflow {
```java
package io.temporal.samples.nexus.caller;

import io.temporal.samples.nexus.service.NexusService;
import io.temporal.samples.nexus.service.SampleNexusService;
import io.temporal.workflow.NexusOperationHandle;
import io.temporal.workflow.NexusOperationOptions;
import io.temporal.workflow.NexusServiceOptions;
import io.temporal.workflow.Workflow;
import java.time.Duration;

public class HelloCallerWorkflowImpl implements HelloCallerWorkflow {
NexusService nexusService =
SampleNexusService sampleNexusService =
Workflow.newNexusServiceStub(
NexusService.class,
SampleNexusService.class,
NexusServiceOptions.newBuilder()
.setOperationOptions(
NexusOperationOptions.newBuilder()
Expand All @@ -429,10 +429,10 @@ public class HelloCallerWorkflowImpl implements HelloCallerWorkflow {
.build());

@Override
public String hello(String message, NexusService.Language language) {
NexusOperationHandle<NexusService.HelloOutput> handle =
public String hello(String message, SampleNexusService.Language language) {
NexusOperationHandle<SampleNexusService.HelloOutput> handle =
Workflow.startNexusOperation(
nexusService::hello, new NexusService.HelloInput(message, language));
sampleNexusService::hello, new SampleNexusService.HelloInput(message, language));
// Optionally wait for the operation to be started. NexusOperationExecution will contain the
// operation token in case this operation is asynchronous.
handle.getExecution().get();
Expand Down Expand Up @@ -472,7 +472,7 @@ public class CallerWorker {
WorkflowImplementationOptions.newBuilder()
.setNexusServiceOptions(
Collections.singletonMap(
"NexusService",
"SampleNexusService",
NexusServiceOptions.newBuilder().setEndpoint("my-nexus-endpoint-name").build()))
.build(),
EchoCallerWorkflowImpl.class,
Expand All @@ -497,7 +497,7 @@ import io.temporal.api.common.v1.WorkflowExecution;
import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowOptions;
import io.temporal.samples.nexus.options.ClientOptions;
import io.temporal.samples.nexus.service.NexusService;
import io.temporal.samples.nexus.service.SampleNexusService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

Expand All @@ -519,12 +519,12 @@ public class CallerStarter {
logger.info("Workflow result: {}", echoWorkflow.echo("Nexus Echo 👋"));
HelloCallerWorkflow helloWorkflow =
client.newWorkflowStub(HelloCallerWorkflow.class, workflowOptions);
execution = WorkflowClient.start(helloWorkflow::hello, "Nexus", NexusService.Language.EN);
execution = WorkflowClient.start(helloWorkflow::hello, "Nexus", SampleNexusService.Language.EN);
logger.info(
"Started HelloCallerWorkflow workflowId: {} runId: {}",
execution.getWorkflowId(),
execution.getRunId());
logger.info("Workflow result: {}", helloWorkflow.hello("Nexus", NexusService.Language.ES));
logger.info("Workflow result: {}", helloWorkflow.hello("Nexus", SampleNexusService.Language.ES));
}
}
```
Expand Down
Loading
Loading