Toolchain support for test plugins in devmode

README.md

@@ -38,6 +38,8 @@ The Liberty Maven Plugin provides a number of goals for managing a Liberty serve
 
 The Liberty Maven Plugin is tested with Long-Term-Support (LTS) releases of Java. The plugin, as of release 3.10, supports Java 8, 11, 17 and 21. Versions 3.7 to 3.9.x support Java 8, 11 and 17. Prior to version 3.7, the plugin is supported on Java 8 and 11.
 
+To control the JDK used by Liberty Maven Plugin goals and dev mode with Maven Toolchains, see the [toolchain documentation](docs/toolchain.md#toolchain). This feature will be available starting with Liberty Maven Plugin version 3.12.0.
+
 #### Release 3.0 differences
 
 The new capabilities and behavior differences are summarized in the [Liberty Maven Plug-in 3.0](https://github.com/OpenLiberty/ci.maven/releases/tag/liberty-maven-3.0/) release notes.

docs/common-parameters.md

@@ -18,6 +18,7 @@ Parameters shared by all goals.
 | runtimeInstallDirectory | Local installation directory location of the Liberty server when the server is installed using the runtime archive, runtime artifact or repository option. The default value is `${project.build.directory}/liberty`.  | No |
 | refresh | If true, re-install Liberty server into the local directory. This is only used when when the server is installed using the runtime archive or runtime artifact option. The default value is false. | No |
 | skip | If true, the specified goal is bypassed entirely. The default value is false. | No |
+| jdkToolchain | Toolchain requirements (for example, `version` and `vendor`) used to select a JDK from `~/.m2/toolchains.xml` for Liberty server goals and dev mode. See [toolchain](toolchain.md#toolchain) for details. | No |
 
 #### Backward Compatibility
 

docs/toolchain.md

@@ -0,0 +1,164 @@
+#### toolchain
+---
+Use Maven toolchains to run Liberty Maven Plugin goals with a specific JDK. This allows you to control the Java version used by Liberty during build, dev mode, and server operations, even when the system default JDK is different.
+
+Maven Toolchains are used to ensure consistent and reproducible builds by allowing projects to explicitly select a required JDK, independent of the system’s default Java installation. For more details, see the [Maven Toolchains Plugin documentation](https://maven.apache.org/plugins/maven-toolchains-plugin/).
+
+Note: Support for Maven Toolchains in Liberty Maven Plugin is available from version 3.12.0 onwards.
+
+
+###### Overview
+
+Maven toolchains allow you to select a JDK from `~/.m2/toolchains.xml` based on requirements (for example, a Java version).
+
+The Liberty Maven Plugin supports toolchains through the `jdkToolchain` configuration element.
+When `jdkToolchain` is configured:
+
+- Liberty server goals that run server commands (for example, `create`, `start`, `stop`, `status`) attempt to run those commands with the selected toolchain JDK.
+- In dev mode (`dev`), the plugin uses the configured toolchain version when determining effective Java compiler options and when running tests through the Surefire and Failsafe plugins.
+
+
+###### Prerequisites
+
+1. Configure a JDK toolchain in `~/.m2/toolchains.xml`.
+
+Example:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<toolchains>
+  <toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>11</version>
+      <vendor>ibm</vendor>
+    </provides>
+    <configuration>
+      <jdkHome>/path/to/jdk-11</jdkHome>
+    </configuration>
+  </toolchain>
+</toolchains>
+```
+
+
+###### Configuration
+
+Configure the Liberty Maven Plugin with `jdkToolchain`.
+
+The `jdkToolchain` element corresponds to the `<provides>` section of a `jdk` toolchain in `~/.m2/toolchains.xml`. These requirements are passed through to Maven's ToolchainManager to select a matching JDK.
+
+For details on the `toolchains.xml` format and the `<provides>` keys, see the Maven [Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html) guide.
+
+| Parameter | Description | Required       |
+| --------  | ----------- |----------------|
+| version | JDK toolchain version to use. | Typically set. |
+| vendor | JDK toolchain vendor to use. | No             |
+
+Example:
+```xml
+<plugin>
+  <groupId>io.openliberty.tools</groupId>
+  <artifactId>liberty-maven-plugin</artifactId>
+  <version>...</version>
+  <configuration>
+    <jdkToolchain>
+      <version>11</version>
+      <!-- Optional: include vendor if you need to distinguish between toolchains -->
+      <!-- <vendor>ibm</vendor> -->
+    </jdkToolchain>
+  </configuration>
+</plugin>
+```
+
+
+###### How it works
+
+When `jdkToolchain` is configured, the Liberty Maven Plugin uses Maven's toolchain lookup to find a matching JDK in `~/.m2/toolchains.xml`.
+
+- If a matching toolchain is found, the plugin uses that toolchain to determine a `JAVA_HOME` and runs Liberty server commands using that `JAVA_HOME`.
+- If no matching toolchain is found (or `jdkHome` is not available), the plugin logs a warning and runs using the same JDK that is used to run Maven.
+
+If `JAVA_HOME` is already set in `server.env` or `jvm.options`, or is provided through Maven project properties (for example, `liberty.env.JAVA_HOME` or `jvmOptions` properties), that configuration takes precedence. In that case, the plugin logs a warning and does not apply the toolchain.
+
+
+###### Dev mode
+
+Dev mode (`liberty:dev`) uses the configured `jdkToolchain` in two places:
+
+1. Java compilation settings
+
+   When a Liberty toolchain version is configured, dev mode uses that version when determining the effective Java compiler options (`release`, `source`, `target`). If the Maven Compiler Plugin is configured with a different toolchain version, dev mode logs a warning and uses the Liberty toolchain version as the effective Java version for compiler options.
+
+2. Unit and integration test toolchains
+
+   Dev mode integrates with:
+
+   When a Liberty toolchain version is configured, dev mode sets the effective Surefire/Failsafe `jdkToolchain` version used for test execution. If Surefire/Failsafe has no toolchain configuration, dev mode applies the Liberty toolchain version. If Surefire/Failsafe specifies a different toolchain version, dev mode logs a warning and uses the Liberty toolchain version.
+
+   - `maven-surefire-plugin` (`test`)
+   - `maven-failsafe-plugin` (`integration-test`)
+
+
+###### Rules and flows
+
+- **No `jdkToolchain` configured**
+
+  Liberty Maven Plugin does not perform toolchain lookup. Server goals and dev mode run using the Maven JVM and plugin defaults.
+
+- **`jdkToolchain` configured, but no matching toolchain is available**
+
+  Liberty Maven Plugin logs a warning and runs using the same JDK that is used to run Maven.
+
+- **`JAVA_HOME` set for the server (`server.env`, `jvm.options`, or Maven project properties)**
+
+  `JAVA_HOME` configured for the server takes precedence over the toolchain. This includes values set directly in `server.env` or `jvm.options`, as well as values provided through Maven project properties that generate those files (for example, `liberty.env.JAVA_HOME` or `jvmOptions` properties). In these cases, Liberty Maven Plugin logs a warning and does not apply the toolchain.
+
+- **Dev mode compilation**
+
+  If a Liberty toolchain version is configured, dev mode aligns compiler options to that version. The Liberty toolchain has higher precedence, so if the Maven Compiler Plugin specifies a different Java version, the plugin logs a warning and falls back to the Liberty toolchain JDK.
+
+  **Example - Dev mode compilation using a different Maven Compiler Plugin toolchain version**
+
+  Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-compiler-plugin` is set to use JDK 17:
+
+  ```
+  [WARNING] Liberty Maven Plugin jdkToolchain configuration (version 11) does not match the Maven Compiler Plugin jdkToolchain configuration (version 17). The Liberty Maven Plugin jdkToolchain configuration will be used for compilation.
+  ```
+
+- **Dev mode tests (Surefire/Failsafe)**
+
+  If a Liberty toolchain version is configured, dev mode uses that version for Surefire/Failsafe toolchain settings. The Liberty toolchain has higher precedence, so if the Surefire/Failsafe Plugin specifies a different Java version, the plugin logs a warning and falls back to the Liberty toolchain JDK.
+
+  **Example - Dev mode tests using a different Surefire toolchain version**
+
+  Configured toolchain JDK 11 for Liberty Maven Plugin, but `maven-surefire-plugin` is set to use JDK 17:
+
+  ```
+  [WARNING] Liberty Maven Plugin jdkToolchain configuration (version 11) does not match the maven-surefire-plugin jdkToolchain configuration (version 17). The Liberty Maven Plugin jdkToolchain configuration will be used for test execution.
+  ```
+
+
+###### Troubleshooting
+
+**If you see a warning indicating that no toolchain is available, verify:**
+- Your `~/.m2/toolchains.xml` exists and contains a `<jdkHome>` entry.
+- The `version` (and optional `vendor`) matches your Liberty `jdkToolchain` configuration.
+
+**Example - Different version of toolchain JDK in toolchain.xml**
+
+Configured toolchain JDK 11 for Liberty Maven Plugin, but added only JDK 17 in the toolchain.xml
+```
+[WARNING] CWWKM4100W: Toolchain configured for liberty server but jdkHome is not configured in .m2/toolchain.xml.
+```
+
+**If you see a warning that toolchain is not honored because JAVA_HOME is configured:**
+
+- Check `server.env` and `jvm.options` for `JAVA_HOME`.
+- Check your Maven project properties for values that set `JAVA_HOME`, such as `liberty.env.JAVA_HOME` or `jvmOptions` properties.
+- Remove or adjust these settings if you want the toolchain JDK to be used.
+
+**Example - JAVA_HOME specified in server.env**
+
+Added a `JAVA_HOME` variable in the server.env
+```
+[WARNING] CWWKM4101W: The toolchain JDK configuration for goal stop is not honored because the JAVA_HOME property is specified in the server.env or jvm.options file
+```

liberty-maven-app-parent/pom.xml

@@ -20,7 +20,7 @@
     <parent>
         <groupId>io.openliberty.tools</groupId>
         <artifactId>liberty-maven</artifactId>
-        <version>3.11.6-SNAPSHOT</version>
+        <version>3.12.0-SNAPSHOT</version>
     </parent>
 
     <artifactId>liberty-maven-app-parent</artifactId>
@@ -36,7 +36,7 @@
                 <plugin>
                     <groupId>io.openliberty.tools</groupId>
                     <artifactId>liberty-maven-plugin</artifactId>
-                    <version>3.11.6-SNAPSHOT</version>
+                    <version>3.12.0-SNAPSHOT</version>
                     <executions>
                         <execution>
                             <id>stop-before-clean</id>

liberty-maven-plugin/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.openliberty.tools</groupId>
         <artifactId>liberty-maven</artifactId>
-        <version>3.11.6-SNAPSHOT</version>
+        <version>3.12.0-SNAPSHOT</version>
     </parent>
 
     <artifactId>liberty-maven-plugin</artifactId>
@@ -38,7 +38,7 @@
         <dependency>
             <groupId>io.openliberty.tools</groupId>
             <artifactId>liberty-ant-tasks</artifactId>
-            <version>1.9.18-SNAPSHOT</version>
+            <version>1.9.18</version>
         </dependency>
         <dependency>
             <groupId>org.apache.maven</groupId>