#594: Customize Java versions in GitHub workflows (#595)

* #594: Customize Java versions in GitHub workflows

* Apply suggestions from code review

Co-authored-by: Christoph Kuhnke <[email protected]>

* Update user guide

* Add link to user guide

* Upgrade junit version

* Update next-java build

* Fix Javadoc comments for Java 21

* Add Javadoc for Java 21

* Deactivate Java 21 build

* Fix compile error

---------

Co-authored-by: Christoph Kuhnke <[email protected]>

.project-keeper.yml

@@ -72,7 +72,7 @@ version:
 excludes:
   # PK can't use itself as a Maven plugin
   - regex: "W-PK-CORE-151: Pom file .* contains no reference to project-keeper-maven-plugin."
-  # PK already uses Java 17 for building
+  # Build with Java 21 fails due to missing JavaDoc comments, see https://github.com/exasol/project-keeper/issues/596
   - "E-PK-CORE-17: Missing required file: '.github/workflows/ci-build-next-java.yml'"
   # No configuration necessary for aggregator POM
   - "E-PK-CORE-103: Missing parent declaration in 'pom.xml'"

doc/changes/changes_4.3.4.md

@@ -10,6 +10,12 @@ The release ignores vulnerability CVE-2023-7272 in transitive runtime dependency
 
 The release also pins Maven plugin versions to avoid plugin versions depending on the Maven version.
 
+The release also installs the Java versions required by Maven sources during the CI builds. Just set property `java.version` in your `pom.xml` and the required JDK will be installed in all GitHub workflows. See the [user guide](../user_guide/user_guide.md#jdk-toolchain-version) for details.
+
+### Features
+
+* #594: Install required Java versions in GitHub workflows
+
 ### Security
 
 * #586: Fixed vulnerability CVE-2024-47554 in test dependency `commons-io:commons-io:2.11.0`
@@ -47,8 +53,8 @@ The release also pins Maven plugin versions to avoid plugin versions depending o
 * Updated `nl.jqno.equalsverifier:equalsverifier:3.16.1` to `3.17.1`
 * Updated `org.hamcrest:hamcrest:2.2` to `3.0`
 * Updated `org.itsallcode:junit5-system-extensions:1.2.0` to `1.2.2`
-* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.2`
-* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.2`
+* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.3`
+* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.3`
 * Updated `org.mockito:mockito-core:5.12.0` to `5.14.2`
 * Updated `org.slf4j:slf4j-jdk14:1.7.36` to `2.0.16`
 
@@ -84,8 +90,8 @@ The release also pins Maven plugin versions to avoid plugin versions depending o
 * Updated `nl.jqno.equalsverifier:equalsverifier:3.16.1` to `3.17.1`
 * Updated `org.hamcrest:hamcrest:2.2` to `3.0`
 * Updated `org.junit-pioneer:junit-pioneer:2.2.0` to `2.3.0`
-* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.2`
-* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.2`
+* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.3`
+* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.3`
 * Updated `org.mockito:mockito-junit-jupiter:5.12.0` to `5.14.2`
 * Updated `org.slf4j:slf4j-jdk14:1.7.36` to `2.0.16`
 
@@ -119,8 +125,8 @@ The release also pins Maven plugin versions to avoid plugin versions depending o
 
 * Updated `com.exasol:project-keeper-shared-test-setup:4.3.3` to `4.3.4`
 * Updated `org.hamcrest:hamcrest:2.2` to `3.0`
-* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.2`
-* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.2`
+* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.3`
+* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.3`
 
 #### Plugin Dependency Updates
 
@@ -146,8 +152,8 @@ The release also pins Maven plugin versions to avoid plugin versions depending o
 
 * Updated `com.exasol:maven-plugin-integration-testing:1.1.2` to `1.1.3`
 * Updated `org.hamcrest:hamcrest:2.2` to `3.0`
-* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.2`
-* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.2`
+* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.3`
+* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.3`
 * Updated `org.mockito:mockito-core:5.12.0` to `5.14.2`
 * Updated `org.slf4j:slf4j-jdk14:1.7.36` to `2.0.16`
 
@@ -177,8 +183,8 @@ The release also pins Maven plugin versions to avoid plugin versions depending o
 
 * Updated `com.exasol:maven-plugin-integration-testing:1.1.2` to `1.1.3`
 * Updated `org.hamcrest:hamcrest:2.2` to `3.0`
-* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.2`
-* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.2`
+* Updated `org.junit.jupiter:junit-jupiter-engine:5.10.2` to `5.11.3`
+* Updated `org.junit.jupiter:junit-jupiter-params:5.10.2` to `5.11.3`
 * Updated `org.mockito:mockito-core:5.12.0` to `5.14.2`
 * Updated `org.mockito:mockito-junit-jupiter:5.12.0` to `5.14.2`
 * Updated `org.slf4j:slf4j-jdk14:1.7.36` to `2.0.16`

doc/user_guide/user_guide.md

@@ -354,6 +354,12 @@ By default PK configures the project to use Java 11. If you need to use a differ
 </properties>
 ```
 
+The specified Java version must be available on your local machine in [`toolchains.xml`](#configure-mavens-toolchainsxml). PK will automatically update the GitHub workflows `ci-build.yml` and `release.yml` and install the required Java versions using GitHub action [`setup-java`](https://github.com/actions/setup-java). This action automatically manages `toolchains.xml` on the GitHub runner, so that the build will use the same Java versions.
+
+When your project uses multiple Maven modules, each can specify it's own Java version. PK will collect all versions and use them in the GitHub workflows.
+
+PK will also calculate the maximum Java version used by all modules and use the next major Java version for generating `.github/workflows/ci-build-next-java.yml`.
+
 #### Exclude Dependencies From Automatic Version Update
 
 PK's [update-dependencies](#update-dependencies) mode updates the project's `pom.xml` files and updates the versions of all dependencies. In certain cases this could break the build. To exclude a dependency from the automatic update, add the following to your `pom.xml`:

maven-project-crawler/src/main/java/com/exasol/projectkeeper/validators/changesfile/LastReleasePomFileReader.java

@@ -18,7 +18,7 @@
 /**
  * This class reads the pom file including its parent POMs of the latest previous release on the current branch.
  */
-public class LastReleasePomFileReader {
+class LastReleasePomFileReader {
     private static final Logger LOGGER = Logger.getLogger(LastReleasePomFileReader.class.getName());
 
     /**

maven-project-crawler/src/main/java/com/exasol/projectkeeper/validators/changesfile/dependencies/MavenDependencyComparator.java

@@ -10,7 +10,7 @@
 /**
  * This class compares two lists of maven dependencies.
  */
-public class MavenDependencyComparator {
+class MavenDependencyComparator {
 
     /**
      * Compare two lists of maven dependencies.

parent-pom/pom.xml

@@ -33,7 +33,7 @@
         <java.version>17</java.version>
         <maven.version>3.9.9</maven.version>
         <minimum.maven.version>3.6.3</minimum.maven.version>
-        <junit.version>5.11.2</junit.version>
+        <junit.version>5.11.3</junit.version>
         <xmlunit.version>2.10.0</xmlunit.version>
         <mockito.version>5.14.2</mockito.version>
         <slf4j.version>2.0.16</slf4j.version>

project-keeper/src/main/java/com/exasol/projectkeeper/OsCheck.java

@@ -12,6 +12,10 @@
  * http://www.docjar.com/html/api/org/apache/commons/lang/SystemUtils.java.html
  */
 public class OsCheck {
+    OsCheck() {
+
+    }
+
     /**
      * Types of Operating Systems
      */
@@ -27,6 +31,8 @@ public enum OSType {
     }
 
     /**
+     * Get command suffix.
+     * 
      * @param suffixForWindows suffix for command on operating system windows
      * @return if detected operating system is windows then return the provided command suffix otherwise return empty
      *         string.
@@ -55,4 +61,4 @@ private static OSType detectOperatingSystemType() {
         }
         return OSType.OTHER;
     }
-}
+}

project-keeper/src/main/java/com/exasol/projectkeeper/ProjectVersionDetector.java

@@ -14,6 +14,9 @@
 public class ProjectVersionDetector {
     private static final String FAILED_TO_DETECT_VERSION = "Failed to detect overall project version.";
 
+    ProjectVersionDetector() {
+    }
+
     /**
      * Detect the version of the overall project.
      *

project-keeper/src/main/java/com/exasol/projectkeeper/ValidationPhase.java

@@ -10,6 +10,8 @@
 public class ValidationPhase {
 
     /**
+     * Create a new validation phase.
+     * 
      * @param validators list of validators
      * @return new instance of {@link ValidationPhase} with provision {@code null}.
      */
@@ -32,13 +34,17 @@ public ValidationPhase(final Provision provision, final List<Validator> validato
     }
 
     /**
+     * Get validators.
+     * 
      * @return list of validators
      */
     public List<Validator> validators() {
         return this.validators;
     }
 
     /**
+     * Get provision.
+     * 
      * @return provision created during the current validation phase
      */
     public Provision provision() {
@@ -52,6 +58,8 @@ public static class Provision {
         private final String projectVersion;
 
         /**
+         * Set project version.
+         * 
          * @param projectVersion version of the current project kept by project-keeper detected by
          *                       {@link ProjectVersionDetector}
          */
@@ -60,6 +68,8 @@ public Provision(final String projectVersion) {
         }
 
         /**
+         * Get project version.
+         * 
          * @return version of the current project
          */
         public String projectVersion() {

project-keeper/src/main/java/com/exasol/projectkeeper/config/ProjectKeeperConfigReader.java

@@ -25,6 +25,13 @@
  * This class reads {@link ProjectKeeperConfig} from file.
  */
 public class ProjectKeeperConfigReader {
+    /**
+     * Create a new instance.
+     */
+    public ProjectKeeperConfigReader() {
+        // Required for adding Javadoc.
+    }
+
     /** Filename of project keeper's configuration file */
     public static final String CONFIG_FILE_NAME = ".project-keeper.yml";
     private static final String USER_GUIDE_URL = "https://github.com/exasol/project-keeper";

project-keeper/src/main/java/com/exasol/projectkeeper/config/ProjectKeeperRawConfig.java

@@ -20,6 +20,13 @@ public class ProjectKeeperRawConfig {
     private Object version;
     private Build build;
 
+    /**
+     * Create a new instance.
+     */
+    public ProjectKeeperRawConfig() {
+        // Required for adding Javadoc.
+    }
+
     /**
      * Get the sources.
      * 
@@ -137,6 +144,11 @@ public static class Source {
         private ProjectKeeperRawConfig.ParentPomRef parentPom;
         private List<String> artifacts;
 
+        /** Create a new instance. */
+        public Source() {
+            // Required for specifying Javadoc
+        }
+
         /**
          * Get the source path, e.g. {@code project-keeper/pom.xml}.
          * 
@@ -260,6 +272,13 @@ public static class ParentPomRef {
         private String version;
         private String relativePath;
 
+        /**
+         * Create a new instance.
+         */
+        public ParentPomRef() {
+            // Required for adding Javadoc.
+        }
+
         /**
          * Get the group ID of the parent POM.
          * 
@@ -347,6 +366,13 @@ public static class Build {
         /** Build workflow customizations allow adding and replacing steps in the default build workflow */
         public List<Workflow> workflows = emptyList();
 
+        /**
+         * Create a new instance.
+         */
+        public Build() {
+            // Required for adding Javadoc.
+        }
+
         /**
          * Get CI build runner operating system, e.g. {@code ubuntu-20.04}.
          * 
@@ -365,22 +391,38 @@ public void setRunnerOs(final String runnerOs) {
             this.runnerOs = runnerOs;
         }
 
-        /** @return {@code true} if the CI build should free disk space before running the build */
+        /**
+         * Get free disk space flag.
+         * 
+         * @return {@code true} if the CI build should free disk space before running the build
+         */
         public boolean shouldFreeDiskSpace() {
             return freeDiskSpace;
         }
 
-        /** @param freeDiskSpace {@code true} if the CI build should free disk space before running the build */
+        /**
+         * Set free disk space flag.
+         * 
+         * @param freeDiskSpace {@code true} if the CI build should free disk space before running the build
+         */
         public void setFreeDiskSpace(final boolean freeDiskSpace) {
             this.freeDiskSpace = freeDiskSpace;
         }
 
-        /** @return Exasol DB versions for which to run the CI build */
+        /**
+         * Get Exasol DB version.
+         * 
+         * @return Exasol DB versions for which to run the CI build
+         */
         public List<String> getExasolDbVersions() {
             return exasolDbVersions;
         }
 
-        /** @param exasolDbVersions Exasol DB versions for which to run the CI build */
+        /**
+         * Set Exasol DB version.
+         * 
+         * @param exasolDbVersions Exasol DB versions for which to run the CI build
+         */
         public void setExasolDbVersions(final List<String> exasolDbVersions) {
             this.exasolDbVersions = exasolDbVersions;
         }
@@ -393,6 +435,11 @@ public void setExasolDbVersions(final List<String> exasolDbVersions) {
      */
     @SuppressWarnings("java:S1104") // Only used for serialization, getter/setters not needed
     public static class Workflow {
+        /** Create a new instance. */
+        public Workflow() {
+            // Required for specifying Javadoc
+        }
+
         /** Workflow name, e.g. {@code ci-build.yml} or {@code release.yml}. */
         public String name;
         /** GitHub environment, e.g. {@code aws}. */
@@ -408,6 +455,11 @@ public static class Workflow {
      */
     @SuppressWarnings("java:S1104") // Only used for serialization, getter/setters not needed
     public static class RawStepCustomization {
+        /** Create a new instance. */
+        public RawStepCustomization() {
+            // Required for specifying Javadoc
+        }
+
         /** Customization type (insert/replace). */
         public StepCustomization.Type action;
         /** ID of the step to replace or after which to insert. */