------
 Selecting Contents for Uber JAR
 ------
 Mauro Talevi
 ------
 2008-07-21
 ------

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

Selecting Contents for Uber JAR

  The POM snippet below shows how to control which project dependencies should be included/excluded in the uber JAR:

+-----
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <artifactSet>
                <excludes>
                  <exclude>classworlds:classworlds</exclude>
                  <exclude>junit:junit</exclude>
                  <exclude>jmock:*</exclude>
                  <exclude>*:xml-apis</exclude>
                  <exclude>org.apache.maven:lib:tests</exclude>
                  <exclude>log4j:log4j:jar:</exclude>
                </excludes>
              </artifactSet>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+-----

  Of course, <<<\<includes\>>>> can be used as well to specify a white list of artifacts. Artifacts are denoted by a
  composite idenitifer of the form <groupId>:<artifactId>[[:<type>]:<classifier>]. Since plugin version 1.3, the
  wildcard characters '*' and '?' can be used to do glob-like pattern matching.
  

  For fine-grained control of which classes from the selected dependencies are included, artifact filters can be used:

+-----
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <filters>
                <filter>
                  <artifact>junit:junit</artifact>
                  <includes>
                    <include>junit/framework/**</include>
                    <include>org/junit/**</include>
                  </includes>
                  <excludes>
                    <exclude>org/junit/experimental/**</exclude>
                    <exclude>org/junit/runners/**</exclude>
                  </excludes>
                </filter>
                <filter>
                  <artifact>*:*</artifact>
                  <excludes>
                    <exclude>META-INF/*.SF</exclude>
                    <exclude>META-INF/*.DSA</exclude>
                    <exclude>META-INF/*.RSA</exclude>
                  </excludes>
                </filter>
              </filters>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+-----

  Here, Ant-like patterns are used to specify that from the dependency <<<junit:junit>>> only certain classes/resources
  should be included in the uber JAR. The second filter demonstrates the use of wildcards for the artifact identity which
  was introduced in plugin version 1.3. It excludes all signature related files from every artifact, regardless of its
  group or artifact id.

  Besides user-specified filters, the plugin can also be configured to automatically remove all classes of dependencies
  that are not used by the project, thereby minimizing the resulting uber JAR:

+-----
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <minimizeJar>true</minimizeJar>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+-----

  As of version 1.6, minimizeJar will respect classes that were specifically marked for inclusion in a filter.
  Note that specifying an include filter for classes in an artifact implicitly excludes all non-specified
  classes in that artifact.
  
+-----
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <minimizeJar>true</minimizeJar>
            </configuration>
            <filters>
              <filter>
                 <artifact>log4j:log4j</artifact>
                 <includes>
                     <include>**</include>
                 </includes>
              </filter>
              <filter>
                 <artifact>commons-logging:commons-logging</artifact>
                 <includes>
                     <include>**</include>
                 </includes>
              </filter>
            </filters>            
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+-----