[sisyphusend]

Problem

When a debug session pauses inside a class packaged in a jar or the JRT runtime (any JDK or third-party library class), the stack frame source is reported as a jdt://contents/... uri with sourceReference: 0. That uri can only be rendered by clients that register a jdt content provider — in practice only VS Code with the Red Hat Java extension. Any other DAP client can only open absolute file paths or fetch contents through the DAP source request, so for those clients every library frame is source-less: stepping into JDK or dependency code works, but the editor shows nothing.

Reported from Zed, which consumes the java-debug server through the (now archived) zed-industries/java-debug fork: zed-extensions/java#326.

Fix

JdtSourceLookUpProvider#getSource now materializes the source of jdt:// class files into a local cache file and reports its absolute path instead of the virtual uri:

• Cache location: {java.io.tmpdir}/java-debug-sources/{jarName}/{package}/{Type}.java, written on demand and reused while present.
• Source attachment available (JDK src.zip, maven *-sources.jar): the attached source is written verbatim. Its line numbers match the class line tables exactly, so frames highlight correctly.
• No source attachment: when java.debug.settings.debugSupportOnDecompiledSource is ON, the class is decompiled with the same ContentProviderManager decompiler the VS Code client uses. The original/decompiled line-mapping APIs accept the cache path (they resolve it back to the jdt:// uri), so the existing remap keeps working.
• If contents cannot be resolved at all, the source falls back to SourceType.REMOTE (a sourceReference is assigned and SourceRequestHandler serves getSourceContents), which finally matches the contract already documented on ISourceLookUpProvider#getSource: "In case of 'remote' a follow up 'source' request will be issued by the client".

One visible behavior change for VS Code: frames in library classes will now open the materialized file instead of the jdt:// virtual document (same contents, real file). If that's undesirable for the VS Code experience, the materialization could instead be gated on the client (e.g. only when the initialize clientID is not a known jdt-content-provider client) — happy to adjust based on maintainer preference.

Verification

Scripted end-to-end session against jdt.ls 1.63.0 with this plugin (built from this branch) loaded via the bundles initialization option. Maven project with commons-lang3:3.17.0, launch demo.Main, stopOnEntry, then repeated stepIn:

Stop	Frame	Reported source
entry	Main.main(String[]) :7	project file ...\src\main\java\demo\Main.java
step	Main.main(String[]) :9	same project file
step	StringUtils.capitalize(String) :538	...\Temp\java-debug-sources\commons-lang3-3.17.0.jar\org\apache\commons\lang3\StringUtils.java — attached source, line 538 is exactly public static String capitalize(final String str)
step	String.length() :1583	...\Temp\java-debug-sources\java.base\java\lang\String.java — JDK src.zip source, line 1583 is exactly public int length()

No frame reported a non-absolute path anymore; mvn checkstyle:check passes.

Additional finding: JDTUtils.toUri(classFile) returns null in some language server versions

While testing this patch against the jdt.ls 1.63.0 used by the Zed extension, library frames had no source at all — and a control run with an unpatched build of current main behaves identically. The cause is #624: getFileURI(IClassFile) now delegates to JDTUtils.toUri(classFile), which returns null for jar class files in that jdt.ls version, and a null uri makes convertDebuggerSourceToClient return no source. This patch adds a fallback for that case (resolve the class file via the source containers directly), which restores source resolution even when toUri yields null — it may be worth a look on its own.

Notes

• The cache directory can be deleted at any time. Jar upgrades change {jarName} so entries invalidate naturally; a JDK upgrade reuses the java.base directory until the temp dir is cleared.
• Setting breakpoints inside a materialized cache file is not wired up (breakpoint verification resolves the enclosing type without project context). Stepping, source display and variable inspection work; can be followed up separately.

Refs zed-extensions/java#326

[sisyphusend]

@microsoft-github-policy-service agree

[wenyt (wenytang-ms)]

Thanks for investigating this and providing the detailed reproduction. The compatibility issue reported in [zed-extensions/java#326](zed-extensions/java#326) is valid, but I’m not comfortable merging this approach.

This change replaces jdt:// sources with cached files for all clients, including VS Code. Preserving the existing VS Code Java experience is a requirement, and opening cached files changes how those documents integrate with the Java extension. The acknowledged breakpoint limitation and cache invalidation concerns also make this unsuitable as a global replacement.

Please keep the existing VS Code behavior unchanged and scope any alternative source handling to clients that explicitly opt in. Supporting DAP source requests would be worth exploring before introducing a file cache. The null-URI behavior associated with #624 should be investigated separately.