// Copyright 2017 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.

[[war_plugin]]
== The War Plugin

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.

[[sec:war_usage]]
=== Usage

To use the War plugin, include the following in your build script:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="useWarPlugin" dir="webApplication/quickstart" title="Using the War plugin">
    <sourcefile file="build.gradle" snippet="use-war-plugin"/>
</sample>
++++

[[sec:war_tasks]]
=== Tasks

The War plugin adds the following tasks to the project.

.War plugin - tasks
[cols="a,a,a,a", options="header"]
|===
| Task name
| Depends on
| Type
| Description

| `war`
| `compile`
| api:org.gradle.api.tasks.bundling.War[]
| Assembles the application WAR file.
|===

The War plugin adds the following dependencies to tasks added by the Java plugin.

.War plugin - additional task dependencies
[cols="a,a", options="header"]
|===
| Task name
| Depends on
| assemble
| war
|===

++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>War plugin - tasks</title>
    <imageobject>
        <imagedata fileref="img/warPluginTasks.png"/>
    </imageobject>
</figure>
++++


[[sec:war_project_layout]]
=== Project layout

.War plugin - project layout
[cols="a,a", options="header"]
|===
| Directory
| Meaning

| `src/main/webapp`
| Web application sources
|===


[[sec:war_dependency_management]]
=== Dependency management

The War plugin adds two dependency configurations named `providedCompile` and `providedRuntime`. Those two configurations have the same scope as the respective `compile` and `runtime` configurations, except that they are not added to the WAR archive. It is important to note that those `provided` configurations work transitively. Let's say you add `commons-httpclient:commons-httpclient:3.0` to any of the provided configurations. This dependency has a dependency on `commons-codec`. Because this is a “provided” configuration, this means that neither of these dependencies will be added to your WAR, even if the `commons-codec` library is an explicit dependency of your `compile` configuration. If you don't want this transitive behavior, simply declare your `provided` dependencies like `commons-httpclient:commons-httpclient:3.0@jar`.

[[sec:war_convention_properties]]
=== Convention properties

.War plugin - directory properties
[cols="a,a,a,a", options="header"]
|===
| Property name
| Type
| Default value
| Description

| `webAppDirName`
| `String`
| `src/main/webapp`
| The name of the web application source directory, relative to the project directory.

| `webAppDir`
| `File` (read-only)
| `__projectDir__/__webAppDirName__`
| The web application source directory.
|===

These properties are provided by a api:org.gradle.api.plugins.WarPluginConvention[] convention object.

[[sec:war_default_settings]]
=== War

The default behavior of the War task is to copy the content of `src/main/webapp` to the root of the archive. Your `webapp` directory may of course contain a `WEB-INF` sub-directory, which may contain a `web.xml` file. Your compiled classes are compiled to `WEB-INF/classes`. All the dependencies of the `runtime` footnote:[The `runtime` configuration extends the `compile` configuration.] configuration are copied to `WEB-INF/lib`.

The api:org.gradle.api.tasks.bundling.War[] class in the API documentation has additional useful information.

[[sec:war_customizing]]
=== Customizing

Here is an example with the most important customization options:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="webproject" dir="webApplication/customized" title="Customization of war plugin">
    <sourcefile file="build.gradle" snippet="customization"/>
</sample>
++++

Of course one can configure the different file-sets with a closure to define excludes and includes.
