Skip to main content

Microservice Development Walkthrough with Nexus in Java

View Markdown
Currently in: Pre-release

This walkthrough uses the new Nexus developer experience: pre-release APIs for the Temporal Operation Handler and Nexus Standalone Activity. These APIs are experimental and subject to change.

This walkthrough builds one Nexus Service from nothing to a complete API, adding one Nexus capability at each step.

A Nexus Service is a contract that one team publishes and other teams call across Namespace boundaries, without sharing code or a deployment.

The walkthrough problem​

A purchase request needs approval before it can proceed. One team owns that approval process, and other teams across the company need to start an approval and find out how it went, without taking on that team's code or running it themselves. That split is what makes this a Nexus problem: the approval team publishes a Service, and everyone else calls it.

Approval is slow and human-driven, so the system has to survive a wait of minutes or weeks. While a request is pending, other systems might nudge the approver or attach information to the request. When a decision arrives, the requesting system needs the outcome.

The Service needs to:

  • Start an approval and eventually return APPROVED or DENIED
  • Accept a nudge that asks the approver again, and count how many have been sent
  • Accept supporting information for a purchase, whether or not its approval exists yet
  • Accept a decision and confirm it was recorded
  • Send a notification when the decision is final

Each of those needs a different Nexus capability, introduced one step at a time.

One contract, every language​

This walkthrough builds the Service in Java. NexGen generates code from the same contract in Go, Python, and TypeScript, and the reasoning at each step is the same in all of them.

The Java sample is nexuswalkthrough.

Any caller can call any handler, because the contract is the only thing the two sides share. A Go caller can drive a Python handler, and a TypeScript caller can drive the Java handler built here. Step 6 builds the Java caller.

How to follow along​

Three kinds of code block appear in this walkthrough. Hover over a block to get a copy icon.

A terminal window is a command to run. Run this one now to confirm you have Temporal CLI 1.9.1 or later:

Run: check your CLI version
temporal --version

Run every terminal command, in order, or later steps may fail.

A block headed by a file path is sample code to read. You don't need to type it: it's already in the sample codebase, and the file name links to the file.

core/src/main/java/io/temporal/samples/nexuswalkthrough/handler/ApprovalWorkflowId.java

  public static String forItem(String itemId) {
    return "approval-" + itemId;
  }

Command output appears in a plain block with no header:

temporal version 1.9.1 (Server 1.32.0, UI 2.54.1)

Before you start​

1. Clone the sample project​

This walkthrough runs inside a clone of the samples-java repository. Every command and file path is relative to the repository root.

Run: clone the sample
git clone https://github.com/temporalio/samples-java.git
cd samples-java

The sample is the finished Service. Each step shows the code it introduces and then runs it.

2. Check your CLI version​

This walkthrough needs Temporal CLI 1.9.1 or later and its development server. Each step runs an Operation from the command line with temporal nexus operation, so check that your CLI has those commands before you start. If temporal nexus --help doesn't list operation, upgrade.

The development server also needs two dynamic config values that are off by default. Step 4 sets them, and Debugging and tips shows what each one fails with when it's missing.

3. Run each Operation as you build it​

Step 4 starts the development server, and step 5 makes the Service reachable. From then on, each step that adds an Operation ends by running it, so you see a result before moving on. Those runs use temporal nexus operation, which starts a Standalone Nexus Operation: the CLI is the caller, so you need no caller Workflow or caller Worker until step 6.

New to Nexus? Read Nexus Services and Nexus Operations, or work through the shorter Java Nexus quickstart.

Start the walkthrough​

Ten steps build the Service, and the sidebar lists them all. Work through them in order, because each one runs against what the last one left running.

Step 1: Define the data contract

The five Operations callers need, and the types they carry.

→

Debugging and tips collects the failures each step can produce, indexed by symptom. Keep it open in a tab.