// Copyright (C) 2023 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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/kotlin",files="build.gradle.kts[tags=use-war-plugin]"]
include::sample[dir="snippets/webApplication/quickstart/groovy",files="build.gradle[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`::
This configuration should be used for dependencies required at compilation but which are provided by the environment in which the WAR is deployed.
Dependencies declared here are thus visible to the `main` and `test` compilation classpaths.

`providedRuntime`::
This configuration should be used for dependencies required at runtime but which are provided by the environment in which the WAR is deployed.
Dependencies declared here are only visible to the `main` and `test` runtime classpaths.


[NOTE]
====
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 `implementation` 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/kotlin",files="build.gradle.kts[tags=customization]"]
include::sample[dir="snippets/webApplication/customized/groovy",files="build.gradle[tags=customization]"]
====

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