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.
Prepare your environment
- Java classes, loops, exceptions and basic Maven usage. No messaging experience required.
- A supplied JDK 21 and four separate cmd.exe terminals on Windows, or shells on Linux/macOS.
- A checkout of the public training repository for editable source, or the trainer’s verified runtime ZIP for demonstrations.
- Your own local broker. Docker, administrator rights and a remote broker are not required.
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.
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.
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 b71a2e92f276ff3b07c7801b0dde604b52f11b68Observe: 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.
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 buildObserve: BUILD_READY. The JDK and Maven Wrapper are present. Network/proxy access is checked during the next build.
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 verifyObserve: 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.
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 startObserve: BROKER_READY. Default TCP address: 127.0.0.1:61616, local loopback only.
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 runtimeObserve: 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
- Station 1 · 45 minutes
Queues and competing consumers
Explain how a queue retains waiting work and how consumers share it.
Start station → - Station 2 · 45 minutes
Events and independent subscribers
Distinguish shared work from independent interest in the same event.
Start station → - 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.
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 stopObserve: Graceful stop completes; broker process exits.
Optional full local reset
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 --confirmObserve: 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.