<!--
  ~ Copyright 2010 the original author or authors.
  ~
  ~ Licensed 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.
  -->
<chapter id='war_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The War Plugin</title>
    <para>The War plugin extends the Java plugin to add support for assembling web application WAR files.
        It disables the default JAR archive generation of the Java plugin and adds a default WAR archive task.
    </para>

    <section>
        <title>Usage</title>
        <para>To use the War plugin, include in your build script:</para>
        <sample id="useWarPlugin" dir="webApplication/quickstart" title="Using the War plugin">
            <sourcefile file="build.gradle" snippet="use-war-plugin"/>
        </sample>
    </section>

    <section>
        <title>Tasks</title>
        <para>The War plugin adds the following tasks to the project.</para>
        <table>
            <title>War plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>war</literal>
                </td>
                <td>
                    <literal>compile</literal>
                </td>
                <td><apilink class="org.gradle.api.tasks.bundling.War"/></td>
                <td>Assembles the application WAR file.</td>
            </tr>
        </table>
        <para>The War plugin adds the following dependencies to tasks added by the Java plugin.</para>
        <table>
            <title>War plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td>assemble</td>
                <td>war</td>
            </tr>
        </table>
        <figure>
            <title>War plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/warPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section>
        <title>Project layout</title>
        <table>
            <title>War plugin - project layout</title>
            <thead>
                <tr>
                    <td>Directory</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>src/main/webapp</filename>
                </td>
                <td>Web application sources</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Dependency management</title>
        <para>The War plugin adds two dependency configurations: <literal>providedCompile</literal> and
            <literal>providedRuntime</literal>. Those configurations have the same scope as the respective
            <literal>compile</literal> and <literal>runtime</literal> configurations, except that they are not added to
            the WAR archive. It is important to note that those <literal>provided</literal> configurations work
            transitively. Let's say you add <literal>commons-httpclient:commons-httpclient:3.0</literal> to any of the
            provided configurations. This dependency has a dependency on <literal>commons-codec</literal>.
            This means neither <literal>httpclient</literal> nor <literal>commons-codec</literal> is added to your
            WAR, even if <literal>commons-codec</literal> were an explicit dependency of your <literal>compile</literal>
            configuration. If you don't want this transitive behavior, simply declare your <literal>provided</literal>
            dependencies like <literal>commons-httpclient:commons-httpclient:3.0@jar</literal>.
        </para>
    </section>

    <section>
        <title>Convention properties</title>
        <table>
            <title>War plugin - directory properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>webAppDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <filename>src/main/webapp</filename>
                </td>
                <td>
                    The name of the web application source directory, relative to the project directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>webAppDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <filename><replaceable>projectDir</replaceable>/<replaceable>webAppDirName</replaceable></filename>
                </td>
                <td>
                    The web application source directory.
                </td>
            </tr>
        </table>

        <para>These properties are provided by a <apilink class="org.gradle.api.plugins.WarPluginConvention"/>
            convention object.
        </para>
    </section>

    <section id='sec:default_settings'>
        <title>War</title>

        <para>The default behavior of the War task is to copy the content of <literal>src/main/webapp</literal>
            to the root of the archive. Your <literal>webapp</literal> directory may of course contain a
            <literal>WEB-INF</literal> sub-directory, which again may contain a <literal>web.xml</literal> file.
            Your compiled classes are compiled to <literal>WEB-INF/classes</literal>. All the dependencies of the
            <literal>runtime</literal>
            <footnote>
                <para>The
                    <literal>runtime</literal>
                    configuration extends the
                    <literal>compile</literal>
                    configuration.
                </para>
            </footnote>
            configuration are copied to <literal>WEB-INF/lib</literal>.</para>
        <para>Have also a look at <apilink class="org.gradle.api.tasks.bundling.War"/>.</para>
    </section>
    <section id='sec:customizing'>
        <title>Customizing</title>
        <para>Here is an example with the most important customization options:
        </para>
        <sample id="webproject" dir="webApplication/customised" title="Customization of war plugin">
            <sourcefile file="build.gradle"/>
        </sample>
        <para>Of course one can configure the different file-sets with a closure to define excludes and includes.
        </para>
        <para>If you want to enable the generation of the default jar archive additional to the war archive just type:
        </para>
        <sample id="customisedWebApplication" dir="webApplication/customised" title="Generation of JAR archive in addition to WAR archive">
            <sourcefile file="build.gradle" snippet="enable-jar"/>
        </sample>
    </section>
</chapter>
