src/site/fml/faq.fml.vm

<?xml version="1.0" encoding="UTF-8"?>

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


<faqs xmlns="http://maven.apache.org/FML/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
  id="FAQ" title="Frequently Asked Questions">
 <part id="General">
   <faq id="filtering">
     <question>How is filtering done in the WAR plugin?</question>
     <answer>
       <p>To enable filtering of <code>web.xml</code> you must configure the WAR Plugin like this:
         <source><![CDATA[
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <filteringDeploymentDescriptors>true</filteringDeploymentDescriptors>
        </configuration>
      </plugin>
]]></source>
       </p>
       <p>Examples can be found <a href="examples/adding-filtering-webresources.html">here</a>.</p>
     </answer>
   </faq>
   <faq id="classifieruse">
     <question>How does the classifier of dependency artifacts affect my WAR project?</question>
     <answer>
       <p>When used, the copy of the dependency artifact in your project will have the classifier appended to its
       filename. This can be used to differentiate duplicate artifacts.</p>
     </answer>
   </faq>
   <faq id="transitiveexclude">
     <question>How do I exclude transitive dependencies from my project?</question>
     <answer>
       <p>Give it a "provided" scope.</p>
     </answer>
   </faq>
   <faq id="dependentwarexclude">
     <question>What's the difference between using dependentWarExclude and provided scope?</question>
     <answer>
       <p><code>dependentWarExclude</code> is used in <a href="overlays.html">overlays</a> for excluding dependent
       WAR files from the assembled webapp.</p>
     </answer>
   </faq>
   <faq id="webresourcesexclude">
     <question>How do I exclude files in my web resources?</question>
     <answer>
       <p>Use the <code>&lt;webResources&gt;</code> / <code>&lt;exclude&gt;</code> parameter to identify the tokens to exclude.</p>
       <p>For more information refer to <a href="examples/adding-filtering-webresources.html">Adding and Filtering
       External Web Resources</a>.</p>
     </answer>
   </faq>
   <faq id="waroverlaysexclude">
     <question>How do I exclude files when doing overlays?</question>
     <answer>
       <p>Use the <code>dependentWarExcludes</code> parameter to identify the tokens to exclude.</p>
     </answer>
   </faq>
   <faq id="configurationdoc">
     <question>Where can I find the documentation for the plugin's configuration?</question>
     <answer>
       <p>
         For each goal, you can use the documentation from the <a href="plugin-info.html">plugin site</a>.
       </p>
       <p>
         If you need a specific version, generate it using <code>mvn site:site</code> or use:
         <source><![CDATA[
mvn help:describe -Dplugin=war -Dfull=true -Dversion=<your-plugin-version-here>
]]></source>
       </p>
     </answer>
   </faq>
   <faq id="attached">
     <question>How do I create a JAR containing the classes in my webapp?</question>
       <answer>
       <p>If you would simply like to package the classes and resources as a JAR in <code>WEB-INF/lib</code>
           rather than as loose files under <code>WEB-INF/classes</code>, use the following configuration:</p>
       <p>
         <source><![CDATA[
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <archiveClasses>true</archiveClasses>
        </configuration>
      </plugin>
]]></source>
       </p>
       <p>If you need to re-use this JAR in another project, the recommended approach is to move the classes to a
       separate module that builds a JAR, and then declare a dependency on that JAR from your webapp as well as from
       any other projects that need it.</p>
       <p>If you can't move the classes to another project, you can deploy the classes and resources included in
           your webapp as an "attached" artifact, with a classifier, by using the following configuration:</p>
       <p>
         <source><![CDATA[
<project>
  ...
  <artifactId>mywebapp</artifactId>
  <version>1.0-SNAPSHOT</version>
  ...
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <attachClasses>true</attachClasses>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
]]></source>
       </p>
       <p>This will result in two artifacts being deployed: <code>mywebapp-1.0-SNAPSHOT.war</code>
       and <code>mywebapp-1.0-SNAPSHOT-classes.jar</code>.</p>
     </answer>
   </faq>
 </part>
</faqs>