# Microservice Development Walkthrough with Nexus in Java

> For the complete documentation index, see [llms.txt](https://docs.temporal.io/llms.txt).
> Any documentation page is available as raw Markdown by appending `.md` to its URL.
> For related questions, query https://docs.temporal.io/api/retrieve?q=<question>&jtb=<job-to-be-done>&src=md-page&agent=<your-name> (no auth; returns JSON `{content, source_url, page_url}`, with `source_url` pointing to Markdown for docs pages). Don't include personal data or credentials.

> Build a Nexus Service end to end in Java, starting from a data contract and adding one Nexus capability at a time to solve a purchase approval problem.

> **⚠️ Currently in: Pre-release:**
> This walkthrough uses the new Nexus developer experience: pre-release APIs for the [Temporal Operation Handler](/nexus/temporal-operation-handler) and [Nexus Standalone Activity](/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](/evaluate/features/nexus) is a contract that one team publishes and other teams call across [Namespace](/namespaces) 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](/nexus/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](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/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](/develop/java/nexus/development-walkthrough/call-the-service) 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](/cli) 1.9.1 or later:

```bash title="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](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/nexuswalkthrough), and the file name links to the file.

[core/src/main/java/io/temporal/samples/nexuswalkthrough/handler/ApprovalWorkflowId.java](https://github.com/temporalio/samples-java/blob/main/core/src/main/java/io/temporal/samples/nexuswalkthrough/handler/ApprovalWorkflowId.java)

```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](https://github.com/temporalio/samples-java)
repository. Every command and file path is relative to the repository root.

```bash title="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](/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](/develop/java/nexus/development-walkthrough/implement-the-service#start-the-development-server)
sets them, and [Debugging and tips](/develop/java/nexus/development-walkthrough/debugging-and-tips)
shows what each one fails with when it's missing.

### 3. Run each Operation as you build it 

[Step 4](/develop/java/nexus/development-walkthrough/implement-the-service)
starts the development server, and [step 5](/develop/java/nexus/development-walkthrough/publish-in-nexus)
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](/standalone-nexus-operation): the CLI is the caller, so you need no
caller Workflow or caller Worker until [step 6](/develop/java/nexus/development-walkthrough/call-the-service).

New to Nexus? Read [Nexus Services](/nexus/services) and [Nexus Operations](/nexus/operations), or work through the shorter [Java Nexus quickstart](/develop/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](/develop/java/nexus/development-walkthrough/define-the-data-contract): The five Operations callers need, and the types they carry.

[Debugging and tips](/develop/java/nexus/development-walkthrough/debugging-and-tips) collects the
failures each step can produce, indexed by symptom. Keep it open in a tab.