src/site/apt/examples/unpacking-filemapper.apt.vm

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

  ------
  Rewriting target path and file name
  ------
  Markus KARG
  ------
  2018-09-24
  ------

Rewriting target path and file name

  When unpacking files, it is possible to rewrite each unpacked file's target path and file name within the target folder.
  This is useful e. g. to add or remove prefixes (like cutting away top level folders etc.):

+---+
<project>
   [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-dependency-plugin</artifactId>
         <version>${project.version}</version>
         <executions>
           <execution>
             <id>unpack</id>
             <phase>package</phase>
             <goals>
               <goal>unpack</goal>
             </goals>
             <configuration>
               [...]
               <artifactItems>
                 <artifactItem>
                   [...]
                   <fileMappers>
                     <org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
                       <pattern>^\Qx.y/z/\E</pattern>
                       <replacement>./</replacement>
                     </org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
                   </fileMappers>
                   [...]
                 </artifactItem>
               </artifactItems>
               [...]
             </configuration>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>
   [...]
 </project>
+---+

  The above example effectively cuts away the prefix <<<x.y/z/>>> of each unpacked file's path, using a regular
  expression and a replacement expression. Two tricks need to be used here: First, the regular expression uses <<<\Q>>>
  and <<<\E>>> to demarcate pattern quoting, as the dot (<<<.>>>) is special character in a reqular expression. Second,
  due to a restriction of Maven's POM syntax, the replacement cannot be empty (this would skip the file). Instead a
  dot-slash (<<<./>>>) replacement is used, which is effectively a no-op for paths segments.

  Any Plexus File Mapper (i. e. implementation of the interface
  <<<org.codehaus.plexus.components.io.filemappers.FileMapper>>>) can be used, but there are three particularly useful.

  The Regular Expression Mapper is useful to modify or cut away prefixes or suffixes, or to rewrite file extensions:

+---+
 [...]
 <org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
   <pattern>[...]</pattern>
   <replacement>[...]</replacement>
 </org.codehaus.plexus.components.io.filemappers.RegExpFileMapper>
 [...]
+---+

  The Prefix File Mapper is useful to add prefixes:

+---+
 [...]
 <org.codehaus.plexus.components.io.filemappers.PrefixFileMapper>
   <prefix>[...]</prefix>
 </org.codehaus.plexus.components.io.filemappers.PrefixFileMapper>
 [...]
+---+

  The Flatten File Mapper removes the path completey, effectively putting all files in the same folder:

+---+
 [...]
 <org.codehaus.plexus.components.io.filemappers.FlattenFileMapper/>
 [...]
+---+

  When multiple file mappers are given, the list gets executed from top to bottom. This might improve readability of
  the overal rewriting action compared to using a singular (typically complex) regular expression.