src/site/apt/usage.apt

  ------
  Configuration and Usage
  ------
  Stephane Nicoll
  <snicoll@apache.org>
  ------
  September 23, 2005

~~ 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


Configuration and Usage

* 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 {{{plugin-info.html}the goals description}}.

* Configuring the EAR Plugin

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

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

  When configuring the EAR Plugin in your pom.xml, you do not declare any
  \<executions\> elements 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 so:

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

* Copying resources

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

  For more details, have a look to 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's 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) and <<<full>>>. By specifying <<<full>>> as file
  name mapping, artifacts are prefixed by the <<<groupId>>> where dots have been
  replaced by dashes.

  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.