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

## Usage

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

Example 1. Using the Ear plugin
build.gradle

    plugins {
        id 'ear'
    }

build.gradle.kts

    plugins {
        ear
    }

## Tasks

The Ear plugin adds the following tasks to the project.

`ear` — Ear

  Depends on: `compile` (only if the Java plugin is also applied)

  Assembles the application EAR file.

### Dependencies added to other tasks

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

`assemble`

  Depends on: `ear`.

## Project layout

    .
    └── src
        └── main
            └── application // (1)

1. Ear resources, such as a META-INF directory

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

## Convention properties

`appDirName` — `String`

  The name of the application source directory, relative to the project directory. Default value: `src/main/application`.

`libDirName` — `String`

  The name of the lib directory inside the generated EAR. Default value: `lib`.

`deploymentDescriptor` — DeploymentDescriptor

  Metadata to generate a deployment descriptor file, e.g. `application.xml`. Default value: A deployment descriptor with sensible defaults named `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.

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

## Customizing

Here is an example with the most important customization options:

Example 2. Customization of ear plugin
build.gradle

    plugins {
        id 'ear'
        id 'java'
    }

    repositories { mavenCentral() }

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

        // 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")
            }
        }
    }

build.gradle.kts

    plugins  {
        ear
        java
    }

    repositories { mavenCentral() }

    dependencies {
        // The following dependencies will be the ear modules and
        // will be placed in the ear root
        deploy(project(path = ":war", configuration = "archives"))

        // 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 { // add a custom node to the XML
                asElement().apply {
                    appendChild(ownerDocument.createElement("data-source").apply { textContent = "my/data/source" })
                }
            }
        }
    }

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

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