[maven-resources-plugin] 01/02: [RESOURCES-171] ISO8859-1 properties files get changed into UTF-8 when filtered. - Update the documentation

[de...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dennisl pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-resources-plugin.git

commit f702decd1c0c0e19024bd80f7a54a04ebb452165
Author: Dennis Lundberg <de...@apache.org>
AuthorDate: Fri Jul 17 10:44:57 2020 +0200

    [RESOURCES-171] ISO8859-1 properties files get changed into UTF-8 when filtered.
    - Update the documentation
---
 .../maven/plugins/resources/ResourcesMojo.java     |  2 +
 .../apt/examples/filtering-properties-files.apt.vm | 96 ++++++++++++++++++++++
 src/site/site.xml                                  |  2 +
 3 files changed, 100 insertions(+)

diff --git a/src/main/java/org/apache/maven/plugins/resources/ResourcesMojo.java b/src/main/java/org/apache/maven/plugins/resources/ResourcesMojo.java
index 1105965..4d9a21c 100644
--- a/src/main/java/org/apache/maven/plugins/resources/ResourcesMojo.java
+++ b/src/main/java/org/apache/maven/plugins/resources/ResourcesMojo.java
@@ -72,6 +72,8 @@ public class ResourcesMojo
     /**
      * The character encoding to use when reading and writing filtered properties files.
      * If not specified, it will default to the value of the "encoding" parameter.
+     *
+     * @since 3.2.0
      */
     @Parameter
     protected String propertiesEncoding;
diff --git a/src/site/apt/examples/filtering-properties-files.apt.vm b/src/site/apt/examples/filtering-properties-files.apt.vm
new file mode 100644
index 0000000..e43106b
--- /dev/null
+++ b/src/site/apt/examples/filtering-properties-files.apt.vm
@@ -0,0 +1,96 @@
+ ------
+ Filtering Properties Files
+ ------
+ Dennis Lundberg
+ ------
+ 2020-07-16
+ ------
+
+~~ 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
+
+Filtering Properties Files
+
+ When filtering resources, special care has to be taken if you are filtering
+ properties files. If your filtered properties files include non-ascii
+ characters and your <<<project.build.sourceEncoding>>> is set to anything other
+ than ISO-8859-1 you might be affected and should continue reading.
+
+* What has <<<project.build.sourceEncoding>>> got to do with resources?
+
+ Maven Resources Plugin has, up until version 3.2.0, defaulted to use
+ <<<project.build.sourceEncoding>>> as the encoding when filtering resources,
+ unless you configure the <<<encoding>>> parameter of the plugin explicitly. So
+ unless you have configured the <<<encoding>>> parameter in Maven Resources
+ Plugin explicitly this is what you get.
+
+* Properties files handled by the <<<Properties>>> class
+
+ When the Properties class is used to read and write properties files they
+ require that the properties files use ISO-8859-1 encoding.
+ This is still the case for Java 11, as can be seen in the
+ {{{https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html}API documentation for the Properties class}}.
+ So, properties files that are used in this way needs to use ISO-8859-1
+ encoding.
+
+* Properties files used as <<<ResourceBundle>>>
+
+ When properties files are used as <<<ResourceBundle>>>s the encoding required
+ differs between versions of Java. Up to and including Java 8 these files are
+ required to use ISO-8859-1 encoding.
+
+ Starting with Java 9 the preferred encoding is UTF-8 for property resource
+ bundles. It might work with ISO-8859-1, but as you can see in the
+ {{{https://docs.oracle.com/javase/9/intl/internationalization-enhancements-jdk-9.htm#JSINT-GUID-5ED91AA9-B2E3-4E05-8E99-6A009D2B36AF}Internationalization Enhancements in JDK 9}}
+ documentation you should consider converting your property resource bundles
+ into UTF-8 encoding.
+
+* What do I need to do?
+
+ You need to do 2 things:
+
+ [[1]] Decide which encoding to use for properties files, based on how you use them
+   in your project.
+
+ [[1]] Explicitly configure Maven Resource Plugin accordingly using the
+   <<<propertiesEncoding>>> configuration parameter, that was introduced in
+   version 3.2.0. In most cases it would look like this:
+
++-----+
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>${project.version}</version>
+        <configuration>
+          ...
+          <propertiesEncoding>ISO-8859-1</propertiesEncoding>
+          ...
+        </configuration>
+      </plugin>
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
++-----+
diff --git a/src/site/site.xml b/src/site/site.xml
index b6331d1..d05484e 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -39,6 +39,8 @@ under the License.
             href="/examples/resource-directory.html"/>
       <item name="Filtering"
             href="/examples/filter.html"/>
+      <item name="Filtering properties files"
+            href="/examples/filtering-properties-files.html"/>
       <item name="Including and excluding files and directories"
             href="/examples/include-exclude.html"/>
       <item name="Escape Filtering"