src/site/apt/usage.apt.vm

 ------
 Usage
 ------
 Jason van Zyl
 John Casey
 ------
 2011-01-20
 ------

~~ 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

  To handle filtering this version of Maven Remote Resources Plugin uses
  {{{/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}.


* 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 that project's <<<$\{basedir}/src/main/resources>>> directory and create the
 <<<$\{basedir}/target/classes/META-INF/maven/remote-resources.xml>>> {{{./remote-resources.html}manifest file}}.

 <<Note:>> The files have to be named like <<<*.vm>>> to mark them as {{{htps://velocity.apache.org}Velocity}} macro files which will
           be filtered by the <<process>> goal. If you don't name the files according to this,
           they will not be filtered.


* 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>
            <id>process-remote-resources</id>
            <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. 


* Running Once in a Multi-Module Build

  <<Note:>> This feature was added in version 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 <<<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>
+---+


* Specifying Delimiters for Filterable Expressions

  <<Note:>> This feature was added in version 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 both 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>
+---+