nvim-java · olisikh · Apr 18, 2026 · Apr 18, 2026 · Apr 18, 2026
diff --git a/README.md b/README.md
@@ -336,33 +336,44 @@ require('java').setup({
   -- JDTLS configuration
   jdtls = {
     version = '1.43.0',
+    path = nil,
+    auto_install = true,
   },
 
   -- Extensions
   lombok = {
     enable = true,
     version = '1.18.40',
+    path = nil,
+    auto_install = true,
   },
 
   java_test = {
     enable = true,
     version = '0.40.1',
+    path = nil,
+    auto_install = true,
   },
 
   java_debug_adapter = {
     enable = true,
     version = '0.58.2',
+    path = nil,
+    auto_install = true,
   },
 
   spring_boot_tools = {
     enable = true,
     version = '1.55.1',
+    path = nil,
+    auto_install = true,
   },
 
   -- JDK installation
   jdk = {
     auto_install = true,
     version = '17',
+    path = nil,
   },
 
   -- Logging
@@ -377,6 +388,20 @@ require('java').setup({
 })
 ```
 
+Set `path` when a tool is managed externally. When `path` is set, nvim-java
+uses that path and does not install the tool. Set
+`auto_install = false` on a tool to fail instead of downloading when no path is
+configured.
+
+Path meanings:
+
+- `jdtls.path`: directory containing `plugins/` and platform `config_*`
+  directories
+- `lombok.path`: path to `lombok.jar`
+- `java_test.path`, `java_debug_adapter.path`, `spring_boot_tools.path`: VS Code
+  extension root containing `package.json`
+- `jdk.path`: JDK home containing `bin/java`
+
 </details>
 
 ## :golf: Architecture

diff --git a/doc/nvim-java.txt b/doc/nvim-java.txt
@@ -349,33 +349,44 @@ want, following options are available:
       -- JDTLS configuration
       jdtls = {
         version = '1.43.0',
+        path = nil,
+        auto_install = true,
       },
 
       -- Extensions
       lombok = {
         enable = true,
         version = '1.18.40',
+        path = nil,
+        auto_install = true,
       },
 
       java_test = {
         enable = true,
         version = '0.40.1',
+        path = nil,
+        auto_install = true,
       },
 
       java_debug_adapter = {
         enable = true,
         version = '0.58.2',
+        path = nil,
+        auto_install = true,
       },
 
       spring_boot_tools = {
         enable = true,
         version = '1.55.1',
+        path = nil,
+        auto_install = true,
       },
 
       -- JDK installation
       jdk = {
         auto_install = true,
         version = '17',
+        path = nil,
       },
 
       -- Logging
@@ -390,6 +401,20 @@ want, following options are available:
     })
 <
 
+Set `path` when a tool is managed externally. When `path` is set, nvim-java
+uses that path and does not install the tool. Set
+`auto_install = false` on a tool to fail instead of downloading when no path is
+configured.
+
+Path meanings:
+
+- `jdtls.path`: directory containing `plugins/` and platform `config_*`
+  directories
+- `lombok.path`: path to `lombok.jar`
+- `java_test.path`, `java_debug_adapter.path`, `spring_boot_tools.path`: VS Code
+  extension root containing `package.json`
+- `jdk.path`: JDK home containing `bin/java`
+
 
 ARCHITECTURE                                          *nvim-java-architecture*
 

diff --git a/lua/java-core/ls/servers/jdtls/cmd.lua b/lua/java-core/ls/servers/jdtls/cmd.lua
@@ -1,12 +1,12 @@
 local List = require('java-core.utils.list')
 local path = require('java-core.utils.path')
-local Manager = require('pkgm.manager')
 local system = require('java-core.utils.system')
 local log = require('java-core.utils.log2')
 local err = require('java-core.utils.errors')
 local java_version_map = require('java-core.constants.java_version')
 local lsp_utils = require('java-core.utils.lsp')
 local str = require('java-core.utils.str')
+local resolver = require('pkgm.resolve')
 
 local M = {}
 
@@ -23,7 +23,7 @@ function M.get_cmd(config)
 		-- system java. So as a workaround, we use the absolute path to java instead
 		-- So following check is not needed when we have auto_install set to true
 		-- @see https://github.com/neovim/neovim/issues/36818
-		if not config.jdk.auto_install then
+		if not config.jdk.auto_install and not config.jdk.path then
 			M.validate_java_version(config, lsp_config.cmd_env)
 		end
 
@@ -44,23 +44,16 @@ end
 ---@return java-core.List
 function M.get_jvm_args(config)
 	local use_lombok = config.lombok.enable
-	local jdtls_root = Manager:get_install_dir('jdtls', config.jdtls.version)
-	local jdtls_config = path.join(jdtls_root, system.get_config_suffix())
+	local jdtls_root = resolver.get_jdtls_root(config)
+	local jdtls_config = M.get_jdtls_config_path(jdtls_root)
 
 	local java_exe = 'java'
 
 	-- NOTE: eventhough we are setting the PATH env var, due to a bug, it's not
 	-- working on Windows. So we are using the absolute path to java instead
 	-- @see https://github.com/neovim/neovim/issues/36818
-	if config.jdk.auto_install then
-		local jdk_root = Manager:get_install_dir('openjdk', config.jdk.version)
-		local java_home
-		if system.get_os() == 'mac' then
-			java_home = vim.fn.glob(path.join(jdk_root, 'jdk-*', 'Contents', 'Home'))
-		else
-			java_home = vim.fn.glob(path.join(jdk_root, 'jdk-*'))
-		end
-
+	if config.jdk.auto_install or config.jdk.path then
+		local java_home = resolver.get_jdk_home(config)
 		java_exe = path.join(java_home, 'bin', 'java')
 	end
 
@@ -85,20 +78,37 @@ function M.get_jvm_args(config)
 
 	-- Adding lombok
 	if use_lombok then
-		local lombok_root = Manager:get_install_dir('lombok', config.lombok.version)
-		local lombok_path = vim.fn.glob(path.join(lombok_root, 'lombok*.jar'))
-		jvm_args:push('-javaagent:' .. lombok_path)
+		jvm_args:push('-javaagent:' .. resolver.get_lombok_path(config))
 	end
 
 	return jvm_args
 end
 
+---@private
+---@param jdtls_root string
+---@return string
+function M.get_jdtls_config_path(jdtls_root)
+	local config_path = path.join(jdtls_root, system.get_config_suffix())
+
+	if vim.fn.isdirectory(config_path) == 1 then
+		return config_path
+	end
+
+	local os_config_path = path.join(jdtls_root, 'config_' .. system.get_os())
+
+	if vim.fn.isdirectory(os_config_path) == 1 then
+		return os_config_path
+	end
+
+	return config_path
+end
+
 ---@private
 ---@param config java.Config
 ---@param cwd? string
 ---@return java-core.List
 function M.get_jar_args(config, cwd)
-	local jdtls_root = Manager:get_install_dir('jdtls', config.jdtls.version)
+	local jdtls_root = resolver.get_jdtls_root(config)
 	cwd = cwd or vim.fn.getcwd()
 
 	local launcher_reg = path.join(jdtls_root, 'plugins', 'org.eclipse.equinox.launcher_*.jar')
@@ -115,7 +125,7 @@ function M.get_jar_args(config, cwd)
 		equinox_launcher,
 
 		'-configuration',
-		lsp_utils.get_jdtls_cache_conf_path(),
+		lsp_utils.get_jdtls_cache_conf_path(jdtls_root),
 
 		'-data',
 		lsp_utils.get_jdtls_cache_data_path(cwd),

diff --git a/lua/java-core/ls/servers/jdtls/env.lua b/lua/java-core/ls/servers/jdtls/env.lua
@@ -1,26 +1,18 @@
 local path = require('java-core.utils.path')
-local Manager = require('pkgm.manager')
 local log = require('java-core.utils.log2')
 local system = require('java-core.utils.system')
+local resolver = require('pkgm.resolve')
 
 local M = {}
 
 --- @param config java.Config
 function M.get_env(config)
-	if not config.jdk.auto_install then
-		log.debug('config.jdk.auto_install disabled, returning empty env')
+	if not config.jdk.auto_install and not config.jdk.path then
+		log.debug('config.jdk.auto_install disabled and config.jdk.path unset, returning empty env')
 		return {}
 	end
 
-	local jdk_root = Manager:get_install_dir('openjdk', config.jdk.version)
-
-	local java_home
-
-	if system.get_os() == 'mac' then
-		java_home = vim.fn.glob(path.join(jdk_root, 'jdk-*', 'Contents', 'Home'))
-	else
-		java_home = vim.fn.glob(path.join(jdk_root, 'jdk-*'))
-	end
+	local java_home = resolver.get_jdk_home(config)
 
 	local java_bin = path.join(java_home, 'bin')
 

diff --git a/lua/java-core/ls/servers/jdtls/plugins.lua b/lua/java-core/ls/servers/jdtls/plugins.lua
@@ -1,10 +1,10 @@
 local M = {}
 
-function M.get_plugin_version_map(config)
+function M.get_plugin_config_map(config)
 	return {
-		['java-test'] = config.java_test.version,
-		['java-debug'] = config.java_debug_adapter.version,
-		['spring-boot-tools'] = config.spring_boot_tools.version,
+		['java-test'] = config.java_test,
+		['java-debug'] = config.java_debug_adapter,
+		['spring-boot-tools'] = config.spring_boot_tools,
 	}
 end
 
@@ -15,19 +15,18 @@ end
 function M.get_plugins(config, plugins)
 	local file = require('java-core.utils.file')
 	local List = require('java-core.utils.list')
-	local Manager = require('pkgm.manager')
 	local path = require('java-core.utils.path')
 	local err = require('java-core.utils.errors')
 	local str = require('java-core.utils.str')
+	local resolver = require('pkgm.resolve')
 
-	local plugin_version_map = M.get_plugin_version_map(config)
+	local plugin_config_map = M.get_plugin_config_map(config)
 
 	return List:new(plugins)
 		:map(function(plugin_name)
-			local version = plugin_version_map[plugin_name]
+			local plugin_config = plugin_config_map[plugin_name]
 
-			local pkg_path = Manager:get_install_dir(plugin_name, version)
-			local plugin_root = path.join(pkg_path, 'extension')
+			local plugin_root = resolver.get_extension_root(plugin_name, plugin_config)
 			local package_json_str = vim.fn.readfile(path.join(plugin_root, 'package.json'))
 			local package_json = vim.json.decode(table.concat(package_json_str, '\n'))
 			local java_extensions = package_json.contributes.javaExtensions

diff --git a/lua/java-core/utils/lsp.lua b/lua/java-core/utils/lsp.lua
@@ -23,12 +23,23 @@ function M.get_jdtls_cache_root_path()
 	return cache_root
 end
 
+local function get_cache_key(value)
+	if value == nil or value == '' then
+		return nil
+	end
+
+	return vim.fn.sha256(value)
+end
+
 --- Returns the path to the jdtls config file
+---@param jdtls_root? string
 ---@return string
-function M.get_jdtls_cache_conf_path()
+function M.get_jdtls_cache_conf_path(jdtls_root)
 	local path = require('java-core.utils.path')
 	local cache_root = M.get_jdtls_cache_root_path()
-	local conf_path = path.join(cache_root, 'config')
+	local cache_key = get_cache_key(jdtls_root)
+	local conf_dir_name = cache_key and ('config_' .. cache_key) or 'config'
+	local conf_path = path.join(cache_root, conf_dir_name)
 	return conf_path
 end
 

diff --git a/lua/java.lua b/lua/java.lua
@@ -28,16 +28,15 @@ function M.setup(custom_config)
 	----------------------------------------------------------------------
 	--                       package installation                       --
 	----------------------------------------------------------------------
-	local Manager = require('pkgm.manager')
-	local pkgm = Manager()
+	local pkgm = require('pkgm.resolve')
 
-	pkgm:install('jdtls', config.jdtls.version)
+	pkgm.install('jdtls', config.jdtls)
 
 	if config.java_test.enable then
 		----------------------------------------------------------------------
 		--                               test                               --
 		----------------------------------------------------------------------
-		pkgm:install('java-test', config.java_test.version)
+		pkgm.install('java-test', config.java_test)
 
 		M.test = {
 			run_current_class = test_api.run_current_class,
@@ -54,7 +53,7 @@ function M.setup(custom_config)
 		----------------------------------------------------------------------
 		--                             debugger                             --
 		----------------------------------------------------------------------
-		pkgm:install('java-debug', config.java_debug_adapter.version)
+		pkgm.install('java-debug', config.java_debug_adapter)
 		require('java-dap').setup()
 
 		M.dap = {
@@ -65,15 +64,15 @@ function M.setup(custom_config)
 	end
 
 	if config.spring_boot_tools.enable then
-		pkgm:install('spring-boot-tools', config.spring_boot_tools.version)
+		pkgm.install('spring-boot-tools', config.spring_boot_tools)
 	end
 
 	if config.lombok.enable then
-		pkgm:install('lombok', config.lombok.version)
+		pkgm.install('lombok', config.lombok)
 	end
 
 	if config.jdk.auto_install then
-		pkgm:install('openjdk', config.jdk.version)
+		pkgm.install('openjdk', config.jdk)
 	end
 
 	----------------------------------------------------------------------