| ------ |
| Usage |
| ------ |
| Jason van Zyl |
| John Casey |
| ------ |
| 27 November 2006 |
| ------ |
| |
| ~~ 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 |
| |
| * Running Once in a Multi-Module Build (<Since: 1.1>) |
| |
| In many cases, an application build consists of multiple Maven modules, but you only need to |
| include the license files, dependencies listing, etc. once for the entire application. Of course, |
| in such cases, the dependencies listing needs to aggregate all dependencies of all modules. |
| |
| To accomplish this, you can use the new <<<runOnlyAtExecutionRoot>>> parameter when you configure |
| the Remote-Resources plugin in your application parent POM. This parameter limits execution of the |
| Remote-Resources plugin to the root directory in which the build was run. In most cases, the |
| application's distribution archives will be created at this top directory, so this is a natural |
| location into which licensing and dependency information should be generated. |
| |
| To run the Remote-Resources plugin only in the execution root, use the following: |
| |
| +---+ |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| [...] |
| |
| <executions> |
| <execution> |
| <id>process-remote-resources</id> |
| <goals> |
| <goal>process</goal> |
| </goals> |
| <configuration> |
| <runOnlyAtExecutionRoot>true</runOnlyAtExecutionRoot> |
| [...] |
| </configuration> |
| </execution> |
| </executions> |
| </plugin> |
| +---+ |
| |
| * How to Create a Resource Bundle |
| |
| To turn on the bundle resource manifest generation you need to configure the plugin as follows: |
| |
| ------------------- |
| <project> |
| ... |
| <build> |
| <plugins> |
| <!-- Turn this into a lifecycle --> |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| <executions> |
| <execution> |
| <goals> |
| <goal>bundle</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| ------------------- |
| |
| This will trigger the scanning of your <<<${basedir}/src/main/resources>>> directory and create the |
| <<<${basedir}/target/classes/META-INF/maven/remote-resources.xml>>> manifest file. |
| |
| * How to Use Remote Resource Bundles |
| |
| To use remote resource bundles you need to configure the plugin as follows: |
| |
| ------------------- |
| <project> |
| ... |
| <build> |
| <plugins> |
| <!-- Turn this into a lifecycle --> |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| <executions> |
| <execution> |
| <goals> |
| <goal>process</goal> |
| </goals> |
| <configuration> |
| <resourceBundles> |
| <resourceBundle>org.apache:apache-jar-resource-bundle:1.0</resourceBundle> |
| </resourceBundles> |
| </configuration> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| ------------------- |
| |
| This will retrieve the <<<apache-jar-resource-bundle-1.0.jar>>> from the remote repositories |
| specified in your POM, process each resource in the bundle and deposit them in your projects |
| <<<${basedir}/target/classes>>> directory. |
| |
| * Specifying Delimiters for Filterable Expressions (<Since 1.1>) |
| |
| By default, the remote-resources plugin supports expressions specified using either the '<<<$\{expr}>>>' or '<<<@expr@>>>' format. |
| However, at times it may be more convenient to use a different set of filter delimiters. By configuring the |
| <<<filterDelimiters>>> and <<<useDefaultFilterDelimiters>>> parameters, you have a high degree of control over the |
| filtering process. |
| |
| To enable the filter delimiters for the format '<<<#\{expr}>>>' (Ruby-style), add the following to your plugin |
| configuration: |
| |
| +---+ |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| [...] |
| |
| <executions> |
| <execution> |
| <id>process-remote-resources</id> |
| <goals> |
| <goal>process</goal> |
| </goals> |
| <configuration> |
| <filterDelimiters> |
| <filterDelimiter>#{*}</filterDelimiter> |
| </filterDelimiters> |
| [...] |
| </configuration> |
| </execution> |
| </executions> |
| </plugin> |
| +---+ |
| |
| Notice the '<<<*>>>' character above. This denotes the dividing point between start and end delimiter, where the actual |
| expression will be specified. |
| |
| If your start and end delimiters are the same, you can use an even simpler configuration. For example, to enable filter |
| delimiters for the format '<<<#expr#>>>', add the following to your plugin configuration: |
| |
| +---+ |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| [...] |
| |
| <executions> |
| <execution> |
| <id>process-remote-resources</id> |
| <goals> |
| <goal>process</goal> |
| </goals> |
| <configuration> |
| <filterDelimiters> |
| <filterDelimiter>#</filterDelimiter> |
| </filterDelimiters> |
| [...] |
| </configuration> |
| </execution> |
| </executions> |
| </plugin> |
| +---+ |
| |
| When the filter processor executes and notices this delimiter specification missing a '<<<*>>>' character, it will simply |
| assume the provided delimiter will be used as the start <and> end delimiter for an expression. |
| |
| All of the above assumes that you still want the ability to use '<<<$\{expr}>>>' and '<<<@expr@>>>' delimiters. However, in |
| cases where this would cause trouble, you can disable these default delimiters as follows: |
| |
| +---+ |
| <plugin> |
| <artifactId>maven-remote-resources-plugin</artifactId> |
| <version>${project.version}</version> |
| [...] |
| |
| <executions> |
| <execution> |
| <id>process-remote-resources</id> |
| <goals> |
| <goal>process</goal> |
| </goals> |
| <configuration> |
| <useDefaultFilterDelimiters>false</useDefaultFilterDelimiters> |
| [...] |
| </configuration> |
| </execution> |
| </executions> |
| </plugin> |
| +---+ |