(doc) Add example on using --release javac option

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

@@ -0,0 +1,82 @@
+ ------
+ Setting the --release of the Java Compiler
+ ------
+ Mahmoud Anouti
+ ------
+ 2019-12-20
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Setting the <<<--release>>> of the Java Compiler
+
+  Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
+  option to specify against which Java SE release you want to build the project.
+  For example, you have JDK 11 installed and used by Maven, but you want to
+  build the project against Java 8.
+  The <<<--release>>> option ensures that the code is compiled following the
+  rules of the programming language of the specified release, and that generated
+  classes target the release as well as the public API of that release. This
+  means that, unlike the
+  {{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}},
+  the compiler will detect and generate an error when using APIs that don't exist
+  in previous releases of Java SE.
+
+  Since version 3.6 of the Compiler Plugin, this option can be provided either
+  via a property:
+
++-----
+<project>
+  [...]
+  <properties>
+    <maven.compiler.release>8</maven.compiler.release>
+  </properties>
+  [...]
+</project>
++-----
+
+  or by configuring the plugin directly:
+
++-----
+<project>
+  [...]
+  <build>
+    [...]
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          <release>8</release>
+        </configuration>
+      </plugin>
+    </plugins>
+    [...]
+  </build>
+  [...]
+</project>
++-----
+
+  <<Note:>> The value in the <<<release>>> parameter follows the new version naming scheme adopted
+  since Java 9. As such, the release number does not start with 1.x anymore. Also note that the
+  supported <<<release>>> targets include the release of the currently used JDK plus a limited number
+  of previous releases.

src/site/apt/examples/set-compiler-source-and-target.apt.vm

@@ -75,9 +75,10 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
   <<Note:>> Merely setting the <<<target>>> option does not guarantee that your code actually runs on a JRE with the
   specified version. The pitfall is unintended usage of APIs that only exist in later JREs which would make your code
   fail at runtime with a linkage error. To avoid this issue, you can either configure the compiler's boot classpath
-  to match the target JRE or use the
+  to match the target JRE, or use the
   {{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}}
-  to verify your code doesn't use unintended APIs. In the same way, setting the <<<source>>> option does not guarantee 
-  that your code actually compiles on a JDK with the specified version. To compile your code with a specific JDK 
-  version, different than the one used to launch Maven, refer to the
-  {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.
+  to verify your code doesn't use unintended APIs, or better yet use the
+  {{{../examples/set-compiler-release.html}<<<release>>> option supported since JDK 9}}.
+  In the same way, setting the <<<source>>> option does not guarantee that your code actually compiles on a JDK with
+  the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven,
+  refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.

src/site/apt/index.apt.vm

@@ -83,6 +83,8 @@ ${project.name}
 
   * {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
 
+  * {{{./examples/set-compiler-release.html}Compile Using the --release javac Option (supported since JDK 9)}}
+
   * {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}}
 
   * {{{./examples/pass-compiler-arguments.html}Pass Compiler Arguments}}

src/site/site.xml

@@ -35,6 +35,7 @@ under the License.
     <menu name="Examples">
       <item name="Compile Using A Different JDK" href="examples/compile-using-different-jdk.html"/>
       <item name="Compile Using -source and -target javac Options" href="examples/set-compiler-source-and-target.html"/>
+      <item name="Compile Using the --release javac Option (JDK 9+)" href="examples/set-compiler-release.html"/>
       <item name="Compile Using Memory Allocation Enhancements" href="examples/compile-with-memory-enhancements.html"/>
       <item name="Pass Compiler Arguments" href="examples/pass-compiler-arguments.html"/>
       <item name="Non-javac compilerIds" href="non-javac-compilers.html"/>