# java-engineer

Java 17 to 25 coding rules for writing and reviewing code, covering records, sealed types, Optional, virtual threads and null safety.

Skill by JetBrains. Category: Code quality.

## Install

Project (for this project only):

```sh
npx skills add jetbrains/junie-extensions --skill java-engineer
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add jetbrains/junie-extensions --skill java-engineer -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 2. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/jetbrains/junie-extensions/java-engineer)

## Source

[Open the source](https://github.com/jetbrains/junie-extensions/tree/HEAD/extensions/java-engineer/skills/java). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: java-engineer
description: Java 17–25 policy and pitfalls. Use when writing, reviewing, or refactoring Java code — enforces idioms around records, sealed types, switch exhaustiveness, Optional, virtual threads, and null-safety that LLMs frequently get wrong.
---

# Java — policy & pitfalls

Baseline knowledge of the Java language (records, sealed, pattern matching, text blocks, streams, `var`, generics, Optional API) is assumed — this skill does not teach the language. It encodes the project policy and the traps that keep appearing in code review.

## Setup Check (run first)

Before writing non-trivial code, verify:

1. **JDK version** — `java --version`, and target version in `pom.xml` (`<maven.compiler.release>`) or `build.gradle(.kts)` (`java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }`). Adjust feature use if < 17. Current LTS: Java 25 (released Sept 2025); Java 21 is the previous LTS. Prefer LTS releases for new projects.
2. **Build tool wrapper** — use `./mvnw` / `./gradlew`, never a globally installed `mvn` / `gradle`.
3. **Lombok** — look for `lombok` in dependencies. If present, prefer `@RequiredArgsConstructor` / `@Slf4j` / `@Builder`; if absent, do not introduce Lombok unless asked.
4. **Static analysis** — `error-prone`, `checkstyle`, `spotbugs`, `pmd`. Respect existing rules; do not add new violations.
5. **Preview features** — if build uses `--enable-preview`, some features behave differently. Check flag before relying on preview syntax.

## MUST DO

- **`Optional` is a return type only.** Never a parameter, field, or element of a collection.
- **Value classes → `record`.** DTOs, events, results, config snapshots. Not JPA entities (records are final and have no no-arg constructor).
- **Closed hierarchies → `sealed`** + exhaustive `switch`. Compiler catches new cases.
- **`switch` expression over `if / else if` chains.** Pattern-matching `switch` over `instanceof` chains.
- **Fields `final`** unless you have a reason to reassign.
- **Fail fast at boundaries** — `Objects.requireNonNull` in public-API constructors; validate invariants in record compact constructors.
- **`try-with-resources`** for anything `AutoCloseable` — including `ExecutorService` (Java 19+).
- **Virtual threads for blocking I/O** (`Executors.newVirtualThreadPerTaskExecutor()`). Not for CPU-bound work.
- **Structured concurrency** for multi-call fan-out: `try (var scope = new StructuredTaskScope.ShutdownOnFailure()) { ... }`.
- **Parameterized logging**: `log.info("user_updated userId={} status={}", id, status)`.

## MUST NOT DO

- **No `Optional.get()`** without prior `isPresent()` — use `.map(...).orElseThrow(...)` or `.orElse(default)`.
- **No raw types** (`List` instead of `List<Foo>`), no `@SuppressWarnings("rawtypes")` to silence warnings.
- **No returning `null` from a collection-returning method.** Return `List.of()` / `Collections.emptyList()`.
- **No checked exceptions leaking into `Stream` / lambda**. Wrap into an unchecked domain exception at the boundary.
- **No catching `Exception` / `Throwable`** to "make the compiler happy". Handle a specific type or propagate.
- **No mutating input collections.** Make a defensive copy: `List.copyOf(input)`.
- **No `synchronized` around a blocking call on a virtual thread** — it pins the carrier thread. Use `ReentrantLock`.
- **No `Thread.sleep` / blocking I/O on `parallelStream()`** — shared common pool, starves other work.
- **No mutation of `Stream.toList()` result** — it's unmodifiable (JDK 16+).
- **No PII / tokens / raw passwords in logs.**

## Reference Guide

| Load when | File |
|---|---|
| Debugging subtle language / API behavior (Optional, Stream, switch, records, generics) | `references/pitfalls.md` |
| Records, sealed hierarchies, pattern-matching switch, preview features (pitfalls & traps, not syntax tutorials) | `references/modern-java.md` |
| Writing concurrent code (virtual threads, structured concurrency, `ExecutorService` lifecycle, `ThreadLocal` traps) | `references/concurrency.md` |
| File / stream / socket I/O, charsets, partial reads, NIO buffers | `references/io.md` |

## Output Format

When producing code:

1. A short plan (1–3 bullets) of what's changing.
2. The code.
3. A checklist of the non-obvious MUST rules applied.

When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and suggest the minimal fix.
````

- Previous: [sales-pipeline-analysis](https://syn4pse.dev/terminal/fivetran-sales-pipeline-analysis.md)
- Next: [prisma-platform-core-concepts](https://syn4pse.dev/terminal/prisma-platform-core-concepts.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
