{"id":13872576,"url":"https://github.com/dansomething/coc-java-debug","last_synced_at":"2025-05-07T10:36:49.573Z","repository":{"id":42510775,"uuid":"236511578","full_name":"dansomething/coc-java-debug","owner":"dansomething","description":"An extension for coc.nvim to enable Java debugging via jdt.ls","archived":false,"fork":false,"pushed_at":"2024-08-05T13:01:57.000Z","size":23765,"stargazers_count":102,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-10T01:12:54.918Z","etag":null,"topics":["coc-java","debugging","java","jdt","lsp","nvim","vim","vimspector"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/coc-java-debug","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dansomething.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-27T14:40:26.000Z","updated_at":"2024-09-28T18:08:20.000Z","dependencies_parsed_at":"2024-01-16T09:55:51.584Z","dependency_job_id":"7b6d1300-a702-4483-99c9-75a3eabc8527","html_url":"https://github.com/dansomething/coc-java-debug","commit_stats":{"total_commits":109,"total_committers":4,"mean_commits":27.25,"dds":0.5229357798165137,"last_synced_commit":"cf3671962c8a3697f117e3e2f68b7faf91ecdcef"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dansomething%2Fcoc-java-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dansomething%2Fcoc-java-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dansomething%2Fcoc-java-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dansomething%2Fcoc-java-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dansomething","download_url":"https://codeload.github.com/dansomething/coc-java-debug/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239565645,"owners_count":19660154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coc-java","debugging","java","jdt","lsp","nvim","vim","vimspector"],"created_at":"2024-08-05T23:00:46.493Z","updated_at":"2025-02-18T23:03:37.306Z","avatar_url":"https://github.com/dansomething.png","language":"TypeScript","readme":"# coc-java-debug\n\nAn [extension][0] for [coc.nvim][17] to enable the [Java Debug Server][1] for the Java language server ([jdt.ls][2]) in\nVim/Neovim.\n\nIt also provides an easy way to launch [Vimspector][19] and connect it to the Java debug server.\n\n## Features\n\n- Integration with [Vimspector][6].\n- Launch Vimspector and connect to the Java debugger with a single command.\n- Provide Vimspector config substitutions for the following Java project values:\n  - class paths\n  - main class\n  - module paths\n  - project name\n- Configure Java debug settings.\n\n## Requirements\n\n- Install the [coc.nvim][17] plugin.\n- Install the [Vimspector][5] plugin.\n- Install the [coc-java][4] extension.\n\n## Quick Start\n\nInstall the coc-java-debug extension.\n\n```sh\n:CocInstall coc-java-debug\n```\n\nOpen a Java file with a main method in Vim.\n\nSet a [breakpoint][15] in your main method.\n\nExecute this Vim command.\n\n```sh\n:CocCommand java.debug.vimspector.start\n```\n\n## Goals\n\n- Provide a simple integration between [Vimspector][19] and the [Java Debug Server][1].\n- Provide Java-specific replacements for Vimspector's [native config][10].\n  - See `java.debug.vimspector.substitution.*` settings.\n- Support Vim and Neovim.\n\n## Non-Goals\n\n- This project is not intended to be a clone of [vscode-java-debug][16].\n\n## Available commands\n\nThe following `:CocCommand` options are provided:\n\n- `java.debug.vimspector.start`: Launch Vimspector and connect it to the [Java Debug Server][1].\n- `java.debug.settings.update`: Sync local debug settings to [Java Debug Server][1]. Done automatically when Vimspector is started with `java.debug.vimspector.start` command.\n\n### Command Arguments\n\n`java.debug.vimspector.start`\n\n- Optionally accepts a JSON string of settings to be passed to Vimspector using [\"LaunchWithSettings\"][8] internally.\n- This feature may be used to override values in the Vimspector config at runtime.\n- For example, it can be used to specify which configuration to load and a [replacement][10] value.\n\n```viml\n:CocCommand java.debug.vimspector.start {\"configuration\":\"Run Test\",\"Test\":\"Name of the test\"}\n```\n\n## Supported settings\n\nThe following settings are supported in [CocConfig][9]:\n\n### java.debug.vimspector\n\n- `java.debug.vimspector.config.createIfNotExists` : If `true` then a `.vimspector.json` config will be created in the workspace if one doesn't already exist, defaults to `true`.\n- `java.debug.vimspector.substitution.adapterPort` : Specifies the [adapter port][11] substitution name for use in `.vimspector.json`. The actual port number will replace this value in the config when the debug server is started, defaults to `AdapterPort`.\n- `java.debug.vimspector.substitution.classPaths` : Specifies the 'class paths' substitution name for use in `.vimspector.json`. The actual class paths will replace this value in the Vimspector config, defaults to `ClassPaths`.\n- `java.debug.vimspector.substitution.mainClass` : Specifies the 'main class' substitution name for use in `.vimspector.json`. The actual main class will replace this value in the Vimspector config, defaults to `MainClass`.\n- `java.debug.vimspector.substitution.modulePaths` : Specifies the 'module paths' substitution name for use in `.vimspector.json`. The actual module paths will replace this value in the Vimspector config, defaults to `ModulePaths`.\n- `java.debug.vimspector.substitution.projectName` : Specifies the 'project name' substitution name for use in `.vimspector.json`. The actual project name will replace this value in the Vimspector config, defaults to `ProjectName`.\n\n### java.debug.settings\n\n- `java.debug.logLevel`: minimum level of debugger logs that are sent to language server, defaults to `warn`.\n- `java.debug.settings.showHex`: show numbers in hex format in \"Variables\" viewlet, defaults to `false`.\n- `java.debug.settings.showStaticVariables`: show static variables in \"Variables\" viewlet, defaults to `false`.\n- `java.debug.settings.showQualifiedNames`: show fully qualified class names in \"Variables\" viewlet, defaults to `false`.\n- `java.debug.settings.showLogicalStructure`: show the logical structure for the Collection and Map classes in \"Variables\" viewlet, defaults to `true`.\n- `java.debug.settings.showToString`: show 'toString()' value for all classes that override 'toString' method in \"Variables\" viewlet, defaults to `true`.\n- `java.debug.settings.maxStringLength`: the maximum length of string displayed in \"Variables\" viewlet, the string longer than this length will be trimmed, defaults to `0` which means no trim is performed.\n- `java.debug.settings.numericPrecision`: the precision when formatting doubles in \"Variables\" viewlet.\n- `java.debug.settings.hotCodeReplace`: Reload the changed Java classes during debugging, defaults to `manual`.\n- `java.debug.settings.exceptionBreakpoint.exceptionTypes`: Specifies a set of exception types you want to break on, e.g. `java.lang.NullPointerException`. A specific exception type and its subclasses can be selected for caught exceptions, uncaught exceptions, or both can be selected.\n- `java.debug.settings.exceptionBreakpoint.allowClasses`: Specifies the allowed locations where the exception breakpoint can break on. Wildcard is supported, e.g. `java.*`, `*.Foo`.\n- `java.debug.settings.exceptionBreakpoint.skipClasses`: Skip the specified classes when breaking on exception.\n  - `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.\n  - `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.\n  - `java.*` - Skip the specified classes. Wildcard is supported.\n  - `java.lang.ClassLoader` - Skip the classloaders.\n- `java.debug.settings.stepping.skipClasses`: Skip the specified classes when stepping.\n  - `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.\n  - `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.\n  - `java.*` - Skip the specified classes. Wildcard is supported.\n  - `java.lang.ClassLoader` - Skip the classloaders.\n- `java.debug.settings.stepping.skipSynthetics`: Skip synthetic methods when stepping.\n- `java.debug.settings.stepping.skipStaticInitializers`: Skip static initializer methods when stepping.\n- `java.debug.settings.stepping.skipConstructors`: Skip constructor methods when stepping.\n- `java.debug.settings.jdwp.limitOfVariablesPerJdwpRequest`: The maximum number of variables or fields that can be requested in one JDWP request. The higher the value, the less frequently debuggee will be requested when expanding the variable view. Also a large number can cause JDWP request timeout. Defaults to 100.\n- `java.debug.settings.jdwp.requestTimeout`: The timeout (ms) of JDWP request when the debugger communicates with the target JVM. Defaults to 3000.\n- `java.debug.settings.jdwp.async`: Experimental: Controls whether the debugger is allowed to send JDWP commands asynchronously. Async mode can improve remote debugging response speed on high-latency networks. Defaults to `auto`, and automatically switch to async mode when the latency of a single jdwp request exceeds 15ms during attach debugging.\n  - `auto` (Default)\n  - `on`\n  - `off`\n- `java.debug.settings.debugSupportOnDecompiledSource`: [Experimental]: Enable debugging support on the decompiled source code. Be aware that this feature may affect the loading speed of Call Stack Viewlet. You also need [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java)@1.20.0 or higher to use this feature.\n\n## Usage and Setup\n\n### Debug a Main Method\n\nThis example will demonstrate how to load a Java program with a main method and debug it using Vimspector.\n\nIf you don't have a `.vimspector.json` file in the root directory of your Java project then `coc-java-debug` will create\none for you unless `java.debug.vimspector.config.createIfNotExists` is disabled.\n\nIf you already have a `.vimspector.json` file then add the config below.\n\n```json\n{\n  \"adapters\": {\n    \"coc-java-debug\": {\n      \"port\": \"${AdapterPort}\"\n    }\n  },\n  \"configurations\": {\n    \"javaLaunch\": {\n      \"default\": true,\n      \"adapter\": \"coc-java-debug\",\n      \"configuration\": {\n        \"args\": \"${args}\",\n        \"request\": \"launch\",\n        \"projectName\": \"${ProjectName}\",\n        \"mainClass\": \"${MainClass}\",\n        \"classPaths\": [\"*${ClassPaths}\"]\n      },\n      \"breakpoints\": {\n        \"exception\": {\n          \"caught\": \"N\",\n          \"uncaught\": \"N\"\n        }\n      }\n    }\n  }\n}\n```\n\nNext, open a Java file with a main method in Vim and set a [breakpoint][15] in your main method.\n\nExecute the command to start debugging.\n\n```viml\n:CocCommand java.debug.vimspector.start\n```\n\nYou will be prompted with\n\n\u003e Enter value for args:\n\nIf you don't have any program arguments just press your enter key.\nOtherwise, type in your args just as you would from a terminal and then press your enter key.\n\nAt this point Vimspector should open and pause your Java program on the breakpoint you set.\n\nThat's it! You may now [step debug][20] your way through your Java program from within Vim.\n\n### Remote Debugging\n\nThis example will demonstrate attaching to a Java program that is running with remote debugging enabled. This is useful\nfor debugging tests or running services.\n\n#### Vimspector Attach Config\n\nAdd the following contents to the `.vimspector.json` file in the root directory of your Java project. Note, don't change\n`\"${AdapterPort}\"`. See [issue #3][7] for an explanation of how this port value works.\n\n```json\n{\n  \"adapters\": {\n    \"coc-java-debug\": {\n      \"port\": \"${AdapterPort}\"\n    }\n  },\n  \"configurations\": {\n    \"javaAttach\": {\n      \"default\": true,\n      \"adapter\": \"coc-java-debug\",\n      \"configuration\": {\n        \"request\": \"attach\",\n        \"host\": \"127.0.0.1\",\n        \"port\": \"5005\"\n      },\n      \"breakpoints\": {\n        \"exception\": {\n          \"caught\": \"N\",\n          \"uncaught\": \"N\"\n        }\n      }\n    }\n  }\n}\n```\n\n*Review the [Vimspector config][12] docs for what's possible within this file.*\n\n##### Configure Vim\n\nThis extension provides `:CocCommand java.debug.vimspector.start` to simplify launching Vimspector.\n\n*Note, it does not start your Java process in remote debug mode. An example of how to do that is covered below.*\n\nTo further simplify, launching Vimspector, add the following config to your `~/.vimrc` file or wherever appropriate for\nyour Vim setup.\n\n```viml\n\" Press F1 key to launch Vimspector\nnmap \u003cF1\u003e :CocCommand java.debug.vimspector.start\u003cCR\u003e\n```\n\n##### Start the Remote Debug Session\n\nFirst, run a Java program with [remote debugging enabled][13].\nBe sure it is configured to pause and wait for a remote connection on port `5005` for this example work.\n\nFor a simple Java program. Create a `Hello.java` file with these contents.\n\n```java\npublic class Hello {\n  public static void main(String[] args) {\n    System.out.println(\"Hello World!\");\n  }\n}\n```\n\nNext, run these commands from a shell to compile the program and then start it with remote debugging enabled.\n\n```sh\njavac -g Hello.java\njava -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=5005,suspend=y Hello\n```\n\nIf everything works correctly you will see this message.\n\n\u003e Listening for transport dt_socket at address: 5005\n\nNow, open the file you want to debug in Vim and set a [breakpoint with Vimspector][15].\n\nFinally, start the debug session in Vim by pressing your `F1` key or use your custom key mapping if you have altered the\nconfig from this example. This should result in Vimspector opening in a new tab in Vim with your Java program paused at\nthe breakpoint you set.\n\nThat's it! You may now [step debug][20] your way through a Java program from within Vim.\n\n*Note, if you use a Java debug port different than `5005` you will need to change that value in your `.vimspector.json`\nfile. It is also possible to configure this port dynamically in Vimspector in the same manner as the debug adapter\nport.*\n\n*Also note, if you use Maven for builds you may start [remote debugging][14] for tests and then run Vimspector.*\n\n```sh\nmvn test -Dmaven.surefire.debug\n```\n\n##### Alternative Configuration (Optional)\n\nIf you'd prefer to launch the Vimspector plugin directly with your own configuration then add something similar the\nfollowing config to your `~/.vimrc` file or wherever appropriate for your Vim setup.\n\n*Note, this will bypass using the `:CocCommand` documented above to start the debug session.*\n\n```viml\nfunction! JavaStartDebugCallback(err, port)\n  execute \"cexpr! 'Java debug started on port: \" . a:port . \"'\"\n  call vimspector#LaunchWithSettings({ \"configuration\": \"Java Attach\", \"AdapterPort\": a:port })\nendfunction\n\nfunction JavaStartDebug()\n  call CocActionAsync('runCommand', 'vscode.java.startDebugSession', function('JavaStartDebugCallback'))\nendfunction\n\nnmap \u003cF1\u003e :call JavaStartDebug()\u003cCR\u003e\n```\n\nThis example provides a way to start the Java debug server through coc.vim and then tell Vimspector which port to use to\nconnect to the debug server. It maps the `F1` key to kick things off, but you can change this key mapping to whatever\nyou want.\n\n## License\n\nEPL 2.0, See [LICENSE](LICENSE) for more information.\n\n[0]: https://github.com/neoclide/coc.nvim/wiki/Using-coc-extensions\n[1]: https://github.com/Microsoft/java-debug\n[2]: https://github.com/eclipse/eclipse.jdt.ls\n[4]: https://github.com/neoclide/coc-java#quick-start\n[5]: https://github.com/puremourning/vimspector#installation\n[6]: https://puremourning.github.io/vimspector-web/\n[7]: https://github.com/dansomething/coc-java-debug/issues/3#issuecomment-622075010\n[8]: https://github.com/puremourning/vimspector#launch-with-options\n[9]: https://github.com/neoclide/coc.nvim/wiki/Using-the-configuration-file#configuration-file-resolve\n[10]: https://puremourning.github.io/vimspector/configuration.html#replacements-and-variables\n[11]: https://puremourning.github.io/vimspector/configuration.html#adapter-configurations\n[12]: https://puremourning.github.io/vimspector/configuration.html\n[13]: https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/conninv.html#Invocation\n[14]: https://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html\n[15]: https://github.com/puremourning/vimspector?tab=readme-ov-file#breakpoints\n[16]: https://github.com/microsoft/vscode-java-debug\n[17]: https://github.com/neoclide/coc.nvim\n[19]: https://github.com/puremourning/vimspector?tab=readme-ov-file#other-lsp-clients\n[20]: https://github.com/puremourning/vimspector?tab=readme-ov-file#stepping\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdansomething%2Fcoc-java-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdansomething%2Fcoc-java-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdansomething%2Fcoc-java-debug/lists"}