# The Ear Plugin

version 8.12

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

    plugins {
        ear
    }

build.gradle

    plugins {
        id '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 (ear)

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

`generateDeploymentDescriptor` — `Boolean`

  Specifies if deploymentDescriptor should be generated. Default value: `true`.

These properties are provided by a EarPluginConvention convention object.

Configuring the ear tasks via the plugin’s convention properties is deprecated. If you need to change from the default values, configure the appropriate tasks directly. If you want to configure all `Ear` tasks in the project, use tasks.withType(Ear.class).configureEach(…​).

## 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.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 = "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")
    }

    tasks.ear {
        appDirectory = file("src/main/app")  // use application metadata found in this folder
        libDirName = "APP-INF/lib" // put dependent libraries into APP-INF/lib inside the generated EAR
        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" })
                }
            }
        }
    }

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: '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'
    }

    tasks.named('ear') {
        appDirectory = file('src/main/app')  // use application metadata found in this folder
        libDirName = 'APP-INF/lib' // put dependent libraries into APP-INF/lib inside the generated EAR
        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`.

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