------
 Maven 2 Ear Plugin: configuration examples
 ------
 Stephane Nicoll
 <snicoll@apache.org>
 ------
 September 23, 2005

Introduction

  The Ear plugin allows to generate automatically the descriptor deployment, e.g.
  application.xml. This generation is already customized by the goal's parameters,
  see {{{index.html}the goals description}}.  

  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

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

  Please note that third party libraries 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.

  The security settings might be specified under the security parameter.

Customizing the context root

  The sample below shows how to customize the context root of an artifact to be placed
  in the EAR file:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <webModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <contextRoot>/custom-context-root</contextRoot>
             </webModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

Customizing a module location

  The sample below shows how to place a library in the APP-INF/lib directory of the EAR file:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <bundleDir>APP-INF/lib</bundleDir>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

  Note that it is possible to specify a default bundle directory for all Java modules. If a Java module
  has not the bundleDir property above, the default one is used. Here is an example of such configuration:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <defaultJavaBundleDir>APP-INF/lib</defaultJavaBundleDir>
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <bundleDir>/</bundleDir>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

  In this case, all Java modules will be placed in the APP-INF/lib directory except the specified artifact
  which will be placed at the root of the EAR structure.

Customizing a module file name

  The sample below shows how to rename a module being placed in the EAR file:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <bundleFileName>anotherName-1.2.3.jar</bundleFileName>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

Customizing a module uri

  This is actually a combination of customizing the module's location and file
  name. The sample below shows how to specify the URI of a module being placed
  in the EAR file:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <uri>APP-INF/lib/anotherName-1.2.3.jar</uri>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

Excluding a module

  If for some reason a dependency which is declared in the pom of the project needs to be
  excluded, the excluded flag could be used as follows:

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <excluded>true</excluded>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------

Including a third party library in the generated application.xml

  If third party libraries need to be included in the generated application.xml, the
  'includeInApplicationXml' flag could be used. This flag works only for java modules.

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <modules>
             <javaModule>
               <groupId>artifactGroupId</groupId>
               <artifactId>artifactId</artifactId>
               <includeInApplicationXml>true</includeInApplicationXml>
             </javaModule>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------


Specifying security roles for the generated application.xml

  Security roles might be specified as follows

+--------
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
           [...]
           <security>
            <security-role id="SecurityRole_1234">
              <role-name>manager</role-name>
            </security-role>
            <security-role id="SecurityRole_5678">
              <description>My cool description</description>
              <role-name id="RoleName_12">teller</role-name>
            </security-role>
          </security>
        </configuration>
      </plugin>
    </plugins>
  </build>
+---------