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

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


The following commit(s) were added to refs/heads/master by this push:
     new f11d6beb Add a guide to filtering resources
f11d6beb is described below

commit f11d6beb195a7624660e4357dab60e4ced8fb440
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:11:42 2026 +0000

    Add a guide to filtering resources
---
 content/filtered-resources/.htaccess               |   3 +
 content/markdown/general.md                        |   2 +
 .../guides/mini/guide-filtering-resources.md       | 252 +++++++++++++++++++++
 content/markdown/guides/mini/index.txt             |   1 +
 content/site.xml                                   |   1 +
 5 files changed, 259 insertions(+)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index 7e070003..82901eda 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -23,6 +23,9 @@ Redirect Permanent 
/developers/release/pmc-release-process.html /developers/rele
 Redirect Permanent /development-process.html 
/archives/maven-1.x/development-process.html
 Redirect Permanent /welcome-to-new-committers.html 
/developers/welcome-to-new-committers.html
 
+Redirect Permanent /plugins/maven-resources-plugin/examples/encoding.html 
/guides/mini/guide-filtering-resources.html#Encoding
+Redirect Permanent 
/plugins/maven-resources-plugin/examples/escape-filtering.html 
/guides/mini/guide-filtering-resources.html#Escaping
+Redirect Permanent /plugins/maven-resources-plugin/examples/filter.html 
/guides/mini/guide-filtering-resources.html
 Redirect Permanent /scm/local.html /pom-scm-urls.html#Local_file_system
 Redirect Permanent /scm/scm-url-format.html /pom-scm-urls.html
 Redirect Permanent /scm/scms-overview.html /pom-scm-urls.html#Supported_SCMs
diff --git a/content/markdown/general.md b/content/markdown/general.md
index bb582729..67a07fe6 100644
--- a/content/markdown/general.md
+++ b/content/markdown/general.md
@@ -21,6 +21,8 @@ under the License.
 
 <!--MACRO{toc|fromDepth=2}-->
 
+<a id="encoding-warning"></a>
+
 ## How do I prevent "[WARNING] Using platform encoding (Cp1252 actually) to 
copy filtered resources, i.e. build is platform dependent!"
 
 This or a similar warning is emitted by a plugin that processes plain text 
files but has not been configured to
diff --git a/content/markdown/guides/mini/guide-filtering-resources.md 
b/content/markdown/guides/mini/guide-filtering-resources.md
new file mode 100644
index 00000000..15cc0e7c
--- /dev/null
+++ b/content/markdown/guides/mini/guide-filtering-resources.md
@@ -0,0 +1,252 @@
+<!--
+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.
+-->
+
+# Guide to Filtering Resources
+
+Resource filtering replaces variables in your resource files with values known 
at build time, such as a project name or version.
+The replacement is done by [Maven Filtering](/shared/maven-filtering/), which 
the [Maven Resources Plugin](/plugins/maven-resources-plugin/), the Maven WAR 
Plugin and the Maven EAR Plugin share.
+The examples below use the resources plugin; the rules for variables, 
delimiters and escaping are the same wherever Maven Filtering does the work.
+
+## Enabling filtering
+
+Variables in a resource are written with the `${...}` or `@...@` delimiters.
+They can come from the system properties, the project properties, filter 
files, and the command line.
+
+For example, take a resource `src/main/resources/hello.txt` that contains
+
+```
+Hello ${name}
+```
+
+and a POM that declares the resource directory:
+
+```xml
+<project>
+  ...
+  <name>My Resources Plugin Practice Project</name>
+  ...
+  <build>
+    ...
+    <resources>
+      <resource>
+        <directory>src/main/resources</directory>
+      </resource>
+      ...
+    </resources>
+    ...
+  </build>
+  ...
+</project>
+```
+
+Running
+
+```
+mvn resources:resources
+```
+
+copies the file to `target/classes/hello.txt` unchanged, because filtering is 
off by default:
+
+```
+Hello ${name}
+```
+
+Add a `<filtering>` element to the resource and set it to `true`:
+
+```xml
+<project>
+  ...
+  <resource>
+    <directory>src/main/resources</directory>
+    <filtering>true</filtering>
+  </resource>
+  ...
+</project>
+```
+
+Now `target/classes/hello.txt` contains the project name from the POM:
+
+```
+Hello My Resources Plugin Practice Project
+```
+
+## Setting values
+
+A value given on the command line with `-D` replaces the project's value.
+To change `name` to `world`:
+
+```
+mvn resources:resources -Dname="world"
+```
+
+The result in `target/classes/hello.txt` is
+
+```
+Hello world
+```
+
+You can also define your own variables in the `<properties>` element of the 
POM.
+If `hello.txt` uses `${your.name}`, this POM supplies the value:
+
+```xml
+<project>
+  ...
+  <properties>
+    <your.name>world</your.name>
+  </properties>
+  ...
+</project>
+```
+
+### Filter files
+
+To keep the values out of the POM, put them in a properties file and list it 
in `<filters>`.
+A filter file `my-filter-values.properties` that contains
+
+```properties
+your.name = world
+```
+
+is added like this:
+
+```xml
+<project>
+  ...
+  <build>
+    ...
+    <filters>
+      <filter>my-filter-values.properties</filter>
+    </filters>
+    ...
+  </build>
+  ...
+</project>
+```
+
+The `filters` parameter of the 
[resources:resources](/plugins/maven-resources-plugin/resources-mojo.html#filters)
 goal adds filter files to a single execution, and `useBuildFilters` controls 
whether the files in `<build><filters>` are used for that execution.
+
+## Binary files
+
+Do not filter files with binary content such as images, because that most 
likely corrupts them.
+
+If you have both text and binary resources, keep them in two directories: the 
default `src/main/resources` for the files that are not filtered, and for 
example `src/main/resources-filtered` for the files that are:
+
+```xml
+<project>
+  ...
+  <build>
+    ...
+    <resources>
+      <resource>
+        <directory>src/main/resources-filtered</directory>
+        <filtering>true</filtering>
+      </resource>
+      ...
+    </resources>
+    ...
+  </build>
+  ...
+</project>
+```
+
+Alternatively, [configure the file 
extensions](/plugins/maven-resources-plugin/examples/binaries-filtering.html) 
that are not filtered. The 
[nonFilteredFileExtensions](/plugins/maven-resources-plugin/resources-mojo.html#nonFilteredFileExtensions)
 parameter adds to the built-in list.
+
+## Escaping
+
+To keep an expression from being replaced, precede it with an escape string.
+Set the escape string with the 
[escapeString](/plugins/maven-resources-plugin/resources-mojo.html#escapeString)
 parameter:
+
+```xml
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>3.5.0</version>
+        <configuration>
+          ...
+          <escapeString>\</escapeString>
+          ...
+        </configuration>
+      </plugin>
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+```
+
+With the escape string `\`, an escaped expression is not interpolated, and the 
escape string is removed from the output:
+
+| In the resource | In the output |
+|:---|:---|
+| `\${java.home}` | `${java.home}` |
+
+Anything else preceded by the escape string is passed through unchanged.
+The same applies to expressions delimited by `@`.
+
+## Encoding
+
+A character encoding such as `US-ASCII`, `UTF-8` or `UTF-16` is used to read 
and write filtered files.
+The best practice is to [define the encoding](/general.html#encoding-warning) 
through the `${project.build.sourceEncoding}` property, which the resources 
plugin uses by default for its 
[encoding](/plugins/maven-resources-plugin/resources-mojo.html#encoding) 
parameter:
+
+```xml
+<project>
+  ...
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    ...
+  </properties>
+  ...
+</project>
+```
+
+To use a different encoding for the resources only, set the `encoding` 
parameter in the plugin configuration:
+
+```xml
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>3.5.0</version>
+        <configuration>
+          ...
+          <encoding>UTF-8</encoding>
+          ...
+        </configuration>
+      </plugin>
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
+```
+
+Filtered `.properties` files can use their own encoding through the 
[propertiesEncoding](/plugins/maven-resources-plugin/resources-mojo.html#propertiesEncoding)
 parameter (since 3.2.0); it defaults to `encoding`.
+
+## See also
+
+* [Filtering properties 
files](/plugins/maven-resources-plugin/examples/filtering-properties-files.html)
+* [Custom resources 
filters](/plugins/maven-resources-plugin/examples/custom-resource-filters.html)
+* [Specifying resource 
directories](/plugins/maven-resources-plugin/examples/resource-directory.html)
diff --git a/content/markdown/guides/mini/index.txt 
b/content/markdown/guides/mini/index.txt
index 90164985..de3f3831 100644
--- a/content/markdown/guides/mini/index.txt
+++ b/content/markdown/guides/mini/index.txt
@@ -23,6 +23,7 @@ under the License.
 - [Creating Assemblies]($prefix/guide-assemblies.html)
 - [Configuring Archive Plugins]($prefix/guide-archive-configuration.html)
 - [Configuring Maven]($prefix/guide-configuring-maven.html)
+- [Filtering Resources]($prefix/guide-filtering-resources.html)
 - [Generating Sources]($prefix/guide-generating-sources.html)
 - [Working with Manifests]($prefix/guide-manifest.html)
 - [Maven Classloading]($prefix/guide-maven-classloading.html)
diff --git a/content/site.xml b/content/site.xml
index 3e01143f..bacb2129 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -171,6 +171,7 @@ under the License.
           <item name="Using Toolchains" 
href="/guides/mini/guide-using-toolchains.html"/>
           <item name="Targeting a Java Version" 
href="/guides/mini/guide-java-target.html"/>
           <item name="Building Multi-Release JARs" 
href="/guides/mini/guide-multi-release-jars.html"/>
+          <item name="Filtering Resources" 
href="/guides/mini/guide-filtering-resources.html"/>
           <item name="Maven CI Friendly Version" 
href="/guides/mini/guide-maven-ci-friendly.html"/>
         </item>
 

Reply via email to