Prerequisites

This tutorial uses a Spring Boot retail application, the Aerospike Java SDK, and the Aerospike Voyager desktop tool. Install the following dependencies and clone the sample application repository before you start.

The sample application includes a Docker Compose file that runs a single-node Aerospike Database. You do not install Aerospike Database separately.

Required

Docker

Docker runs the single-node Aerospike Database for the sample application. Download and install Docker Desktop from the Docker website.

Verify Docker is running:

docker --version

The output is similar to:

Docker version 27.0.0, build abc1234

Podman with podman compose works as a drop-in replacement on Linux and macOS. If you use it, substitute podman for docker in the commands in this tutorial.

JDK 21

The sample application requires JDK 21.

Download a JDK 21 distribution for your operating system and architecture. Either of the following works:
- Eclipse Temurin (Adoptium)
- Oracle JDK 21
Run the installer for your platform:
- macOS: open the installer you downloaded (.dmg from Oracle, .pkg from Adoptium) and follow the prompts. With Homebrew, you can run brew install --cask temurin@21 instead.
- Windows: run the downloaded installer (.exe or .msi) and accept the option to add Java to your PATH.
- Linux: install from your distribution’s package manager if it ships JDK 21, or follow the Adoptium Linux installer instructions to add the Adoptium APT, RPM, or APK repository and install temurin-21-jdk. As an alternative, extract the downloaded .tar.gz to a stable location such as /opt/jdk-21 and add the JDK’s bin directory to your PATH.
Open a new terminal so the updated PATH is picked up, then verify the JDK.
Terminal window
```
java -version
```
The output begins with openjdk version "21 (or java version "21 for Oracle JDK), for example:
```
openjdk version "21.0.4" 2024-07-16 LTS
```
Any 21.x (or later) build is acceptable. If the version reported is not 21.x, your PATH is still resolving an older JDK.

Apache Maven

The sample application is built with Apache Maven. Install Maven from maven.apache.org, or use your operating system package manager. For example, run brew install maven on macOS or apt install maven on Debian-based Linux distributions.

Verify Maven is available:

mvn -version

The output is similar to:

Apache Maven 3.9.6
Java version: 21.0.4, vendor: Eclipse Adoptium

Aerospike Voyager

Aerospike Voyager is the desktop tool you use to inspect and edit data in your cluster. Voyager runs on macOS, Windows, and Linux.

Download Voyager from the Aerospike download page, install it, then launch it once to confirm it opens without errors. You connect Voyager to the database in the next step.

Sample application

Clone the workshop repository, which contains the Spring Boot retail application, the local Aerospike Database Docker Compose file, and the JSON product data:

git clone https://github.com/aerospike-examples/aerospike-client-sdk-workshop
cd aerospike-client-sdk-workshop

Optional

An IDE with Java support

You edit Java source files in this tutorial. Any editor with Java support works. IntelliJ IDEA, VS Code with the Java Extension Pack, or Eclipse are common choices.

Verify the working tree

The repository contains the following top-level entries:

Directoryaerospike-client-sdk-workshop
- Directoryconfig/
  - …
- Directorydata/ 200 product JSON files auto-loaded on first run
  - …
- Directoryspring-server/ Java source code you edit in this tutorial
  - …
- Directorywebsite/
  - …
- Directoryworkshop/
  - …
- .gitignore
- docker-compose.yml runs the local single-node Aerospike Database
- guide-to-java-sdk.md
- new_client_tester_prompts.md
- README.md
- usability_test_script.md