Chapter 51. The Ear Plugin

Table of Contents

51.1. Usage
51.2. Tasks
51.3. Project layout
51.4. Dependency management
51.5. Convention properties
51.6. Ear
51.7. Customizing
51.8. Using custom descriptor file

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.

51.1. Usage

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

Example 51.1. Using the Ear plugin

build.gradle

apply plugin: 'ear'

51.2. Tasks

The Ear plugin adds the following tasks to the project.

Table 51.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 51.2. Ear plugin - additional task dependencies

Task name Depends on

assemble

ear

51.3. Project layout

Table 51.3. Ear plugin - project layout

Directory Meaning

src/main/application

Ear resources, such as a META-INF directory

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

51.5. Convention properties

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

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

51.7. Customizing

Here is an example with the most important customization options:

Example 51.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(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")
        }
    }
}

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

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