# Chapter 27. The Ear Plugin

The Ear plugin adds support for assembling web application EAR files. It adds a default EAR archive task. It doesn't require the Java plugin, but for projects that also use the Java plugin it disables the default JAR archive generation.

## 27.1. Usage

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

Example 27.1. Using the Ear plugin

`build.gradle`

    apply plugin: 'ear'

## 27.2. Tasks

The Ear plugin adds the following tasks to the project.

Table 27.1. Ear plugin - tasks

Task name | Depends on | Type | Description
`ear` | `compile` (only if the Java plugin is also applied) | `Ear` | Assembles the application EAR file.

The Ear plugin adds the following dependencies to tasks added by the base plugin.

Table 27.2. Ear plugin - additional task dependencies

Task name | Depends on
assemble | ear

## 27.3. Project layout

Table 27.3. Ear plugin - project layout

Directory | Meaning
`src/main/application` | Ear resources, such as a META-INF directory

## 27.4. Dependency management

The Ear plugin adds two dependency configurations: `deploy` and `earlib`. All dependencies in the `deploy` configuration are placed in the root of the EAR archive, and are not transitive. All dependencies in the `earlib` configuration are placed in the 'lib' directory in the EAR archive and are transitive.

## 27.5. Convention properties

Table 27.4. Ear plugin - directory properties

Property name | Type | Default value | Description
`appDirName` | `String` | `src/main/application` | The name of the application source directory, relative to the project directory.
`libDirName` | `String` | `lib` | The name of the lib directory inside the generated EAR.
`deploymentDescriptor` | `org.gradle.plugins.``ear.descriptor.``DeploymentDescriptor` | A deployment descriptor with sensible defaults named `application.xml` | Metadata to generate a deployment descriptor file, e.g. `application.xml`. If this file already exists in the `appDirName/META-INF` then the existing file contents will be used and the explicit configuration in the `ear.deploymentDescriptor` will be ignored.

These properties are provided by a `EarPluginConvention` convention object.

## 27.6. Ear

The default behavior of the Ear task is to copy the content of `src/main/application` to the root of the archive. If your `application` directory doesn't contain a `META-INF/application.xml` deployment descriptor then one will be generated for you.

The `Ear` class in the API documentation has additional useful information.

## 27.7. Customizing

Here is an example with the most important customization options:

Example 27.2. Customization of ear plugin

`build.gradle`

    apply plugin: 'ear'
    apply plugin: 'java'

    repositories { mavenCentral() }

    dependencies {
        // The following dependencies will be the ear modules and
        // will be placed in the ear root
        deploy project(':war')

        // The following dependencies will become ear libs and will
        // be placed in a dir configured via the libDirName property
        earlib group: 'log4j', name: 'log4j', version: '1.2.15', ext: 'jar'
    }

    ear {
        appDirName 'src/main/app'  // use application metadata found in this folder
        // put dependent libraries into APP-INF/lib inside the generated EAR
        libDirName 'APP-INF/lib'
        deploymentDescriptor {  // custom entries for application.xml:
    //      fileName = "application.xml"  // same as the default value
    //      version = "6"  // same as the default value
            applicationName = "customear"
            initializeInOrder = true
            displayName = "Custom Ear"  // defaults to project.name
            // defaults to project.description if not set
            description = "My customized EAR for the Gradle documentation"
    //      libraryDirectory = "APP-INF/lib"  // not needed, above libDirName setting does this
    //      module("my.jar", "java")  // won't deploy as my.jar isn't deploy dependency
    //      webModule("my.war", "/")  // won't deploy as my.war isn't deploy dependency
            securityRole "admin"
            securityRole "superadmin"
            withXml { provider -> // add a custom node to the XML
                provider.asNode().appendNode("data-source", "my/data/source")
            }
        }
    }

You can also use customization options that the `Ear` task provides, such as `from` and `metaInf`.

## 27.8. Using custom descriptor file

You may already have appropriate settings in a `application.xml` file and want to use that instead of configuring the `ear.deploymentDescriptor` section of the build script. To accommodate that goal, place the `META-INF/application.xml` in the right place inside your source folders (see the `appDirName` property). The file contents will be used and the explicit configuration in the `ear.deploymentDescriptor` will be ignored.