<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. It disables the default jar archive generation of the Java Plugin and
        adds a default war archive task.
    </para>

    <section>
        <title>Tasks</title>
        <para>TBD</para>
    </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>Directory Name Property</td>
                    <td>Directory File Property</td>
                    <td>Default Name</td>
                    <td>Default File</td>
                </tr>
            </thead>
            <tr>
                <td>
                    webAppDirName
                </td>
                <td>
                    webAppDir
                </td>
                <td>
                    <filename>main/webapp</filename>
                </td>
                <td>
                    <filename><replaceable>srcRoot</replaceable>/main/webapp</filename>
                </td>
            </tr>
        </table>
    </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> folder 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" lang="groovy"/>.</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>
    <section id='sec:eclipse_wtp'>
        <title>Eclipse WTP</title>
        <para>
            <apilink class="org.gradle.api.tasks.ide.eclipse.EclipseWtp"/>
            has a default instance with the name <literal>eclipseWtp</literal>. It generates a
            <filename>.settings/org.eclipse.wst.common.component</filename> file.
        </para>
    </section>
</chapter>
