<!--
  ~ Copyright 2009 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="jetty_plugin">
    <title>The Jetty Plugin</title>

    <note>
        <para>
            This plugin is deprecated and will be removed in Gradle 4.0.
            Consider using the more feature-rich <ulink url="https://github.com/akhikhl/gretty">Gretty plugin</ulink> instead.
        </para>
    </note>

    <para>The Jetty plugin extends the War plugin to add tasks which allow you to deploy your web application to a
        Jetty web container embedded in the build.
    </para>

    <section id="sec:jetty_usage">
        <title>Usage</title>
        <para>To use the Jetty plugin, include the following in your build script:</para>
        <sample id="useJettyPlugin" dir="webApplication/quickstart" title="Using the Jetty plugin">
            <sourcefile file="build.gradle" snippet="use-jetty-plugin"/>
        </sample>
    </section>

    <section id="sec:jetty_tasks">
        <title>Tasks</title>
        <para>The Jetty plugin defines the following tasks:</para>
        <table>
            <title>Jetty plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>jettyRun</literal>
                </td>
                <td>
                    <literal>compile</literal>
                </td>
                <td><apilink class="org.gradle.api.plugins.jetty.JettyRun"/></td>
                <td>Starts a Jetty instance and deploys the exploded web application to it.</td>
            </tr>
            <tr>
                <td>
                    <literal>jettyRunWar</literal>
                </td>
                <td>
                    <literal>war</literal>
                </td>
                <td><apilink class="org.gradle.api.plugins.jetty.JettyRunWar"/></td>
                <td>Starts a Jetty instance and deploys the WAR to it.</td>
            </tr>
            <tr>
                <td>
                    <literal>jettyStop</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.jetty.JettyStop"/></td>
                <td>Stops the Jetty instance.</td>
            </tr>
        </table>
        <figure>
            <title>Jetty plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/jettyPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section id="sec:jetty_project_layout">
        <title>Project layout</title>
        <para>The Jetty plugin uses the same layout as the War plugin.</para>
    </section>

    <section id="sec:jetty_dependency_management">
        <title>Dependency management</title>
        <para>The Jetty plugin does not define any dependency configurations.</para>
    </section>

    <section id="sec:jetty_convention_properties">
        <title>Convention properties</title>
        <para>The Jetty plugin defines the following convention properties:</para>
        <table>
            <title>Jetty plugin - properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>contextPath</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    WAR file base name
                </td>
                <td>
                    The application deployment location within the Jetty container.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>httpPort</literal>
                </td>
                <td>
                    <classname>Integer</classname>
                </td>
                <td>
                    <literal>8080</literal>
                </td>
                <td>
                    The TCP port which Jetty should listen for HTTP requests on.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>stopPort</literal>
                </td>
                <td>
                    <classname>Integer</classname>
                </td>
                <td>
                    <literal>null</literal>
                </td>
                <td>
                    The TCP port which Jetty should listen for admin requests on.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>stopKey</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>null</literal>
                </td>
                <td>
                    The key to pass to Jetty when requesting it to stop.
                </td>
            </tr>
        </table>
        <para>These properties are provided by a <apilink class="org.gradle.api.plugins.jetty.JettyPluginConvention"/>
            convention object.</para>
    </section>

</chapter>
