[MCOMPILER-582] Automatic detection of release option for JDK < 9

- add ITs for confirm feature
- extends documentation

Co-authored-by: Konrad Windszus <kwin@apache.org>

src/it/release-without-profile-fork/invoker.properties

@@ -0,0 +1,18 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+invoker.goals = compile

src/it/release-without-profile-fork/pom.xml

@@ -0,0 +1,45 @@
+<?xml version='1.0'?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>org.apache.maven.plugins.compiler.it</groupId>
+  <artifactId>release-without-profile-fork</artifactId>
+  <version>1.0-SNAPSHOT</version>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>@project.version@</version>
+        <configuration>
+          <!-- compiler arguments will by automatically selected against to used JDK -->
+          <release>8</release>
+          <target>8</target>
+          <source>8</source>
+          <fork>true</fork>
+        </configuration>
+      </plugin>
+    </plugins>
+
+  </build>
+</project>

src/it/release-without-profile-fork/src/main/java/MyClass.java

@@ -0,0 +1,21 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package foo;
+
+public class MyClass {}

src/it/release-without-profile-fork/verify.groovy

@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+def logFile = new File(basedir, 'build.log')
+assert logFile.exists()
+content = logFile.text
+
+// for jdk 8 we will have target and source
+def jdkTarget = content.contains(' -source 8') && content.contains(' -target 8') && !content.contains(' --release 8')
+
+// for jdk9+ we will have release only
+def jdkRelease = !content.contains(' -source 8') && !content.contains(' -target 8') && content.contains(' --release 8')
+
+assert (jdkTarget && !jdkRelease) || (!jdkTarget && jdkRelease)

src/it/release-without-profile/invoker.properties

@@ -0,0 +1,18 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+invoker.goals = compile

src/it/release-without-profile/pom.xml

@@ -0,0 +1,44 @@
+<?xml version='1.0'?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>org.apache.maven.plugins.compiler.it</groupId>
+  <artifactId>release-without-profile</artifactId>
+  <version>1.0-SNAPSHOT</version>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>@project.version@</version>
+        <configuration>
+          <!-- compiler arguments will by automatically selected against to used JDK -->
+          <release>8</release>
+          <target>8</target>
+          <source>8</source>
+        </configuration>
+      </plugin>
+    </plugins>
+
+  </build>
+</project>

src/it/release-without-profile/src/main/java/MyClass.java

@@ -0,0 +1,21 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package foo;
+
+public class MyClass {}

src/it/release-without-profile/verify.groovy

@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+def logFile = new File(basedir, 'build.log')
+assert logFile.exists()
+content = logFile.text
+
+// for jdk 8 we will have target and source
+def jdkTarget = content.contains(' -source 8') && content.contains(' -target 8') && !content.contains(' --release 8')
+
+// for jdk9+ we will have release only
+def jdkRelease = !content.contains(' -source 8') && !content.contains(' -target 8') && content.contains(' --release 8')
+
+assert (jdkTarget && !jdkRelease) || (!jdkTarget && jdkRelease)

src/site/apt/examples/set-compiler-release.apt.vm

@@ -85,7 +85,12 @@ Setting the <<<--release>>> of the Java Compiler
 
   The <<<--release>>> option is not supported using JDK 8. To enable a project that targets Java 8
   to be built using JDK 8 and also JDK 9 or later requires the conditional usage of the
-  <<<--release>>> option. This may be done through the use of a profile:
+  <<<--release>>> option.
+
+  Conditional parametrization is required for the Compiler Plugin version below <<<3.13.0>>>
+  or compilerId different that <<<javac>>>.
+
+  This may be done through the use of a profile:
 
 +-----
 <project>
@@ -106,3 +111,32 @@ Setting the <<<--release>>> of the Java Compiler
   [...]
 </project>
 +-----
+
+  Since version <<<3.13.0>>> of the Compiler Plugin together with the default <<<javac>>> compilerId you don't need conditional parametrisation of <<<release>>>.
+  The <<<release>>> parameter will only be effective for Java 9 or above, otherwise the <<<source>>> and <<<target>>> will be passed to the compiler.
+
+  So you can simply configure as:
+
++-----
+<project>
+ [...]
+ <build>
+   [...]
+   <plugins>
+     <plugin>
+       <groupId>org.apache.maven.plugins</groupId>
+       <artifactId>maven-compiler-plugin</artifactId>
+       <version>${project.version}</version>
+       <configuration>
+         <release>8</release>
+         <source>8</source>
+         <target>8</target>
+       </configuration>
+     </plugin>
+   </plugins>
+   [...]
+ </build>
+ [...]
+</project>
++-----
+