// 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.adoc#java_plugin,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:

.Using the War plugin
====
include::sample[dir="snippets/webApplication/quickstart/groovy",files="build.gradle[tags=use-war-plugin]"]
include::sample[dir="snippets/webApplication/quickstart/kotlin",files="build.gradle.kts[tags=use-war-plugin]"]
====

[[sec:war_project_layout]]
== Project layout

In addition to the <<java_plugin.adoc#sec:java_project_layout,standard Java project layout>>, the War Plugin adds:

`src/main/webapp`::
Web application sources

[[sec:war_tasks]]
== Tasks

The War plugin adds and modifies the following tasks:

`war` — link:{groovyDslPath}/org.gradle.api.tasks.bundling.War.html[War]::
_Depends on_: `compile`
+
Assembles the application WAR file.

`assemble` - _lifecycle task_::
_Depends on_: `war`

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

.War plugin - tasks
image::warPluginTasks.png[]

[[sec:war_dependency_management]]
== Dependency management

The War plugin adds two dependency configurations:

 * `providedCompile`
 * `providedRuntime`

These 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 these `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_plugin_publishing]]
== Publishing

`components.web`::
A link:{javadocPath}/org/gradle/api/component/SoftwareComponent.html[SoftwareComponent] for <<publishing_setup.adoc#publishing_overview,publishing>> the production WAR created by the `war` task.

[[sec:war_convention_properties]]
== Convention properties (deprecated)

`webAppDirName` — `String`::
_Default value_: `src/main/webapp`
+
The name of the web application source directory, relative to the project directory.

`webAppDir` — (read-only) `File`::
_Default value_: `$webAppDirName`, e.g. _src/main/webapp_
+
The path to the web application source directory.

These properties are provided by a link:{groovyDslPath}/org.gradle.api.plugins.WarPluginConvention.html[WarPluginConvention] object.

Configuring war tasks via convention properties is **deprecated**. If you need to set default values the `war` task then configure the task directly. If you want to configure all tasks of type `War` in the project then use link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(War.class).configureEach(...)].

[[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 link:{groovyDslPath}/org.gradle.api.tasks.bundling.War.html[War] class in the API documentation has additional useful information.

[[sec:war_customizing]]
== Customizing

Here is an example with the most important customization options:

.Customization of war plugin
====
include::sample[dir="snippets/webApplication/customized/groovy",files="build.gradle[tags=customization]"]
include::sample[dir="snippets/webApplication/customized/kotlin",files="build.gradle.kts[tags=customization]"]
====

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