# Port To Jdk21

> Port changes from a stage-jdk8-based branch to a stage-based branch, upgrading Java 8 code to Java 21

- Skill: `aerospike/port-to-jdk21` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aerospike/port-to-jdk21`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aerospike/port-to-jdk21/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aerospike (https://skillmd.com/u/aerospike)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aerospike/port-to-jdk21

---


# Port Branch Changes from stage-jdk8 (Java 8) to stage (Java 21)

Port changes from the source branch `$ARGUMENTS` (based on `stage-jdk8`) to a new branch based on `stage`.

## Target Branch Naming

The target branch name MUST be derived from the source branch name by removing the `_jdk8` suffix:
- Source: `CLIENT-1234_feature_jdk8` -> Target: `CLIENT-1234_feature`
- If the source branch doesn't have a `_jdk8` suffix, append `_jdk21` to create the target name:
  - Source: `bugfix-something` -> Target: `bugfix-something_jdk21`

## Steps

1. **Validate** the source branch `$ARGUMENTS` exists and is based on `stage-jdk8`.
2. **Analyze** the commits on the source branch that are not on `stage-jdk8`:
   ```
   git log --oneline stage-jdk8..$ARGUMENTS
   ```
3. **Create** the target branch off `stage`:
   ```
   git checkout stage
   git pull
   git checkout -b <target-branch-name>
   ```
4. **Cherry-pick** the commits from the source branch onto the target branch. If there are conflicts, resolve them with the Java 21 adaptations listed below.
5. **Adapt** the code for Java 21 idioms (see adaptation rules below).
6. **Purge Maven cache** to avoid stale JDK 8 artifacts causing build failures:
   ```
   mvn dependency:purge-local-repository \
     -DreResolve=true \
     -DactTransitively=false
   ```
7. **Build** to verify:
   ```
   mvn clean install -U
   ```

## Java 8 to Java 21 Adaptation Rules

When porting code, apply these modernization transformations where appropriate:

### Language Features
- **Traditional instanceof + cast** -> Use pattern matching for instanceof
  ```java
  // Java 8
  if (obj instanceof String) { String s = (String) obj; use(s); }
  // Java 21
  if (obj instanceof String s) { use(s); }
  ```
- **Verbose switch statements** -> Consider switch expressions where cleaner
  ```java
  // Java 8
  String result;
  switch (x) {
      case 1: result = "one"; break;
      case 2: result = "two"; break;
      default: result = "other"; break;
  }
  // Java 21
  var result = switch (x) {
      case 1 -> "one";
      case 2 -> "two";
      default -> "other";
  };
  ```
- **String concatenation for multiline** -> Consider text blocks where appropriate
- **Explicit types for local variables** -> Use `var` where the type is obvious from context

### API Differences
- **`Collections.unmodifiableList(Arrays.asList(...))`** -> Use `List.of(...)`
- **`Collections.unmodifiableSet(new HashSet<>(Arrays.asList(...)))`** -> Use `Set.of(...)`
- **`string.trim().isEmpty()`** -> Use `string.isBlank()`
- **`!optional.isPresent()`** -> Use `optional.isEmpty()`
- **`.collect(Collectors.toList())`** -> Use `.toList()`
- **Traditional I/O patterns** -> Consider `Files.readString()` / `Files.writeString()` where appropriate

### Project-Specific Differences
- The `stage` branch uses `aerospike-client-jdk21` artifact instead of `aerospike-client-jdk8`
- pom.xml uses `java.version=21` instead of `java.version=1.8` / `java.api=8`
- The `stage` branch may have additional methods (e.g., `estimateKeySize()`) not present in jdk8
- Do NOT modify pom.xml java version settings - those are already correct on `stage`

### Important
- **Be conservative with modernization**: Only modernize code that is part of the change being ported. Do not refactor surrounding unchanged code.
- Preserve the original commit messages when cherry-picking
- If a file does not exist on `stage`, check if the functionality lives in a different file or should be skipped
- After all changes, run `mvn clean install -U` and fix any compilation errors