Chapter 23. 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.

23.1. Usage

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

Example 23.1. Using the War plugin

build.gradle

apply plugin: 'war'

23.2. Tasks

The War plugin adds the following tasks to the project.

Table 23.1. War plugin - tasks

Task name	Depends on	Type	Description
`war`	`compile`	`War`	Assembles the application WAR file.

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

Table 23.2. War plugin - additional task dependencies

Task name	Depends on
assemble	war

Figure 23.1. War plugin - tasks

23.3. Project layout

Table 23.3. War plugin - project layout

Directory	Meaning
`src/main/webapp`	Web application sources

23.4. Dependency management

The War plugin adds two dependency configurations: providedCompile and providedRuntime. Those 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. This means neither httpclient nor commons-codec is added to your WAR, even if commons-codec were 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.

23.5. Convention properties

Table 23.4. War plugin - directory properties

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

23.6. 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 again may contain a web.xml file. Your compiled classes are compiled to WEB-INF/classes. All the dependencies of the runtime ^[9] configuration are copied to WEB-INF/lib.

Have also a look at War.

23.7. Customizing

Here is an example with the most important customization options:

Example 23.2. Customization of war plugin

build.gradle

import org.apache.commons.httpclient.HttpClient
import org.apache.commons.httpclient.methods.GetMethod

group = 'gradle'
version = '1.0'
apply plugin: 'war'
apply plugin: 'jetty'

configurations {
   moreLibs
}

repositories {
   flatDir(dirs: "$projectDir/lib")
   mavenCentral()
}

dependencies {
    compile 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"
    }
    runtime ":runtime:1.0"
    providedRuntime ":providedRuntime:1.0@jar"
    testCompile "junit:junit:3.8.2"
    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
}

jar.enabled = true

[jettyRun, jettyRunWar]*.daemon = true
stopKey = 'foo'
stopPort = 9451
httpPort = 8163

task runTest(dependsOn: jettyRun) << {
    callServlet()
}

task runWarTest(dependsOn: jettyRunWar) << {
    callServlet()
}

private void callServlet() {
    HttpClient client = new HttpClient()
    GetMethod method = new GetMethod("http://localhost:$httpPort/customised/hello")
    client.executeMethod(method)
    new File(buildDir, "servlet-out.txt").write(method.getResponseBodyAsString())
    jettyStop.execute()
}

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

If you want to enable the generation of the default jar archive additional to the war archive just type:

Example 23.3. Generation of JAR archive in addition to WAR archive

build.gradle

jar.enabled = true

^[9]The runtime configuration extends the compile configuration.