// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.adoc#java_plugin,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:

.Using the Ear plugin
====
include::sample[dir="snippets/ear/earWithWar/kotlin",files="build.gradle.kts[tags=use-ear-plugin]"]
include::sample[dir="snippets/ear/earWithWar/groovy",files="build.gradle[tags=use-ear-plugin]"]
====

[[sec:ear_tasks]]
== Tasks

The Ear plugin adds the following tasks to the project.

`ear` — link:{groovyDslPath}/org.gradle.plugins.ear.Ear.html[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.adoc#base_plugin,Base Plugin>>.

`assemble`::
_Depends on_: `ear`.


[[sec:ear_project_layout]]
== Project layout

----
.
└── src
    └── main
        └── application // <1>
----
<1> 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)

`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` — link:{javadocPath}/org/gradle/plugins/ear/descriptor/DeploymentDescriptor.html[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 link:{groovyDslPath}/org.gradle.plugins.ear.EarPluginConvention.html[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  link:{javadocPath}/org/gradle/api/DomainObjectCollection.html#withType-java.lang.Class-[tasks.withType(Ear.class).configureEach(...)].

[[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 link:{groovyDslPath}/org.gradle.plugins.ear.Ear.html[Ear] class in the API documentation has additional useful information.

[[sec:ear_customizing]]
== Customizing

Here is an example with the most important customization options:

.Customization of ear plugin
====
include::sample[dir="snippets/ear/earCustomized/kotlin/ear",files="build.gradle.kts[]"]
include::sample[dir="snippets/ear/earCustomized/groovy/ear",files="build.gradle[]"]
====

You can also use customization options that the link:{groovyDslPath}/org.gradle.plugins.ear.Ear.html[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.
