------
  Filtering Some Distribution Files
 ------
  Edwin Punzalan
 ------
  26-July-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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html


Filtering Some Distribution Files

* Introduction

  File filtering is used to substitute variable fields from inside a file to
  their represented values. For the Assembly Plugin, and most Maven filtering
  procedures, these variables are enclosed between $\{ and \}. For
  example, before a file is filtered, it contains <<<$\{project.artifactId\}>>>.
  But after filtering is complete, a new file is created with the project's
  <<<artifactId>>> substituting <<<$\{project.artifactId\}>>> and that this new
  file is used instead of the original one.

  Although filtering can be done during the process-resources phase, not all
  files going into your distribution will be coming from a project resource.
  Thus, the Assembly Plugin allows filtering of files before copying them into
  the created assembly.

  This example demonstrates how to filter files before adding them into the
  assembly. In this example, we need to filter distribution files into the
  archive. The files included in the distribution are:

    * README.txt

    * LICENSE.txt

    * NOTICE.txt

    []

  All the above files are in the root directory of the project but only the
  README and the NOTICE files should be filtered. The property file used to
  filter these are files is found in <<<src/assemble/filter.properties>>>.

  A property file is a file which contains the names of the variables and their
  corresponding string value. The format of its contents is identical to how Java
  Property files are saved. Below is an example of a property file:

+---
# lines beginning with the # sign are comments

variable1=value1
variable2=value2
+---


* The Assembly Descriptor

  Filtering is only enabled inside \<files\> so that's what we will use. Thus,
  our assembly descriptor will be:

+-----
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>distribution</id>
  <formats>
    <format>jar</format>
  </formats>
  <files>
    <file>
      <source>README.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
    <file>
      <source>LICENSE.txt</source>
      <outputDirectory>/</outputDirectory>
    </file>
    <file>
      <source>NOTICE.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
  </files>
</assembly>
+-----

  The above descriptor tells the Assembly Plugin to filter both the README.txt
  and the NOTICE.txt files and to just copy the LICENSE.txt file.

  Alternatively, if there are many .txt files to include inside \<files\>, we can
  setup both \<fileSets\> and \<files\> like so:

+-----
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>distribution</id>
  <formats>
    <format>jar</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>${basedir}</directory>
      <includes>
        <include>*.txt</include>
      </includes>
      <excludes>
        <exclude>README.txt</exclude>
        <exclude>NOTICE.txt</exclude>
      </excludes>
    </fileSet>
  </fileSets>
  <files>
    <file>
      <source>README.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
    <file>
      <source>NOTICE.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
  </files>
</assembly>
+-----

  The above descriptor adds all .txt files to the assembly but filters README.txt
  and NOTICE.txt files.


* The POM

  The configuration of the Assembly Plugin inside pom.xml should not be
  different from the others, except for the configuration of the filter file, so:

+-----
<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <filters>
            <filter>src/assemble/filter.properties</filter>
          </filters>
          <descriptors>
            <descriptor>src/assemble/distribution.xml</descriptor>
          </descriptors>
        </configuration>
      </plugin>
   [...]
</project>
+-----

* Generating The Assembly

  To generate the distribution assembly, we then use:

+-----
mvn assembly:assembly
+-----