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:

build.gradle.kts
plugins {
    war
}
build.gradle
plugins {
    id '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:

warWar

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;

warPluginTasks
Figure 1. War plugin - tasks

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.

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.

Publishing

components.web

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

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 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 tasks.withType(War.class).configureEach(…​).

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:

build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    providedCompile("javax.servlet:servlet-api:2.5")
}

tasks.war {
    webAppDirectory = file("src/main/webapp")
    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.
    webXml = file("src/someWeb.xml") // copies a file to WEB-INF/web.xml
}
build.gradle
repositories {
    mavenCentral()
}

dependencies {
    providedCompile "javax.servlet:servlet-api:2.5"
}

war {
    webAppDirectory = file('src/main/webapp')
    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.
    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.