# Chapter 21. 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.

## 21.1. Tasks

The War plugin adds the following tasks to the project.

Table 21.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 21.2. War plugin - additional task dependencies

Task name | Depends on
assemble | war

Figure 21.1. War plugin - tasks

## 21.2. Project layout

Table 21.3. War plugin - project layout

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

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

## 21.4. Convention properties

Table 21.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.

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

Have also a look at `War` .

## 21.6. Customizing

Here is an example with the most important customization options:

Example 21.1. Customization of war plugin

`build.gradle`

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

    group = 'gradle'
    version = '1.0'
    usePlugin('war')
    usePlugin('jetty')

    configurations {
       moreLibs
    }

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

    dependencies {
        compile ":compile:1.0"
        providedCompile ":providedCompile:1.0@jar", "javax.servlet:servlet-api:2.5"
        runtime ":runtime:1.0"
        providedRuntime ":providedRuntime:1.0@jar"
        testCompile "junit:junit:3.8.2"
        moreLibs ":otherLib:1.0"
    }

    war {
        fileSet(dir: file('src/rootContent')) // adds a file-set to the root of the archive
        webInf(dir: file('src/additionalWebInf')) // adds a file-set to the WEB-INF dir.
        additionalLibs(dir: file('additionalLibs')) // adds a file-set to the WEB-INF/lib dir.
        libConfigurations('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 21.2. Generation of JAR archive in addition to WAR archive

`build.gradle`

    jar.enabled = true

## 21.7. Eclipse WTP

`EclipseWtp` has a default instance with the name `eclipseWtp`. It generates a `.settings/org.eclipse.wst.common.component` file.

[18] The `runtime` configuration extends the `compile` configuration.