diff --git a/src/site/apt/examples/binaries-filtering.apt.vm b/src/site/apt/examples/binaries-filtering.apt.vm deleted file mode 100644 index 059ee33b..00000000 --- a/src/site/apt/examples/binaries-filtering.apt.vm +++ /dev/null @@ -1,60 +0,0 @@ - ------ - Binaries Filtering - ------ - Olivier Lamy - ------ - 2008-10-14 - ------ - -~~ 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 - -Binary filtering - - The plugin will prevent binary files filtering without adding some <<>> configuration - for the following file extensions <<>>, <<>>, <<>>, <<>> and <<>>. - - If you like to add supplemental file extensions this can simply achieved by - using a configuration like the following: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - - pdf - swf - - ... - - - - ... - - ... - -+-----+ diff --git a/src/site/apt/examples/copy-resources.apt.vm b/src/site/apt/examples/copy-resources.apt.vm deleted file mode 100644 index b955f843..00000000 --- a/src/site/apt/examples/copy-resources.apt.vm +++ /dev/null @@ -1,67 +0,0 @@ - ------ - Copy Resources - ------ - Olivier Lamy - ------ - 2008-09-13 - ------ - -~~ 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 - -Copy Resources - - You can use the mojo copy-resources to copy resources which are not in the default maven layout or not declared in the build/resources element - and attach it to a phase - -+-----+ - - ... - - - - maven-resources-plugin - ${project.version} - - - copy-resources - - validate - - copy-resources - - - ${basedir}/target/extra-resources - - - src/non-packaged-resources - true - - - - - - - - ... - - ... - -+-----+ diff --git a/src/site/apt/examples/custom-resource-filters.apt.vm b/src/site/apt/examples/custom-resource-filters.apt.vm deleted file mode 100644 index b8d533c0..00000000 --- a/src/site/apt/examples/custom-resource-filters.apt.vm +++ /dev/null @@ -1,101 +0,0 @@ - ------ - Custom resource filters - ------ - Olivier Lamy - ------ - 2010-09-24 - ------ - -~~ 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 - -Custom resources filters - - You can build your own custom resources filters. - Custom resource filter classes implement - {{{/shared/maven-filtering/apidocs/org/apache/maven/shared/filtering/MavenResourcesFiltering.html}org.apache.maven.shared.filtering.MavenResourcesFiltering}}. - -* Custom Resources Filter Implementation - -Custom resource filter classes must be marked as a component with -the javax.inject.Named annotation, and are usually also singletons. -Below is an example named "itFilter" - -+-----+ -@Singleton -@Named("itFilter") -public class ItFilter - implements MavenResourcesFiltering - -+-----+ - -* Dependency declaration - -Your classes must be available in the maven-resources-plugin classpath. -This can be done by adding your artifact to the plugin dependencies. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - - - - custom resources filters artifact groupId - custom resources filters artifact artifactId - custom resources filters artifact version - - - - - ... - - ... - -+-----+ - -* Use of your Custom Resource Filter with the maven-resources-plugin - -You must now declare the custom filter in the plugin. - -+-----+ - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - - itFilter - - - ... - - -+-----+ - - And that's it! diff --git a/src/site/apt/examples/encoding.apt.vm b/src/site/apt/examples/encoding.apt.vm deleted file mode 100644 index 9d0ec63c..00000000 --- a/src/site/apt/examples/encoding.apt.vm +++ /dev/null @@ -1,80 +0,0 @@ - ------ - Specifying a character encoding scheme - ------ - Franz Allan See - Karl Heinz Marbaise - ------ - 2016-05-13 - ------ - -~~ 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 - -Specifying a character encoding scheme - - A character encoding scheme such as <<>>, <<>> or <<>> can be chosen to be - used for the reading and writing of files. - - The best practice is to {{{https://maven.apache.org/general.html#encoding-warning}define encoding}} - for copying filtered resources via the property <<<$\{project.build.sourceEncoding}>>> which should be - defined in the pom properties section like this: - -+-----+ - - ... - - UTF-8 - ... - - .. - -+-----+ - - By using the above property <<>> will automatically - use this {{{../resources-mojo.html#encoding}encoding}}. - - Occasionally you need to change the encoding explicitly for different purposes. - This can be done by defining the encoding via the configuration - like this: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - UTF-8 - ... - - - - ... - - ... - -+-----+ - - - \ No newline at end of file diff --git a/src/site/apt/examples/escape-filtering.apt.vm b/src/site/apt/examples/escape-filtering.apt.vm deleted file mode 100644 index ebcfd746..00000000 --- a/src/site/apt/examples/escape-filtering.apt.vm +++ /dev/null @@ -1,58 +0,0 @@ - ------ - Escape Filtering - ------ - Olivier Lamy - ------ - 2008-09-05 - ------ - -~~ 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 - -Escape filtering - - You can escape filtering with configurable String. - - This means expression $\{ \} and @ @ preceded will replace by the expression : \$\{java.home\} -> $\{java.home\}. - - <> - - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - \ - ... - - - - ... - - ... - -+-----+ diff --git a/src/site/apt/examples/filter.apt b/src/site/apt/examples/filter.apt deleted file mode 100644 index 823db895..00000000 --- a/src/site/apt/examples/filter.apt +++ /dev/null @@ -1,203 +0,0 @@ - ------ - Filtering - ------ - Franz Allan See - ------ - 2008-09-05 - ------ - -~~ 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 - - Variables can be included in your resources. These variables, denoted by the - <<<$\{...\}>>> or <<<@...@>>> delimiters, can come from the system properties, your project - properties, from your filter resources and from the command line. - - For example, if you have a resource <<>> containing - -+-----+ -Hello ${name} -+-----+ - - And a POM like this - -+-----+ - - ... - My Resources Plugin Practice Project - ... - - ... - - - src/main/resources - - ... - - ... - - ... - -+-----+ - - Upon calling - -+-----+ -mvn resources:resources -+-----+ - - This will create a resource output in <<>> which contains - exactly the same text. - -+-----+ -Hello ${name} -+-----+ - - However, if you add a <<<\>>> element to our POM and set it to <<>> like this: - -+-----+ - - ... - - src/main/resources - true - - ... - -+-----+ - - Your <<>> after calling - -+-----+ -mvn resources:resources -+-----+ - - would be - -+-----+ -Hello My Resources Plugin Practice Project -+-----+ - - That's because the name variable was replaced by the value of the project's - name (which was specified in the POM). - - Moreover, you can also assign values through the command line using the "-D" - option. For example, to change the value for the variable <<>> to "world", - invoke this command: - -+-----+ -mvn resources:resources -Dname="world" -+-----+ - - And the output in <<>> would be - -+-----+ -Hello world -+-----+ - - Furthermore, you are not limited to pre-defined project variables. You can - specify your own variables and their values in the <<<\>>> element. For - example, if you want to change the variable from "name" to "your.name", - add a <<<\>>> element within the <<<\>>> element. - -+-----+ - - ... - - world - - ... - -+-----+ - - But to organize your project, you may want to put all your variables and their - values in a separate file so that you will not have to rewrite your POM, or set - their values all the time with every build. This can be done by adding a - filter. - -+-----+ - - ... - My Resources Plugin Practice Project - ... - - ... - - [a filter property] - - ... - - ... - -+-----+ - - For example, you can separate "your.name" from the POM by specifying a filter file - <<>> containing: - -+-----+ -your.name = world -+-----+ - - and adding that to our POM - -+-----+ - - ... - - my-filter-values.properties - - ... - -+-----+ - - - <> Do not filter files with binary content like images! This will most likely result in corrupt output. - - If you have both text files and binary files as resources, it is recommended to have two separated - folders: one folder <<>> (default) for the resources which are not filtered and - another folder <<>> for the resources which are filtered. - -+-----+ - - ... - - ... - - - src/main/resources-filtered - true - - ... - - ... - - ... - -+-----+ - - Now you can put those files into <<>> which should not filtered and the other files - into <<>>. - - As already mentioned, filtering binary files like images, pdf`s, etc. can result in corrupted output. - To prevent such problems you can {{{./binaries-filtering.html}configure file extensions}} - which will not be filtered. - diff --git a/src/site/apt/examples/filtering-properties-files.apt.vm b/src/site/apt/examples/filtering-properties-files.apt.vm deleted file mode 100644 index e43106bb..00000000 --- a/src/site/apt/examples/filtering-properties-files.apt.vm +++ /dev/null @@ -1,96 +0,0 @@ - ------ - 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 <<>> is set to anything other - than ISO-8859-1 you might be affected and should continue reading. - -* What has <<>> got to do with resources? - - Maven Resources Plugin has, up until version 3.2.0, defaulted to use - <<>> as the encoding when filtering resources, - unless you configure the <<>> parameter of the plugin explicitly. So - unless you have configured the <<>> parameter in Maven Resources - Plugin explicitly this is what you get. - -* Properties files handled by the <<>> 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 <<>> - - When properties files are used as <<>>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 - <<>> configuration parameter, that was introduced in - version 3.2.0. In most cases it would look like this: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - ISO-8859-1 - ... - - - - ... - - ... - -+-----+ diff --git a/src/site/apt/examples/resource-directory.apt b/src/site/apt/examples/resource-directory.apt deleted file mode 100644 index 55b4d85d..00000000 --- a/src/site/apt/examples/resource-directory.apt +++ /dev/null @@ -1,102 +0,0 @@ - ------ - Specifying resource directories - ------ - Franz Allan See - ------ - 2008-09-05 - ------ - -~~ 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 - -Specifying resource directories - - By default, Maven will look for your project's resources under - <<>>. - -+-----+ -Project -|-- pom.xml -`-- src - `-- main - `-- resources -+-----+ - - However, all your resources may not be in <<>>. Thus, you'd have - to specify those directories by adding the following to your POM. - -+-----+ - - ... - - ... - - - [your folder here] - - - ... - - ... - -+-----+ - - So if your resources resides in <<>> - -+-----+ -Project -|-- pom.xml -`-- src - `-- my-resources -+-----+ - - you can specify that directory by doing the following: - -+-----+ - - ... - - - src/my-resources - - - ... - -+-----+ - - Furthermore, you can have several directories by adding multiple <<<\>>> elements: - -+-----+ - - ... - - - resource1 - - - resource2 - - - resource3 - - - ... - -+-----+ diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index 5b731c47..00000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,105 +0,0 @@ - ------ - Introduction - ------ - Franz Allan See - ------ - 2013-07-22 - ------ - -~~ 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 - -${project.name} - - The Resources Plugin handles the copying of project resources to the output - directory. There are two different kinds of resources: main resources and test resources. The - difference is that the main resources are the resources associated to the main - source code while the test resources are associated to the test source code. - - Thus, this allows the separation of resources for the main source code and its - unit tests. - - This plugin uses the {{{http://maven.apache.org/shared/maven-filtering/}Maven Filtering}} - shared component for filtering resources. - -* Goals Overview - - The Resources Plugin copies files specified by Resource elements, to an output directory. The three - variations below only differ in how the resource and output directory elements are specified or defaulted. - The Resources Plugin has three goals: - - * {{{./resources-mojo.html}resources:resources}} copies the - resources for the main source code to the main output directory. - - This goal usually executes automatically, because it is bound by default to the process-resources life-cycle phase. - It always uses the project.build.resources element to specify the resources, and by default uses the - project.build.outputDirectory to specify the copy destination. - - * {{{./testResources-mojo.html}resources:testResources}} copies the - resources for the test source code to the test output directory. - - This goal usually executes automatically, because it is bound by default to the process-test-resources life-cycle phase. - It always uses the project.build.testResources element to specify the resources, and by default uses the - project.build.testOutputDirectory to specify the copy destination. - - * {{{./copy-resources-mojo.html}resources:copy-resources}} copies resources to an output directory. - - This goal requires that you configure the resources to be copied, and specify the outputDirectory. - -* Usage - - General instructions on how to use the Resources Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. - - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - The following examples show how to use the Resources Plugin in more advanced - use cases: - - * {{{./examples/encoding.html}Specifying a character encoding scheme}} - - * {{{./examples/resource-directory.html}Specifying resource directories}} - - * {{{./examples/filter.html}Filtering}} - - * {{{./examples/include-exclude.html}Including and excluding files and directories}} - - * {{{./examples/escape-filtering.html}Escape filtering}} - - * {{{./examples/copy-resources.html}Copy resources}} - - * {{{./examples/binaries-filtering.html}Binaries filtering}} - - * {{{./examples/custom-resource-filters.html}Custom resources filters}} - - [] diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index c8b8e615..00000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,77 +0,0 @@ - ------ - Usage - ------ - Franz Allan See - ------ - 2011-02-05 - ------ - -~~ 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 - -Usage - - The Resources Plugin handles the copying of project resources to the output - directory. The following examples describe the basic usage of the Plugin. - - To handle filtering this version of Maven Resources Plugin uses - {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}. - - -* Copy resources for the main source code - -+-----+ -mvn resources:resources -+-----+ - - Upon executing this command, the resources for your main source code, - as specified by the \ element, will be - copied to your main build output directory. This does not affect the - resources for your test code. - - Moreover, this goal is bound to the <<>> phase. - - -* Copy resources for the unit tests - -+-----+ -mvn resources:testResources -+-----+ - - Like the first goal this goal copies resources, but this time for your test source code to your - test build output directory, as specified by the \ element. - Also, this does not affect the resources for the main source - code. - - Furthermore, this is bound to the <<>> phase. - - -* Copy resources specified by a \ configuration element - -+-----+ -mvn resources:copy-resources -+-----+ - - Rather than using the \ or \ elements or their - defaults, this uses a \ element that is specified as part of the - plugin configuration. - - See the examples for how to configure this. See the Maven Model for - how to write \ elements. \ No newline at end of file diff --git a/src/site/markdown/examples/binaries-filtering.md.vm b/src/site/markdown/examples/binaries-filtering.md.vm new file mode 100644 index 00000000..1c817bbc --- /dev/null +++ b/src/site/markdown/examples/binaries-filtering.md.vm @@ -0,0 +1,49 @@ + + +# Binary filtering + +The plugin will prevent binary files filtering without adding some `excludes` configuration for the following file extensions `jpg`, `jpeg`, `gif`, `bmp` and `png`. + +If you like to add supplemental file extensions this can simply achieved by using a configuration like the following: + +```unknown + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + + pdf + swf + + ... + + + + ... + + ... + +``` diff --git a/src/site/markdown/examples/copy-resources.md.vm b/src/site/markdown/examples/copy-resources.md.vm new file mode 100644 index 00000000..192c8489 --- /dev/null +++ b/src/site/markdown/examples/copy-resources.md.vm @@ -0,0 +1,57 @@ + + +# Copy Resources + +You can use the mojo copy-resources to copy resources which are not in the default maven layout or not declared in the build/resources element and attach it to a phase + +```unknown + + ... + + + + maven-resources-plugin + ${project.version} + + + copy-resources + + validate + + copy-resources + + + ${basedir}/target/extra-resources + + + src/non-packaged-resources + true + + + + + + + + ... + + ... + +``` diff --git a/src/site/markdown/examples/custom-resource-filters.md.vm b/src/site/markdown/examples/custom-resource-filters.md.vm new file mode 100644 index 00000000..81bb4ffd --- /dev/null +++ b/src/site/markdown/examples/custom-resource-filters.md.vm @@ -0,0 +1,89 @@ + + +# Custom resources filters + +You can build your own custom resources filters. Custom resource filter classes implement [org.apache.maven.shared.filtering.MavenResourcesFiltering](/shared/maven-filtering/apidocs/org/apache/maven/shared/filtering/MavenResourcesFiltering.html). + +Custom Resources Filter Implementation +-------------------------------------- + +# Custom resource filter classes must be marked as a component with the javax.inject.Named annotation, and are usually also singletons. Below is an example named "itFilter" + +```unknown +@Singleton +@Named("itFilter") +public class ItFilter + implements MavenResourcesFiltering +``` + +Dependency declaration +---------------------- + +# Your classes must be available in the maven-resources-plugin classpath. This can be done by adding your artifact to the plugin dependencies. + +```unknown + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + + + + custom resources filters artifact groupId + custom resources filters artifact artifactId + custom resources filters artifact version + + + + + ... + + ... + +``` + +Use of your Custom Resource Filter with the maven-resources-plugin +------------------------------------------------------------------ + +# You must now declare the custom filter in the plugin. + +```unknown + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + + itFilter + + + ... + + +``` + +And that's it! diff --git a/src/site/markdown/examples/encoding.md.vm b/src/site/markdown/examples/encoding.md.vm new file mode 100644 index 00000000..8c511bdb --- /dev/null +++ b/src/site/markdown/examples/encoding.md.vm @@ -0,0 +1,61 @@ + + +# Specifying a character encoding scheme + +A character encoding scheme such as `ASCII`, `UTF-8` or `UTF-16` can be chosen to be used for the reading and writing of files. + +The best practice is to [define encoding](https://maven.apache.org/general.html#encoding-warning) for copying filtered resources via the property `${esc.d}{project.build.sourceEncoding}` which should be defined in the pom properties section like this: + +```unknown + + ... + + UTF-8 + ... + + .. + +``` + +By using the above property `maven-resources-plugin` will automatically use this [encoding](../resources-mojo.html#encoding). + +Occasionally you need to change the encoding explicitly for different purposes. This can be done by defining the encoding via the configuration like this: + +```unknown + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + UTF-8 + ... + + + + ... + + ... + +``` diff --git a/src/site/markdown/examples/escape-filtering.md.vm b/src/site/markdown/examples/escape-filtering.md.vm new file mode 100644 index 00000000..e45f30f7 --- /dev/null +++ b/src/site/markdown/examples/escape-filtering.md.vm @@ -0,0 +1,48 @@ + + +# Escape filtering + +You can escape filtering with configurable String. + +This means expression ${esc.d}{ } and @ @ preceded will replace by the expression : ${esc.b}${esc.b}${esc.d}{java.home} -> ${esc.d}{java.home}. + +**The escapeString will be removed** + +```unknown + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + \ + ... + + + + ... + + ... + +``` diff --git a/src/site/markdown/examples/filter.md b/src/site/markdown/examples/filter.md new file mode 100644 index 00000000..c0f517c8 --- /dev/null +++ b/src/site/markdown/examples/filter.md @@ -0,0 +1,174 @@ + + +# Filtering + +Variables can be included in your resources. These variables, denoted by the `${...}` or `@...@` delimiters, can come from the system properties, your project properties, from your filter resources and from the command line. + +For example, if you have a resource `src/main/resources/hello.txt` containing + +```unknown +Hello ${name} +``` + +And a POM like this + +```unknown + + ... + My Resources Plugin Practice Project + ... + + ... + + + src/main/resources + + ... + + ... + + ... + +``` + +Upon calling + +```unknown +mvn resources:resources +``` + +This will create a resource output in `target/classes/hello.txt` which contains exactly the same text. + +```unknown +Hello ${name} +``` + +However, if you add a `` element to our POM and set it to `true` like this: + +```unknown + + ... + + src/main/resources + true + + ... + +``` + +Your `target/classes/hello.txt` after calling + +```unknown +mvn resources:resources +``` + +would be + +```unknown +Hello My Resources Plugin Practice Project +``` + +That's because the name variable was replaced by the value of the project's name (which was specified in the POM). + +Moreover, you can also assign values through the command line using the "-D" option. For example, to change the value for the variable `name` to "world", invoke this command: + +```unknown +mvn resources:resources -Dname="world" +``` + +And the output in `target/classes/hello.txt` would be + +```unknown +Hello world +``` + +Furthermore, you are not limited to pre-defined project variables. You can specify your own variables and their values in the `` element. For example, if you want to change the variable from "name" to "your.name", add a `` element within the `` element. + +```unknown + + ... + + world + + ... + +``` + +But to organize your project, you may want to put all your variables and their values in a separate file so that you will not have to rewrite your POM, or set their values all the time with every build. This can be done by adding a filter. + +```unknown + + ... + My Resources Plugin Practice Project + ... + + ... + + [a filter property] + + ... + + ... + +``` + +For example, you can separate "your.name" from the POM by specifying a filter file `my-filter-values.properties` containing: + +```unknown +your.name = world +``` + +and adding that to our POM + +```unknown + + ... + + my-filter-values.properties + + ... + +``` + +**Warning:** Do not filter files with binary content like images\! This will most likely result in corrupt output. + +If you have both text files and binary files as resources, it is recommended to have two separated folders: one folder `src/main/resources` (default) for the resources which are not filtered and another folder `src/main/resources-filtered` for the resources which are filtered. + +```unknown + + ... + + ... + + + src/main/resources-filtered + true + + ... + + ... + + ... + +``` + +Now you can put those files into `src/main/resources` which should not filtered and the other files into `src/main/resources-filtered`. + +As already mentioned, filtering binary files like images, pdf\`s, etc. can result in corrupted output. To prevent such problems you can [configure file extensions](./binaries-filtering.html) which will not be filtered. diff --git a/src/site/markdown/examples/filtering-properties-files.md.vm b/src/site/markdown/examples/filtering-properties-files.md.vm new file mode 100644 index 00000000..30a05da7 --- /dev/null +++ b/src/site/markdown/examples/filtering-properties-files.md.vm @@ -0,0 +1,69 @@ + + +# 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 [API documentation for the Properties class](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html). 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 [Internationalization Enhancements in JDK 9](https://docs.oracle.com/javase/9/intl/internationalization-enhancements-jdk-9.htm#JSINT-GUID-5ED91AA9-B2E3-4E05-8E99-6A009D2B36AF) 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: + + ```unknown + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + ISO-8859-1 + ... + + + + ... + + ... + + ``` diff --git a/src/site/apt/examples/include-exclude.apt b/src/site/markdown/examples/include-exclude.md similarity index 53% rename from src/site/apt/examples/include-exclude.apt rename to src/site/markdown/examples/include-exclude.md index 521e8683..8e93f3db 100644 --- a/src/site/apt/examples/include-exclude.apt +++ b/src/site/markdown/examples/include-exclude.md @@ -1,40 +1,29 @@ - ------ - Including and excluding files and directories - ------ - Franz Allan See - ------ - 2008-09-05 - ------ + -Including and excluding files and directories +# Including and excluding files and directories - When specifying a resource directory, every file within that directory may not - be used. Thus, we may have to specify only the files that we want to include or - specify the files that we want to exclude. +When specifying a resource directory, every file within that directory may not be used. Thus, we may have to specify only the files that we want to include or specify the files that we want to exclude. - To include a resource, we only need to add an <<<\>>> element. +To include a resource, we only need to add an `` element. -+-----+ +```unknown ... My Resources Plugin Practice Project @@ -58,11 +47,11 @@ Including and excluding files and directories ... -+-----+ +``` - And to exclude a resource, we only need to add an <<<\>>> element. +And to exclude a resource, we only need to add an `` element. -+-----+ +```unknown ... My Resources Plugin Practice Project @@ -86,13 +75,11 @@ Including and excluding files and directories ... -+-----+ +``` - For example, if we want to include all text and RTF files under our - <<>> directory and in all its subdirectories, we can do the - following: +For example, if we want to include all text and RTF files under our `src/my-resources` directory and in all its subdirectories, we can do the following: -+-----+ +```unknown ... My Resources Plugin Practice Project @@ -113,12 +100,11 @@ Including and excluding files and directories ... -+-----+ +``` - Also, if we want to include everything except the bitmaps, jpegs, and gifs, we - can simply exclude them by: +Also, if we want to include everything except the bitmaps, jpegs, and gifs, we can simply exclude them by: -+-----+ +```unknown ... My Resources Plugin Practice Project @@ -141,13 +127,11 @@ Including and excluding files and directories ... -+-----+ +``` - Of course, we can also have both <<<\>>> and <<<\>>> elements. For example, if we - want to include all text files that does not contain the word "test" in their - filename. +Of course, we can also have both `` and `` elements. For example, if we want to include all text files that does not contain the word "test" in their filename. -+-----+ +```unknown ... My Resources Plugin Practice Project @@ -170,4 +154,4 @@ Including and excluding files and directories ... -+-----+ +``` diff --git a/src/site/markdown/examples/resource-directory.md b/src/site/markdown/examples/resource-directory.md new file mode 100644 index 00000000..9a445152 --- /dev/null +++ b/src/site/markdown/examples/resource-directory.md @@ -0,0 +1,91 @@ + + +# Specifying resource directories + +By default, Maven will look for your project's resources under `src/main/resources`. + +```unknown +Project +|-- pom.xml +`-- src + `-- main + `-- resources +``` + +However, all your resources may not be in `src/main/resources`. Thus, you'd have to specify those directories by adding the following to your POM. + +```unknown + + ... + + ... + + + [your folder here] + + + ... + + ... + +``` + +So if your resources resides in `src/my-resources` + +```unknown +Project +|-- pom.xml +`-- src + `-- my-resources +``` + +you can specify that directory by doing the following: + +```unknown + + ... + + + src/my-resources + + + ... + +``` + +Furthermore, you can have several directories by adding multiple `` elements: + +```unknown + + ... + + + resource1 + + + resource2 + + + resource3 + + + ... + +``` diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 00000000..f037a477 --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,62 @@ + + +# Apache Maven Resources Plugin +The Resources Plugin handles the copying of project resources to the output directory. There are two different kinds of resources: main resources and test resources. The difference is that the main resources are the resources associated to the main source code while the test resources are associated to the test source code. + +Thus, this allows the separation of resources for the main source code and its unit tests. + +This plugin uses the [Maven Filtering](http://maven.apache.org/shared/maven-filtering/) shared component for filtering resources. + +## Goals Overview + +The Resources Plugin copies files specified by Resource elements, to an output directory. The three variations below only differ in how the resource and output directory elements are specified or defaulted. The Resources Plugin has three goals: + +- [resources:resources](./resources-mojo.html) copies the resources for the main source code to the main output directory. + + This goal usually executes automatically, because it is bound by default to the process-resources life-cycle phase. It always uses the project.build.resources element to specify the resources, and by default uses the project.build.outputDirectory to specify the copy destination. + +- [resources:testResources](./testResources-mojo.html) copies the resources for the test source code to the test output directory. + + This goal usually executes automatically, because it is bound by default to the process-test-resources life-cycle phase. It always uses the project.build.testResources element to specify the resources, and by default uses the project.build.testOutputDirectory to specify the copy destination. + +- [resources:copy-resources](./copy-resources-mojo.html) copies resources to an output directory. + + This goal requires that you configure the resources to be copied, and specify the outputDirectory. + +## Usage + +General instructions on how to use the Resources Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. + +In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). + +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html). + +## Examples + +The following examples show how to use the Resources Plugin in more advanced use cases: + +- [Specifying a character encoding scheme](./examples/encoding.html) +- [Specifying resource directories](./examples/resource-directory.html) +- [Filtering](./examples/filter.html) +- [Including and excluding files and directories](./examples/include-exclude.html) +- [Escape filtering](./examples/escape-filtering.html) +- [Copy resources](./examples/copy-resources.html) +- [Binaries filtering](./examples/binaries-filtering.html) +- [Custom resources filters](./examples/custom-resource-filters.html) diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm new file mode 100644 index 00000000..e6a70517 --- /dev/null +++ b/src/site/markdown/usage.md.vm @@ -0,0 +1,57 @@ + + +# Usage + +The Resources Plugin handles the copying of project resources to the output directory. The following examples describe the basic usage of the Plugin. + +To handle filtering this version of Maven Resources Plugin uses [Maven Filtering](http://maven.apache.org/shared/maven-filtering/index.html) ${mavenFilteringVersion}. + +Copy resources for the main source code +--------------------------------------- + +```unknown +mvn resources:resources +``` + +Upon executing this command, the resources for your main source code, as specified by the <resources> element, will be copied to your main build output directory. This does not affect the resources for your test code. + +Moreover, this goal is bound to the `process-resources` phase. + +Copy resources for the unit tests +--------------------------------- + +```unknown +mvn resources:testResources +``` + +Like the first goal this goal copies resources, but this time for your test source code to your test build output directory, as specified by the <testResources> element. Also, this does not affect the resources for the main source code. + +Furthermore, this is bound to the `process-test-resources` phase. + +Copy resources specified by a <resources> configuration element +--------------------------------------------------------------------- + +```unknown +mvn resources:copy-resources +``` + +Rather than using the <resources> or <testResources> elements or their defaults, this uses a <resources> element that is specified as part of the plugin configuration. + +See the examples for how to configure this. See the Maven Model for how to write <resources> elements.