diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index 06a8cfa8..00000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,101 +0,0 @@ - ------ - Introduction - ------ - Olivier Lamy - ------ - 2013-07-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. - -${project.name} - - This component has been built from the filtering process/code in Maven Resources Plugin. - - The goal is to provide a shared component for all plugins that needs to filter resources. - - -* MavenResourcesExecution - -** POM Interpolation - - POM values will be interpolated <> with expressions starting with <<>> or <<>> (it's configurable). - In previous versions something like $\{foo.version\} or $\{version\} was interpolated with the current POM version, but - it won't be interpolated with a POM value any more. - -** Escaping Interpolation - - It's possible now to define a String which will escape interpolation. - \$\{java.home\} will be interpolated to $\{java.home\}. - -** <<>> parameter - - It also accepts absolute paths. - -** <<>> parameter - - The parameter <<>> forces file copy even if the destination file is newer. - - -* MavenResourcesFiltering - - This component will apply filtering on a <<>> of <<>>s. - - If you want to use the default <<>> of <<>> (see below) - you should use the method without the <<>> parameter. - - The component will not filter a predefined set of file extensions (jpg, jpeg, gif, bmp, png). - - <> You can easily add extra file extensions. - - -* MavenFileFilter - - This component has a method which returns the default <<>>s. - These are: - - * Interpolation with token $\{ \} and values from properties files, <<<\>>>/<<<\>>>/<<<\>>, <<>> - and <<>> - - * Interpolation with token @ @ and values from properties files, <<<\>>>/<<<\>>>/<<<\>>, <<>> - and <<>> - - * Interpolation with token $\{ \} and values from <<>> interpolation - - * Interpolation with token @ @ and values from <<>> interpolation - - [] - - The values used for interpolation are stored in a <<>> object - and are loaded in the following order: - - * A <<>> of properties files, provided as a parameter to the method - - * Filters defined in the <<<\>>>/<<<\>>> section of the POM - - * Properties defined in the <<<\>>> section of the POM - - * The <<>> from the current <<>> - - [] - - <> As it's a <<>> object, the last defined key/value pair wins. - - <> When building the <<>> object and reading the properties files that defines the different filters, - interpolation with the token $\{ \} is supported for these filters with limited properties values coming from - <<>> and <<>>. The last wins here too. diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt deleted file mode 100644 index bc867efa..00000000 --- a/src/site/apt/usage.apt +++ /dev/null @@ -1,96 +0,0 @@ - ------ - Usage - ------ - Olivier Lamy - ------ - 2011-01-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. - -Usage - -* Filter a <<>> of <<>> - - Lookup the component in your Mojo: - -+-----+ - @Required - private MavenResourcesFiltering mavenResourcesFiltering; -+-----+ - - Apply filtering on your <<>> of resources, see {{{./index.html}Introduction}} for the default <<>> - that are used. - -+-----+ - MavenResourcesExecution mavenResourcesExecution = - new MavenResourcesExecution ( resources, outputDirectory, mavenProject, - encoding, fileFilters, - nonFilteredFileExtensions, mavenSession ); - - mavenResourcesFiltering.filterResources( mavenResourcesExecution ); -+-----+ - -* Add a new filtering token - - You must use the other methods from the <<>> component and construct your own <<>> of - <<>>. The following example adds interpolation for the token @ @ using values coming from reflection - with the Maven Project. - -+-----+ - // Create your FilterWrapper - FileUtils.FilterWrapper filterWrapper = new FileUtils.FilterWrapper() - { - public Reader getReader( Reader reader ) - { - Interpolator propertiesInterpolator = - new RegexBasedInterpolator( "\\@", "(.+?)\\@" ); - ValueSource valueSource = new MavenProjectValueSource( mavenProject, - true ); - propertiesInterpolator.addValueSource( valueSource ); - return new InterpolatorFilterReader( reader, - propertiesInterpolator, - "@", "@" ); - } - }; - - // Add the new filterWrapper to your MavenResourcesExecution instance - mavenResourcesExecution.addFilterWrapper( filterWrapper ); -+-----+ - - There is a helper method to simplify this. Here's how you would use it to do what we did above: - -+-----+ - mavenResourcesExecution.addFilerWrapper( new MavenProjectValueSource( mavenProject, - true ), - "\\@", "(.+?)\\@", "@", "@" ); -+-----+ - - <> If <<>> is set to <<>>, - the default <<>>s will be added first. - - Now it's time to filter the resources: - -+-----+ - // Apply filtering on your resources - mavenResourcesFiltering.filterResources( mavenResourcesExecution ); -+-----+ - - <> Maven Filtering uses the - {{{http://codehaus-plexus.github.io/plexus-interpolation/}plexus-interpolation component}}. - diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm new file mode 100644 index 00000000..f26fcb06 --- /dev/null +++ b/src/site/markdown/index.md.vm @@ -0,0 +1,75 @@ + + +# ${project.name} + +This component has been built from the filtering process/code in Maven Resources Plugin. + +The goal is to provide a shared component for all plugins that needs to filter resources. + +MavenResourcesExecution +----------------------- + +#[[### POM Interpolation]]# + +POM values will be interpolated **only** with expressions starting with `pom` or `project` (it's configurable). In previous versions something like ${esc.d}{foo.version} or ${esc.d}{version} was interpolated with the current POM version, but it won't be interpolated with a POM value any more. + +#[[### Escaping Interpolation]]# + +It's possible now to define a String which will escape interpolation. ${esc.b}${esc.b}${esc.d}{java.home} will be interpolated to ${esc.d}{java.home}. + +#[[### `targetPath` parameter]]# + +It also accepts absolute paths. + +#[[### `overwrite` parameter]]# + +The parameter `overwrite` forces file copy even if the destination file is newer. + +MavenResourcesFiltering +----------------------- + +This component will apply filtering on a `List` of `org.apache.maven.model.Resource`s. + +If you want to use the default `List` of `FileUtils.FilterWrapper` (see below) you should use the method without the `filterWrappers` parameter. + +The component will not filter a predefined set of file extensions (jpg, jpeg, gif, bmp, png). + +**Note:** You can easily add extra file extensions. + +MavenFileFilter +--------------- + +This component has a method which returns the default `FileUtils.FilterWrapper`s. These are: + +- Interpolation with token ${esc.d}{ } and values from properties files, ``/``/``/``/``/`` section of the POM +- Properties defined in the `` section of the POM +- The `executionProperties` from the current `MavenSession` + +**Note:** As it's a `Properties` object, the last defined key/value pair wins. + +**Note:** When building the `Properties` object and reading the properties files that defines the different filters, interpolation with the token ${esc.d}{ } is supported for these filters with limited properties values coming from `project.properties` and `mavenSession.executionProperties`. The last wins here too. diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md new file mode 100644 index 00000000..2256c593 --- /dev/null +++ b/src/site/markdown/usage.md @@ -0,0 +1,84 @@ + + +# Usage + +## Filter a `List` of `org.apache.maven.model.Resource` + +Lookup the component in your Mojo: + +```unknown + @Required + private MavenResourcesFiltering mavenResourcesFiltering; +``` + +Apply filtering on your `List` of resources, see [Introduction](./index.html) for the default `FilterWrappers` that are used. + +```unknown + MavenResourcesExecution mavenResourcesExecution = + new MavenResourcesExecution ( resources, outputDirectory, mavenProject, + encoding, fileFilters, + nonFilteredFileExtensions, mavenSession ); + + mavenResourcesFiltering.filterResources( mavenResourcesExecution ); +``` + +## Add a new filtering token + +You must use the other methods from the `MavenResourcesFiltering` component and construct your own `List` of `FilterWrappers`. The following example adds interpolation for the token @ @ using values coming from reflection with the Maven Project. + +```unknown + // Create your FilterWrapper + FileUtils.FilterWrapper filterWrapper = new FileUtils.FilterWrapper() + { + public Reader getReader( Reader reader ) + { + Interpolator propertiesInterpolator = + new RegexBasedInterpolator( "\\@", "(.+?)\\@" ); + ValueSource valueSource = new MavenProjectValueSource( mavenProject, + true ); + propertiesInterpolator.addValueSource( valueSource ); + return new InterpolatorFilterReader( reader, + propertiesInterpolator, + "@", "@" ); + } + }; + + // Add the new filterWrapper to your MavenResourcesExecution instance + mavenResourcesExecution.addFilterWrapper( filterWrapper ); +``` + +There is a helper method to simplify this. Here's how you would use it to do what we did above: + +```unknown + mavenResourcesExecution.addFilerWrapper( new MavenProjectValueSource( mavenProject, + true ), + "\\@", "(.+?)\\@", "@", "@" ); +``` + +**Note:** If `mavenResourcesExecution.useDefaultFilterWrappers` is set to `true`, the default `FilterWrapper`s will be added first. + +Now it's time to filter the resources: + +```unknown + // Apply filtering on your resources + mavenResourcesFiltering.filterResources( mavenResourcesExecution ); +``` + +**Note:** Maven Filtering uses the [plexus-interpolation component](http://codehaus-plexus.github.io/plexus-interpolation/).