# The War Plugin

version 5.5-20190702033235+0000

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.

## Usage

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

Example 1. Using the War plugin
build.gradle

    plugins {
        id 'war'
    }

build.gradle.kts

    plugins {
        war
    }

## Project layout

In addition to the standard Java project layout, the War Plugin adds:

`src/main/webapp`

  Web application sources

## Tasks

The War plugin adds and modifies the following tasks:

`war` — 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;

Figure 1. War plugin - tasks

## 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`.

## Publishing

`components.web`

  A SoftwareComponent for publishing the production WAR created by the `war` task.

## Convention properties

`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 WarPluginConvention object.

## 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` [1] configuration are copied to `WEB-INF/lib`.

The War class in the API documentation has additional useful information.

## Customizing

Here is an example with the most important customization options:

Example 2. Customization of war plugin
build.gradle

    configurations {
       moreLibs
    }

    repositories {
       flatDir { dirs "lib" }
       jcenter()
    }

    dependencies {
        implementation module(":compile:1.0") {
            dependency ":compile-transitive-1.0@jar"
            dependency ":providedCompile-transitive:1.0@jar"
        }
        providedCompile "javax.servlet:servlet-api:2.5"
        providedCompile module(":providedCompile:1.0") {
            dependency ":providedCompile-transitive:1.0@jar"
        }
        runtimeOnly ":runtime:1.0"
        providedRuntime ":providedRuntime:1.0@jar"
        testImplementation "junit:junit:4.12"
        moreLibs ":otherLib:1.0"
    }

    war {
        from 'src/rootContent' // adds a file-set to the root of the archive
        webInf { from 'src/additionalWebInf' } // adds a file-set to the WEB-INF dir.
        classpath fileTree('additionalLibs') // adds a file-set to the WEB-INF/lib dir.
        classpath configurations.moreLibs // adds a configuration to the WEB-INF/lib dir.
        webXml = file('src/someWeb.xml') // copies a file to WEB-INF/web.xml
    }

build.gradle.kts

    val moreLibs = configurations.create("moreLibs")

    repositories {
        flatDir { dir("lib") }
        jcenter()
    }

    dependencies {
        implementation(module(":compile:1.0") {
            dependency(":compile-transitive-1.0@jar")
            dependency( ":providedCompile-transitive:1.0@jar")
        })
        providedCompile("javax.servlet:servlet-api:2.5")
        providedCompile(module(":providedCompile:1.0") {
            dependency(":providedCompile-transitive:1.0@jar")
        })
        runtimeOnly(":runtime:1.0")
        providedRuntime(":providedRuntime:1.0@jar")
        testImplementation("junit:junit:4.12")
        moreLibs(":otherLib:1.0")
    }

    tasks.war {
        from("src/rootContent") // adds a file-set to the root of the archive
        webInf { from("src/additionalWebInf") } // adds a file-set to the WEB-INF dir.
        classpath(fileTree("additionalLibs")) // adds a file-set to the WEB-INF/lib dir.
        classpath(moreLibs) // adds a configuration to the WEB-INF/lib dir.
        webXml = file("src/someWeb.xml") // copies a file to WEB-INF/web.xml
    }

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

1. The `runtime` configuration extends the `compile` configuration.