Skip to content
← All labs
Kept for this browser session. No learning progress is saved.

Java foundations · Local Java 21 lab

Messaging with Apache Artemis

An online shop accepts orders while billing and shipping work independently. Follow an order through queues, events and a controlled failure, using evidence from your own local broker.

3 stations3 hours 45 minutesContent v1.0.1

Prepare your environment

The trainer can distribute a verified runtime ZIP and JDK 21 before the session. Extract both and follow RUN.md; local demonstrations need no Maven or network. Editing exercises needs the full source and a build environment. An offline source build additionally requires a prepared Maven Wrapper distribution and dependency/plugin cache. A runtime ZIP alone cannot compile exercises.

The training repository is public, including exercises and worked solutions. On GitHub, download an artifact from a successful Actions run for the agreed revision, extract its runtime ZIP, and read RUN.md. Build artifacts expire after seven days; your trainer should prepare them before the session.

English reference revision: b71a2e9. Verified Windows/Linux/macOS run and artifacts. Source and worked solutions are available in the training repository.

How you will learn

Predict → Run → Break → Explain → Adapt

Work on your own local broker first. With a partner, alternate driver and navigator every 15–20 minutes: one operates, the other predicts and reconciles IDs. Each person demonstrates one changed condition.

Make your initial prediction before revealing hints or asking AI. AI assistance is optional and subject to company policy. Verify suggestions against your code and logs; do not provide credentials, confidential code or company data. You never need to upload prompts or chat histories.

Use the worksheet or local notes for predictions and evidence. These pages do not execute commands or collect your answers. The checklist is your own self-assessment.

Set up once, in separate terminals

Windows commands are selected initially. Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP). Check java -version and javac -version; both should use your supplied JDK 21. Set JAVA_HOME to its root directory in every terminal before building or starting scripts. Configure company proxies/certificates through approved IT settings.

Every terminal — environment

Check your JDK before cloning or starting scripts

Any directory

Use JDK 21 and set JAVA_HOME to its root directory in every terminal. The Windows examples use Command Prompt (cmd.exe), not PowerShell: type cmd if your terminal starts PowerShell. In cmd.exe use set "JAVA_HOME=C:\path\to\jdk-21"; in a Unix shell use export JAVA_HOME="/path/to/jdk-21". Replace the example with your real JDK path, then add its bin directory to PATH. New terminals do not inherit settings made in another terminal.

java -version
javac -version
echo %JAVA_HOME%

Observe: Both version commands report 21. JAVA_HOME names the JDK directory containing bin, not bin itself. Stop here and ask your trainer for the supplied JDK if either command fails.

Setup terminal

Get the source on a personal branch

Parent directory for your training checkout

Clone the public training repository. Replace YOUR_GITHUB_NAME with your username or another personal branch label. The branch starts at the verified revision below, even while main changes. These commands need Git and initial download access. A GitHub Code → Download ZIP download is source and still needs this build; it is different from the prebuilt runtime ZIP containing lib/lab.jar. If you have the runtime ZIP, extract it fully, follow RUN.md, and skip this source-build step. After cd, run subsequent steps from this repository root.

git clone https://github.com/grobmeier/artemis-java-jumpstart.git
cd artemis-java-jumpstart
git switch -c feature/YOUR_GITHUB_NAME-labs b71a2e92f276ff3b07c7801b0dde604b52f11b68

Observe: The source checkout is open on your personal branch at the reference revision. If cloning or switching fails, stop here; do not run later commands in a different directory.

Setup terminal — source checkout only

Check the unbuilt source

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

Run this before compilation. It does not need a lab JAR or a broker. If it fails, fix the reported JDK, JAVA_HOME or incomplete-download problem before continuing. Runtime ZIP users skip this source-only step.

.\scripts\doctor.cmd build

Observe: BUILD_READY. The JDK and Maven Wrapper are present. Network/proxy access is checked during the next build.

Setup terminal — source checkout only

Build and verify before opening broker terminals

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

Only continue after the previous check succeeds. The first build downloads dependencies and runs real broker tests, so allow several minutes. Stop and read the build error if it fails. Runtime ZIP users skip this source-only step.

.\mvnw.cmd -Ptraining clean verify

Observe: BUILD SUCCESS. The training profile builds editable exercises and separate reference solutions. Its tests verify the reference implementation; green CI does not grade every trainee solution.

Terminal 1 — broker

Start the broker in the foreground

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

Keep this terminal open. Do not paste client commands into it. Wait for BROKER_READY before continuing in another terminal.

.\scripts\broker.cmd start

Observe: BROKER_READY. Default TCP address: 127.0.0.1:61616, local loopback only.

Terminal 3 — inspection

Check the runtime connection

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

Open a separate terminal in the same lab root. All station commands below use explicit namespaces. For a repeat, replace the namespace in every cooperating client with a fresh value.

.\scripts\doctor.cmd runtime

Observe: TCP and authentication successful. The broker remains running in Terminal 1.

Choose the right entry point: lab runs finished demonstrations; exercises runs your editable implementations; solutions runs separate worked examples. Stop clients and the local broker before rebuilding with the training profile; Windows may lock running JARs. After BUILD SUCCESS, restart the broker and use a fresh namespace. Do not mix their messages in an old namespace.

No Docker, admin rights, PowerShell policy change or external broker is required. The optional central-broker profile is follow-up material and needs a separate company-network preflight.

Your learning path

  1. Station 1 · 45 minutes

    Queues and competing consumers

    Explain how a queue retains waiting work and how consumers share it.

    Start station →
  2. Station 2 · 45 minutes

    Events and independent subscribers

    Distinguish shared work from independent interest in the same event.

    Start station →
  3. Station 3 · 60 minutes

    Acknowledgement, retry and dead letters

    Explain what is confirmed, what can be delivered again, and how failed work is recovered deliberately.

    Start station →

Debrief and finish

Show a partner or trainer one changed condition. Explain where work waited, who received a copy, and what was confirmed before failure. Support your explanation with business IDs and queue state.

Stop all workers with Ctrl+C. Ask the local broker to stop and wait for its process to exit. A full reset is optional and deletes your owned broker messages; use it only for an exclusively owned local lab after every client and the broker have stopped. Ownership-marker, path and process-lock guards must remain intact. The H2 ledger is separate. Never reset a shared remote broker for an individual exercise.

Terminal 4 — control

Stop your local broker

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

All workers must already be stopped. After this command, wait for Terminal 1 to exit.

.\scripts\broker.cmd stop

Observe: Graceful stop completes; broker process exits.

Optional full local reset
Terminal 4 — control

Reset only your stopped, owned local broker

Lab root: the folder containing mvnw.cmd (source) or RUN.md (runtime ZIP).

Only if every client and broker process has exited, and you intentionally want to remove this local broker dataset. Do not edit ownership markers to bypass a refusal.

.\scripts\broker.cmd reset --confirm

Observe: Owned broker data deleted; H2 ledger preserved. Use fresh namespaces for later runs.

Optional next steps in the training repository: S04 durable subscriptions; S09 idempotency for one local DB effect; selectors and other scenarios. A first pilot with two trainees will help refine timing and clarity.