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