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

## 24.1. Usage

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

Example 24.1. Using the Ear plugin

`build.gradle`

    apply plugin: 'ear'

## 24.2. Tasks

The Ear plugin adds the following tasks to the project.

Table 24.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 24.2. Ear plugin - additional task dependencies

Task name | Depends on
assemble | ear

## 24.3. Project layout

Table 24.3. Ear plugin - project layout

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

## 24.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 <em>not</em> transitive. All dependencies in the `earlib` configuration are placed in the 'lib' directory in the EAR archive and <em>are</em> transitive.

## 24.5. Convention properties

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

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

Also have a look at `Ear`.

## 24.7. Customizing

Here is an example with the most important customization options:

Example 24.2. Customization of ear plugin

`build.gradle`

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

    repositories { mavenCentral() }

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

        //following dependencies will become ear libs and placed in a dir configured via 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
        libDirName 'APP-INF/lib'  // put dependency libraries into APP-INF/lib inside the generated EAR;
                                    // also modify the generated deployment descriptor accordingly
        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
            description = "My customized EAR for the Gradle documentation"  // defaults to project.description
    //      libraryDirectory = "APP-INF/lib"  // not needed, because setting libDirName above did this for us
    //      module("my.jar", "java")  // wouldn't deploy since my.jar isn't a deploy depencency
    //      webModule("my.war", "/")  // wouldn't deploy since my.war isn't a deploy depencency
            securityRole "admin"
            securityRole "superadmin"
            withXml { provider -> // add a custom node to the XML
                provider.asNode().appendNode("data-source", "my/data/source")
            }
        }
    }

    jar.enabled = true

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

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

Example 24.3. Generation of JAR archive in addition to EAR archive

`build.gradle`

    jar.enabled = true

## 24.8. Using custom descriptor file

Let's say you already have the `application.xml` and want to use it instead of configuring the `ear.deploymentDescriptor` section. To accommodate that place the `META-INF/application.xml` in the right place inside your source folders (see the `appDirName` property). The existing file contents will be used and the explicit configuration in the `ear.deploymentDescriptor` will be ignored.