// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[ear_plugin]]
== 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.


[[sec:ear_usage]]
=== Usage

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

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="earWithWar" dir="ear/earWithWar" title="Using the Ear plugin">
            <sourcefile file="build.gradle" snippet="use-ear-plugin"/>
            <test args="assemble"/>
        </sample>
++++


[[sec:ear_tasks]]
=== Tasks

The Ear plugin adds the following tasks to the project.

.Ear plugin - tasks
[cols="a,a,a,a", options="header"]
|===
| Task name
| Depends on
| Type
| Description

| `ear`
| `compile` (only if the Java plugin is also applied)
| api:org.gradle.plugins.ear.Ear[]
| Assembles the application EAR file.
|===

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

.Ear plugin - additional task dependencies
[cols="a,a", options="header"]
|===
| Task name
| Depends on
| assemble
| ear
|===


[[sec:ear_project_layout]]
=== Project layout


.Ear plugin - project layout
[cols="a,a", options="header"]
|===
| Directory
| Meaning

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


[[sec:ear_dependency_management]]
=== 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.

[[sec:ear_convention_properties]]
=== Convention properties


.Ear plugin - directory properties
[cols="a,a,a,a", options="header"]
|===
| 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 api:org.gradle.plugins.ear.EarPluginConvention[] convention object.

[[sec:ear_default_settings]]
=== 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 api:org.gradle.plugins.ear.Ear[] class in the API documentation has additional useful information.

[[sec:ear_customizing]]
=== Customizing

Here is an example with the most important customization options:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="earCustomized" dir="ear/earCustomized/ear" title="Customization of ear plugin">
            <sourcefile file="build.gradle"/>
            <test args="assemble"/>
        </sample>
++++

You can also use customization options that the api:org.gradle.plugins.ear.Ear[] task provides, such as `from` and `metaInf`.

[[sec:using_custom_app_xml]]
=== 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.