  ------
  Usage
  ------
  Stephane Nicoll
  <snicoll@apache.org>
  ------
  2010-12-23

~~ Copyright 2006 The Apache Software Foundation.
~~
~~ 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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html


Usage

  To handle archiving this version of Maven EAR Plugin uses
  {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}.

  To handle filtering this version of Maven EAR Plugin uses
  {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}.

* Introduction

  The EAR Plugin allows you to automatically generate the deployment descriptor, e.g.
  <<<application.xml>>>. This generation is customizable by the goal's
  parameters, see {{{./plugin-info.html}the goals description}}.

* Configuring the EAR Plugin

  The configuration of the EAR Plugin is not any different from the configuration
  of any other plugin. The configuration should be similar to:

+-----
<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-ear-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <!-- configuration elements goes here -->
        </configuration>
      </plugin>
   [...]
</project>
+-----

  When configuring the EAR Plugin in your <<<pom.xml>>>, you do not declare an
  <<<\<executions\>>>> element in it because it is always invoked at least once
  during the <<<package>>> phase of an <<<ear>>> project.

* Executing and Generating your EAR Package

  The EAR Plugin replaces the JAR Plugin when your project <<<\<packaging\>>>> is
  <<<ear>>>. So to generate your EAR package, you need only call the <<<package>>>
  phase like this:

+-----
mvn package
+-----

* Copying resources

  The default resource directory for an EAR is <<<src/main/application>>> as
  defined by the <<<earSourceDirectory>>> parameter. The content of this
  directory may be filtered if necessary using the <<<filtering>>> parameter.

  For more details, have a look at the examples.

* Advanced Configuration

  Any EAR module might be further customized as follows:

   * <<bundleDir>>: the directory in the EAR structure where the artifact will be
   stored.

   * <<bundleFileName>>: the name of the artifact in the EAR structure.

   * <<uri>>: the complete path in the EAR structure for the artifact.

   * <<excluded>>: excludes the artifact from the generated EAR.

   * <<unpack>>: unpack the artifact in the generated EAR.

  The context root of a Web module might be customized using the <<<contextRoot>>>
  parameter.

  Please note that third party libraries (i.e. JarModule) are not included
  in the generated <<<application.xml>>> (only <<<ejb-client>>> should be included in
  a <java> entry). However, a <<<jar>>> dependency could be included in the
  generated <<<application.xml>>> by specifying the <<<includeInApplicationXml>>> flag.

  It is also possible to specify a default bundle directory for all third party
  libraries by specifying the <<<defaultLibBundleDir>>> parameter.

  The security settings might be specified under the <<<security>>> parameter.

  The artifact types that should be unpacked by default can be specified
  using the <<<unpackTypes>>> parameter.

  The file name mapping to use for artifacts stored in the EAR can be specified
  using the <<<fileNameMapping>>> parameter. Valid values for this parameter
  are <<<standard>>> (default), <<<full>>>, <<<no-version>>> and
  <<<no-version-for-ejb>>>. By specifying <<<full>>> as file name mapping,
  artifacts are prefixed by the <<<groupId>>> where dots have been replaced by
  dashes. <<<no-version>>> can be used as a replacement of the default mapping;
  the only difference is that the version is omitted. <<<no-version-for-ejb>>>
  is a specialization that omits the version only for ejb-jars and keeps it for
  others ear modules.

  For more information on EAR modules, please see the
  {{{./modules.html}modules configuration}} page.

  You can take a look at the examples for more information on these advanced
  configurations.

* JBoss support

  The EAR Plugin can generate the <<<jboss-app.xml>>> automatically. To do so, the <<<\<jboss\>>>>
  element must be configured and takes the following child elements:

   * <<version>>: the targeted JBoss version to use, 3.2, 4, 4.2 or 5 (the default is 4).

   * <<library-directory>>: the directory where libraries can be found in the EAR (JBoss 4.2+ only).

   * <<security-domain>>: the JNDI name of the security manager (JBoss 4+ only).

   * <<unauthenticated-principal>>: the unauthenticated principal (JBoss 4+ only).

   * <<loader-repository>>: the name of the UnifiedLoaderRepository MBean to use for the EAR to provide
     ear level scoping of classes deployed in the ear. It can have a <<loaderRepositoryClass>> attribute
     that defines the class loader repository class to use.

   * <<loader-repository-config>>: the class loader repository configuration. If no <<loader-repository>>
     element is defined, a default one is added. It can have a <<configParserClass>> attribute that defines
     the class loader's configuration parser class to use.
     
   The POM snippet below fully configures the following loader repository

+-----
<loader-repository loaderRepositoryClass='dot.com.LoaderRepository'>
    dot.com:loader=unique-archive-name
    <loader-repository-config configParserClass='dot.com.LoaderParser'>
        java2ParentDelegation=true
    </loader-repository-config>
</loader-repository>
+-----

+-----
<configuration>
  <jboss>
    [...]
    <loader-repository loaderRepositoryClass="dot.com.LoaderRepository">
      dot.com:loader=unique-archive-name
    </loader-repository>
    <loader-repository-config configParserClass="dot.com.LoaderParser">
      java2ParentDelegation=true
    </loader-repository-config>
  </jboss>
</configuration>
+-----
   
   * <<jmx-name>>: the object name of the EAR MBean.

   * <<module-order>>: specify the order in which the modules specified in the <<<application.xml>>> file gets loaded (JBoss 4.2+ only).

   * <<data-sources>>: specify the desired data source(s) to add into the <<<jboss-app.xml>>>, usage is as follows:

+-----
<configuration>
  <jboss>
    [...]
    <data-sources>
      <data-source>main-ds.xml</data-source>
      <data-source>config/secondary-ds.xml</data-source>
      [...]
    </data-sources>
  </jboss>
</configuration>
+-----
  

  Hibernate archives (HAR) and Service archives (SAR) will be recognized automatically
  and added the the <<<jboss-app.xml>>> file.

  You can take a look at the examples for more information on the JBoss support.