Require Java 17+ for Maven runtime

* Decouple the Maven runtime JDK from the compile/test toolchain by
  introducing `hc.build.toolchain.version` and overriding the inherited
  `use-toolchains` profile to select the toolchain from that property
  instead of `maven.compiler.source`.

* Require Java 17 or newer to run Maven, but continue compiling and
  testing against Java 8, 11, 17, and 21 toolchains.

* Update CI to install JDK 17 for the Maven process and the matrix JDK
  as the toolchain, generate `toolchains.xml`, and pass
  `hc.build.toolchain.version` explicitly instead of disabling
  toolchains and running everything on the host JDK.

This does not drop support for Java 8 consumers: published artifacts
still target Java 8 and the build can still compile and run tests on
Java 8 through toolchains.

Author: rschmitt

.github/workflows/maven.yml

@@ -22,7 +22,6 @@ permissions:
 
 jobs:
   build:
-
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -43,10 +42,45 @@ jobs:
         key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
         restore-keys: |
           ${{ runner.os }}-maven-
-    - name: Set up JDK ${{ matrix.java }}
+    - name: Select JDK toolchain version
+      run: |
+        case '${{ matrix.java }}' in
+          8)
+            echo 'HC_BUILD_TOOLCHAIN_VERSION=1.8' >> "$GITHUB_ENV"
+            ;;
+          *)
+            echo 'HC_BUILD_TOOLCHAIN_VERSION=${{ matrix.java }}' >> "$GITHUB_ENV"
+            ;;
+        esac
+    - name: Set up toolchain JDK ${{ matrix.java }}
+      id: setup-java-toolchain
       uses: actions/setup-java@v5
       with:
         distribution: 'temurin'
         java-version: ${{ matrix.java }}
+    - name: Set up JDK 17 for Maven
+      uses: actions/setup-java@v5
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+    - name: Configure Maven toolchains
+      env:
+        TOOLCHAIN_JAVA_HOME: ${{ steps.setup-java-toolchain.outputs.path }}
+      run: |
+        mkdir -p "${HOME}/.m2"
+        cat > "${HOME}/.m2/toolchains.xml" <<EOF
+        <?xml version="1.0" encoding="UTF-8"?>
+        <toolchains>
+          <toolchain>
+            <type>jdk</type>
+            <provides>
+              <version>${HC_BUILD_TOOLCHAIN_VERSION}</version>
+            </provides>
+            <configuration>
+              <jdkHome>${TOOLCHAIN_JAVA_HOME}</jdkHome>
+            </configuration>
+          </toolchain>
+        </toolchains>
+        EOF
     - name: Build with Maven
-      run: ./mvnw -V --file pom.xml --no-transfer-progress -DtrimStackTrace=false -Djunit.jupiter.execution.parallel.enabled=false -P-use-toolchains,docker
+      run: ./mvnw -V --file pom.xml --no-transfer-progress -DtrimStackTrace=false -Djunit.jupiter.execution.parallel.enabled=false -Dhc.build.toolchain.version="${HC_BUILD_TOOLCHAIN_VERSION}" -Pdocker

pom.xml

@@ -62,6 +62,8 @@
   <properties>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
+    <!-- Maven itself runs on Java 17+, but compilation and tests can still use an older toolchain JDK. -->
+    <hc.build.toolchain.version>${maven.compiler.source}</hc.build.toolchain.version>
     <httpcore.version>5.5-alpha1</httpcore.version>
     <log4j.version>2.25.3</log4j.version>
     <brotli4j.version>1.20.0</brotli4j.version>
@@ -340,6 +342,27 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>3.5.0</version>
+        <executions>
+          <execution>
+            <id>enforce-java-runtime</id>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+            <configuration>
+              <rules>
+                <requireJavaVersion>
+                  <version>[17,)</version>
+                  <message>Apache HttpComponents Client requires Java 17 or newer to run Maven. Use toolchains to compile and test with older JDKs.</message>
+                </requireJavaVersion>
+              </rules>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
       <plugin>
         <groupId>com.github.siom79.japicmp</groupId>
         <artifactId>japicmp-maven-plugin</artifactId>
@@ -432,6 +455,37 @@
         </plugins>
       </build>
     </profile>
+    <profile>
+      <id>use-toolchains</id>
+      <activation>
+        <file>
+          <exists>${user.home}/.m2/toolchains.xml</exists>
+        </file>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-toolchains-plugin</artifactId>
+            <version>3.2.0</version>
+            <configuration combine.self="override">
+              <toolchains>
+                <jdk>
+                  <version>${hc.build.toolchain.version}</version>
+                </jdk>
+              </toolchains>
+            </configuration>
+            <executions combine.self="override">
+              <execution>
+                <goals>
+                  <goal>toolchain</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
   </profiles>