java-lsp — Java code intelligence via jdtls
Part of the LSP plugin series. Wraps Eclipse JDT Language Server
(jdtls) as a read-only, SOSA Level 1 intelligence source.
Workflow Process
Plan
- Confirm the user's question actually needs semantic info (diagnostics,
references, definitions, hover) vs a plain grep/glob.
- Verify
jdtls --help works and Java 17+ is on PATH (java -version).
- Confirm the repo has a recognizable root:
pom.xml, build.gradle[.kts],
settings.gradle[.kts], .project, or a .git directory.
Act
- Resolve the file path the user is asking about.
- Use LSP via the plugin's
.lsp.json wiring:
textDocument/publishDiagnostics → compile errors
textDocument/definition → jump
textDocument/references → call sites
textDocument/hover → type / Javadoc
workspace/symbol → fuzzy class search
- For cross-file impact (e.g. reviewing a change), iterate
find-references over every public/protected symbol in the touched file.
- Treat jdtls answers as authoritative over heuristic search. If jdtls returns
empty, say so — don't invent references.
Verify
- Cross-check one reported reference by opening the referenced file. If the
symbol isn't really there, the jdtls index is stale — report that, don't
silently retry.
- If diagnostics include
incompleteClasspath, the project isn't fully loaded
yet — wait for the initial build (can take 10–60 s on first open) before
trusting reference counts.
jdtls startup notes (non-obvious)
- First-run latency: the initial workspace build for a large Maven/Gradle
project can take 30–90 s. The plugin's
.lsp.json sets startupTimeout: 120000
(milliseconds); very large monorepos may need more in a fork.
- Workspace folder: jdtls writes build artifacts to
~/.cache/jdtls/workspace/<hash>/. Safe to delete to force reindex.
- JDK version: jdtls runs on Java 17+. The target source can be any
JDK (
--source 1.8 through latest) as long as a matching JDK is on the
runtime classpath. Configure via org.eclipse.jdt.ls.core.vmargs or
JAVA_HOME pointing at the runtime JDK.
Example settings.json (consumer-side, optional)
{
"java.configuration.runtimes": [
{ "name": "JavaSE-17", "path": "/opt/homebrew/opt/openjdk@17", "default": true },
{ "name": "JavaSE-21", "path": "/opt/homebrew/opt/openjdk@21" }
],
"java.import.gradle.enabled": true,
"java.import.maven.enabled": true,
"java.autobuild.enabled": true
}
Common Issues (FAQ)
"jdtls hangs on startup."
Usually the initial Maven/Gradle resolve. Tail ~/.cache/jdtls/*/.metadata/.log
to confirm it's still progressing. Rule out VPN-blocked Maven Central.
"find-references returns only 2 hits but I know there are more."
Two common causes:
- Index not built yet (see
incompleteClasspath warning).
- Callers live in a different Gradle subproject that isn't imported into the
same workspace. Open the repo root, not a subproject.
"Diagnostics show The type XXX cannot be resolved."
Classpath is broken. Check:
pom.xml / build.gradle is valid
- Dependencies have been downloaded (
./mvnw dependency:resolve /
./gradlew dependencies)
- The runtime JDK matches the project's source level
"Android Gradle project — jdtls doesn't see AAR dependencies."
jdtls doesn't run the full Android Gradle Plugin classloader. Open the project
first in Android Studio / IntelliJ to let AGP generate R.java and unpack
AARs, then point jdtls at the generated sources. For pure JVM modules (no
com.android.*), jdtls works directly.
"Kotlin interop — my Java file calls into Kotlin code, refs not found."
That's expected — jdtls doesn't parse .kt. Pair this plugin with
kotlin-lsp for the Kotlin side.
"Javadoc shows as raw HTML tags."
jdtls returns Markdown-rendered Javadoc when the client advertises
hover.markdown. The plugin does that by default; if you're seeing raw HTML
you're probably on a very old jdtls build — upgrade.
"Groovy / Scala / Clojure?"
Out of scope. They'd be sibling plugins (groovy-lsp, metals,
clojure-lsp). Open an issue if you need one.
Out of scope
- Refactor execution (rename, extract method, change signature). jdtls can
plan them; we only surface the plan. Applying edits violates Level-1 SOSA.
- Running tests or the JVM. Pure static analysis.
- Maven / Gradle task execution. If a user wants
./gradlew build, that's a
separate Bash tool concern.
1---2name: java-lsp3description: |4 Use this skill whenever Claude needs semantic intelligence on Java source —5 compile errors, type info, go-to-definition, find-references, or call-graph6 context. Trigger on: "Java LSP", "jdtls", "Eclipse JDT", "find references",7 "who calls this method", "where is X defined", "why does this class fail to8 compile", ".java diagnostics", "method signature", "Java type error", "Maven9 build error", "Gradle compile error", "Android Gradle", "classpath issue",10 "Javadoc for", "decompile", or any question about .java files that requires11 real symbol resolution rather than textual search.12metadata:13 source: https://skillmd.com/skills/msapps-mobile/java-lsp14---1516# java-lsp — Java code intelligence via jdtls1718Part of the LSP plugin series. Wraps **Eclipse JDT Language Server**19(`jdtls`) as a read-only, SOSA Level 1 intelligence source.2021## Workflow Process2223### Plan241. Confirm the user's question actually needs semantic info (diagnostics,25 references, definitions, hover) vs a plain grep/glob.262. Verify `jdtls --help` works and Java 17+ is on PATH (`java -version`).273. Confirm the repo has a recognizable root: `pom.xml`, `build.gradle[.kts]`,28 `settings.gradle[.kts]`, `.project`, or a `.git` directory.2930### Act314. Resolve the file path the user is asking about.325. Use LSP via the plugin's `.lsp.json` wiring:33 - `textDocument/publishDiagnostics` → compile errors34 - `textDocument/definition` → jump35 - `textDocument/references` → call sites36 - `textDocument/hover` → type / Javadoc37 - `workspace/symbol` → fuzzy class search386. For cross-file impact (e.g. reviewing a change), iterate39 `find-references` over every public/protected symbol in the touched file.407. Treat jdtls answers as authoritative over heuristic search. If jdtls returns41 empty, *say so* — don't invent references.4243### Verify448. Cross-check one reported reference by opening the referenced file. If the45 symbol isn't really there, the jdtls index is stale — report that, don't46 silently retry.479. If diagnostics include `incompleteClasspath`, the project isn't fully loaded48 yet — wait for the initial build (can take 10–60 s on first open) before49 trusting reference counts.5051## `jdtls` startup notes (non-obvious)5253- **First-run latency:** the initial workspace build for a large Maven/Gradle54 project can take 30–90 s. The plugin's `.lsp.json` sets `startupTimeout: 120000`55 (milliseconds); very large monorepos may need more in a fork.56- **Workspace folder:** jdtls writes build artifacts to57 `~/.cache/jdtls/workspace/<hash>/`. Safe to delete to force reindex.58- **JDK version:** jdtls **runs** on Java 17+. The *target* source can be any59 JDK (`--source 1.8` through latest) as long as a matching JDK is on the60 runtime classpath. Configure via `org.eclipse.jdt.ls.core.vmargs` or61 `JAVA_HOME` pointing at the runtime JDK.6263## Example `settings.json` (consumer-side, optional)6465```json66{67 "java.configuration.runtimes": [68 { "name": "JavaSE-17", "path": "/opt/homebrew/opt/openjdk@17", "default": true },69 { "name": "JavaSE-21", "path": "/opt/homebrew/opt/openjdk@21" }70 ],71 "java.import.gradle.enabled": true,72 "java.import.maven.enabled": true,73 "java.autobuild.enabled": true74}75```7677## Common Issues (FAQ)7879**"jdtls hangs on startup."**80Usually the initial Maven/Gradle resolve. Tail `~/.cache/jdtls/*/.metadata/.log`81to confirm it's still progressing. Rule out VPN-blocked Maven Central.8283**"find-references returns only 2 hits but I know there are more."**84Two common causes:851. Index not built yet (see `incompleteClasspath` warning).862. Callers live in a *different* Gradle subproject that isn't imported into the87 same workspace. Open the repo root, not a subproject.8889**"Diagnostics show `The type XXX cannot be resolved`."**90Classpath is broken. Check:91- `pom.xml` / `build.gradle` is valid92- Dependencies have been downloaded (`./mvnw dependency:resolve` /93 `./gradlew dependencies`)94- The runtime JDK matches the project's source level9596**"Android Gradle project — jdtls doesn't see AAR dependencies."**97jdtls doesn't run the full Android Gradle Plugin classloader. Open the project98first in Android Studio / IntelliJ to let AGP generate `R.java` and unpack99AARs, then point jdtls at the generated sources. For pure JVM modules (no100`com.android.*`), jdtls works directly.101102**"Kotlin interop — my Java file calls into Kotlin code, refs not found."**103That's expected — jdtls doesn't parse `.kt`. Pair this plugin with104`kotlin-lsp` for the Kotlin side.105106**"Javadoc shows as raw HTML tags."**107jdtls returns Markdown-rendered Javadoc when the client advertises108`hover.markdown`. The plugin does that by default; if you're seeing raw HTML109you're probably on a very old jdtls build — upgrade.110111**"Groovy / Scala / Clojure?"**112Out of scope. They'd be sibling plugins (`groovy-lsp`, `metals`,113`clojure-lsp`). Open an issue if you need one.114115## Out of scope116117- Refactor *execution* (rename, extract method, change signature). jdtls can118 plan them; we only surface the plan. Applying edits violates Level-1 SOSA.119- Running tests or the JVM. Pure static analysis.120- Maven / Gradle task execution. If a user wants `./gradlew build`, that's a121 separate Bash tool concern.