diff --git a/src/site/apt/examples/customize-file-name-mapping.apt.vm b/src/site/apt/examples/customize-file-name-mapping.apt.vm deleted file mode 100644 index 1072f879..00000000 --- a/src/site/apt/examples/customize-file-name-mapping.apt.vm +++ /dev/null @@ -1,81 +0,0 @@ - ------ - Customizing The File Name Mapping - ------ - Stephane Nicoll - - Karl Heinz Marbaise - ------ - 2006-11-19 - -~~ 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 - - -Customizing The File Name Mapping - - It might happen that you need to change the naming of the artifacts within the EAR file. - This can be achieved by using the <<>>. The following shows how it could be - configured in your pom file. - - In this example the default value is given as a starting point. - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - @{groupId}@-@{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ - - - - -+--------- - - Based on the given things you can influence the resulting naming based on your wishes. For example you - want to have all artifacts within your ear file without a version you can change the configuration like the - following: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - @{groupId}@-@{artifactId}@@{dashClassifier?}@.@{extension}@ - - - - -+--------- - - * <<<@\{dashClassifier?\}@>>> - expands to a classifier including the preceding - dash which is needed to separate it from other parts of the artifact - - * <<<@\{version\}@>>> - expands to artifact version, - for <<>> artifacts can contain timestamp postfix instead of <<>> - - * <<<@\{baseVersion\}@>>> - expands to base artifact version, - for <<>> artifacts we will always have <<>> postfix - - [] diff --git a/src/site/apt/examples/customizing-a-module-filename.apt.vm b/src/site/apt/examples/customizing-a-module-filename.apt.vm deleted file mode 100644 index 5cbcf009..00000000 --- a/src/site/apt/examples/customizing-a-module-filename.apt.vm +++ /dev/null @@ -1,51 +0,0 @@ - ------ - Customizing A Module Filename - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -Customizing A Module Filename - - The example below shows how to rename a module being placed in the EAR file: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - anotherName-1.2.3.jar - - - - - - -+--------- diff --git a/src/site/apt/examples/customizing-context-root.apt.vm b/src/site/apt/examples/customizing-context-root.apt.vm deleted file mode 100644 index 53919506..00000000 --- a/src/site/apt/examples/customizing-context-root.apt.vm +++ /dev/null @@ -1,52 +0,0 @@ - ------ - Customizing The Context Root - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -Customizing The Context Root - - The sample below shows how to customize the context root of an artifact to be - placed in the EAR file: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - /custom-context-root - - - - - - -+--------- diff --git a/src/site/apt/examples/customizing-module-location.apt.vm b/src/site/apt/examples/customizing-module-location.apt.vm deleted file mode 100644 index f64ac3c0..00000000 --- a/src/site/apt/examples/customizing-module-location.apt.vm +++ /dev/null @@ -1,82 +0,0 @@ - ------ - Customizing A Module Location - ------ - Stephane Nicoll - - ------ - 2011-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 - - -Customizing A Module Location - - The example below shows how to place a library in the APP-INF/lib directory of - the EAR file: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - APP-INF/lib - - - - - - -+--------- - - Note that it is possible to specify a default bundle directory for all libraries. - If a jarModule does not have the bundleDir property above, the default one is used. - Below is an example of such configuration: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - APP-INF/lib - - - artifactGroupId - artifactId - / - - - - - - -+--------- - - In the above case, jarModules (i.e. libraries) will be placed in the APP-INF/lib directory - except the specified artifact which will be placed at the root of the EAR structure. diff --git a/src/site/apt/examples/customizing-module-uri.apt.vm b/src/site/apt/examples/customizing-module-uri.apt.vm deleted file mode 100644 index 47c38a9e..00000000 --- a/src/site/apt/examples/customizing-module-uri.apt.vm +++ /dev/null @@ -1,53 +0,0 @@ - ------ - Customizing A Module URI - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -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: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - APP-INF/lib/anotherName-1.2.3.jar - - - - - - -+--------- diff --git a/src/site/apt/examples/eclipse-and-maven-integration.apt.vm b/src/site/apt/examples/eclipse-and-maven-integration.apt.vm deleted file mode 100644 index 99274521..00000000 --- a/src/site/apt/examples/eclipse-and-maven-integration.apt.vm +++ /dev/null @@ -1,63 +0,0 @@ - ------ - Eclipse and Maven integration - ------ - Chris Graham - Robert Scholte - ------ - 2013-11-19 - -~~ Copyright 2013 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 - -Eclipse and Maven Integration (without m2e) - - This page describes how to integrate an EAR project in Eclipse or Eclipse-based IDE <> {{{http://www.eclipse.org/m2e/}m2e}} support. - Normally however, using m2e (and m2e-wtp) should be the preferred way to integrate Maven and Eclipse. But in some rare cases that might not be possible. - - If you have used <<>> to generate the metadata for an EAR project, it will want the <<>> file in the <<>> directory. - - If you edit <<>> using the WTP based Application Deployment Descriptor editor, it will use the name of the projects (Web, EJB etc) as the name of the modules. Here is an example: - -+------------------------+ - - - FireDragon - - - FireDragonWeb.war - firedragon - - - -+------------------------+ - - Obviously this does not have the typical Maven based version naming convention applied to it. This allows us to run the application internally within Eclipse using the test environments. - When Maven is used to create the ear using <<>>, it will create the versionized <<>> file, if told to. - However, by default it will not pick up the generated (versionized) one, it will use the existing one in the <<>> directory. - - The solution to resolve this conflict is to have Maven generate the <<>> and use the generated one as opposed to the existing one. - - This can be achieved via these two directives: - -+------------------------+ - true - \${project.build.directory}/application.xml -+------------------------+ - - The first line tells Maven to generate a new <<>> file, by default in the target directory. - The second line tells Maven to use it. diff --git a/src/site/apt/examples/excluding-a-module.apt.vm b/src/site/apt/examples/excluding-a-module.apt.vm deleted file mode 100644 index 3830cdbd..00000000 --- a/src/site/apt/examples/excluding-a-module.apt.vm +++ /dev/null @@ -1,52 +0,0 @@ - ------ - Excluding A Module - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -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: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - true - - - - - - -+--------- diff --git a/src/site/apt/examples/excluding-files-from-ear.apt.vm b/src/site/apt/examples/excluding-files-from-ear.apt.vm deleted file mode 100644 index fd4f7c82..00000000 --- a/src/site/apt/examples/excluding-files-from-ear.apt.vm +++ /dev/null @@ -1,209 +0,0 @@ - ------ - Excluding Files From the EAR - ------ - Dennis Lundberg - ------ - 2011-12-09 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 - -Excluding Files From the EAR - - - It is possible to exclude certain files from the EAR, by using the - <<<\>>> and <<<\>>> configuration - parameters. They each take a comma-separated list of Ant file set patterns. - You can use wildcards such as <<<**>>> to indicate multiple directories and - <<<*>>> to indicate an optional part of a file or directory name. - - -* Shared libraries - - One use case for this is if you want to use shared libraries in your - application server. This involves configuring a location in your application - server that contains some libraries that you want to share between several - EARs. This is a bit like {{{./skinny-wars.html}skinny WARs}}, but taken to the - next level. With skinny WARs you share libraries (JARs) between web - applications within an enterprise application. Shared libraries as described - here shares libraries (JARs) between enterprise applications. - - As an example, let's say that we want to exclude all non-in-house artifacts - from the generated EARs, so that the EAR files we distribute only contains our - own artifacts. The other dependencies we want to put in a shared library on - our application server. They only serve to bloat our EAR files, especially - if we're building or deploying several EARs, each with all of those - dependencies in them. - - Our company in this example, the Acme Corporation, have wisely set a naming - convention for all their in-house artifacts. The artifactId is always prefixed - with "acme-". If they do not use a shared library, the directory layout for - their applications might look like this: - -+-----------------+ - acme-ear-1 - |-- acme-ejb-1.jar - |-- acme-library-1.jar - |-- acme-library-2.jar - |-- acme-war-1.war - |-- acme-war-2.war - |-- external-library-1.jar - |-- external-library-2.jar - `-- external-library-3.jar - - acme-ear-2 - |-- acme-ejb-1.war - |-- acme-library-1.jar - |-- acme-library-2.jar - |-- acme-war-3.war - |-- acme-war-4.war - |-- external-library-2.jar - |-- external-library-3.jar - `-- external-library-4.jar -+-----------------+ - - -** Configuring the EARs - - In order for us to avoid having duplicate copies of the external libraries we - need to do two things. First we make sure that our EARs only contain our own - artifacts. We do this with the <<<\>>> parameter, which - tells the EAR Plugin what files to include in the EAR. Everything else will be - excluded. This configuration should be used in all of Acme's EAR projects, so - it would be better to move this configuration to a parent that is shared - by all of Acme's EAR projects. - -+-----------------+ - - ... - - - - maven-ear-plugin - ${project.version} - - META-INF/**,**/acme-*.jar,**/acme-*.war - - - - - ... - -+-----------------+ - - -** Creating the shared library EAR - - Next we create a shared library EAR that contains all the dependencies that we - want to share between the EARs. In this example we are packaging our shared - library as an EAR. What type of packaging you can use differ between various - application servers. - - <> The <<<\>>> elements of the dependencies have been omitted - here for brevity. - -+-----------------+ - - ... - external-shared-libraries - ear - ... - - - com.external.supplier - external-library-1.jar - - - com.external.supplier - external-library-2.jar - - - com.external.supplier - external-library-3.jar - - - com.external.supplier - external-library-4.jar - - - ... - - - - maven-ear-plugin - ${project.version} - - - - ... - -+-----------------+ - -** The results - - With all the Maven configuration done, the resulting directory layout would - look like this: - -+-----------------+ - external-shared-libraries - |-- external-library-1.jar - |-- external-library-2.jar - |-- external-library-3.jar - `-- external-library-4.jar - - acme-ear-1 - |-- acme-ejb-1.jar - |-- acme-library-1.jar - |-- acme-library-2.jar - |-- acme-war-1.war - `-- acme-war-2.war - - acme-ear-2 - |-- acme-ejb-1.war - |-- acme-library-1.jar - |-- acme-library-2.jar - |-- acme-war-3.war - `-- acme-war-4.war -+-----------------+ - - <> You would also need to configure your application server to use - <<>> as a shared library. How you do that is - however out of scope for this example. - -* Transitive artifacts - - For those who have good reason to exclude transitive dependencies, they can configure their <<>> like this when using Maven3 - -+--------------------- - - GROUPID - ARTIFACTID - VERSION - - - * - * - - - -+--------------------- - - As you can see <<>> support wildcard expressions, so you can have fast and full control over all the dependencies you'd like to exclude. \ No newline at end of file diff --git a/src/site/apt/examples/filtering-advanced.apt.vm b/src/site/apt/examples/filtering-advanced.apt.vm deleted file mode 100644 index 43f59f9c..00000000 --- a/src/site/apt/examples/filtering-advanced.apt.vm +++ /dev/null @@ -1,105 +0,0 @@ - ------ - Filtering Advanced Techniques - ------ - Stephane Nicoll - - ------ - 2009-01-03 - -~~ 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 - - -Filtering: Advanced techniques - - The following features are described in this document: - - * Escaping properties that should not be filtered - - * Ignoring files based on its extension - - -* Escaping properties - - It may be necessary to filters some properties in a file and ignore another. The - filtering mechanism won't touch a token that is not recognized (i.e. that - represents an unknown property). This won't work if the property is known - obviously so it should be escaped explicitely. - - The following configuration defines the value of the <<>> which will - stop the interpolation of a property if it starts with that value - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - true - \ - [...] - - - - -+--------- - - Assuming the following file - -+-------- -jdbc.url=${db.url} -jdbc.user=${db.username} -jdbc.password=${db.password} -+-------- - - Filtering the content of such a file with this config will produce this content. - Note that that the escaped property can now be filtered the usual way later if - necessary! - -+-------- -jdbc.url=jdbc:oracle:thin:@localhost:1521:orcl -jdbc.user=someuser -jdbc.password=${db.password} -+-------- - - -* Ignoring files based on its extension - - Filtering binary files corrupt them so it may be necessary to exclude files from - filtering based on the extension. To do so, configure the plugin as follow - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - true - - png - jpeg - - [...] - - - - -+--------- diff --git a/src/site/apt/examples/filtering-sources.apt.vm b/src/site/apt/examples/filtering-sources.apt.vm deleted file mode 100644 index 431dc736..00000000 --- a/src/site/apt/examples/filtering-sources.apt.vm +++ /dev/null @@ -1,70 +0,0 @@ - ------ - Filtering the sources - ------ - Stephane Nicoll - - ------ - 2009-01-03 - -~~ 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 - - -Filtering the sources - - Filtering the content of the <<>> directory or the - one defined by the <<>> parameter is as easy as: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - true - [...] - - - - -+--------- - - Note that the standard properties are available for filtering. It is also - possible to specify a set of property files to add extra values if - necessary. The configuration below uses also the properties defined in - <<>> - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - true - - src/main/filters/config.properties - - [...] - - - - -+--------- diff --git a/src/site/apt/examples/generating-jboss-app.apt.vm b/src/site/apt/examples/generating-jboss-app.apt.vm deleted file mode 100644 index 2411473d..00000000 --- a/src/site/apt/examples/generating-jboss-app.apt.vm +++ /dev/null @@ -1,50 +0,0 @@ - ------ - Generating the JBoss deployment descriptor file - ------ - Stephane Nicoll - - ------ - 2006-08-06 - -~~ 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 - - -Generating the JBoss deployment descriptor file - - To trigger the generation of the jboss-app.xml file you need to configure the 'jboss' element. For instance - to target version 4 of JBoss with a 'guest' unauthenticated principal and a scoped classloader: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - 4 - guest - com.foo:loader=foo-application-1.0.ear - - - - - -+--------- diff --git a/src/site/apt/examples/generating-modules-id.apt.vm b/src/site/apt/examples/generating-modules-id.apt.vm deleted file mode 100644 index 33268364..00000000 --- a/src/site/apt/examples/generating-modules-id.apt.vm +++ /dev/null @@ -1,71 +0,0 @@ - ------ - Generating modules ID - ------ - Stephane Nicoll - - ------ - 2010-09-04 - -~~ 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 - - -Generating modules ID - - Some environment requires an ID to be generated for each module defined in the <>. Enabling - the automatic IDs generation can be done as follows: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - true - - - - -+--------- - - As a result, each module defined in the <> will have an ID unless an ID was provided in the - configuration. To provide an explicit ID for a given module, use the <> attribute; for instance: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - some-id - - - - - - -+--------- diff --git a/src/site/apt/examples/including-a-third-party-library-in-application-xml.apt.vm b/src/site/apt/examples/including-a-third-party-library-in-application-xml.apt.vm deleted file mode 100644 index f1c4d77f..00000000 --- a/src/site/apt/examples/including-a-third-party-library-in-application-xml.apt.vm +++ /dev/null @@ -1,53 +0,0 @@ - ------ - Including A Third Party Library In application.xml - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -Including A Third Party Library In 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 jar modules - since they define third party libraries packaged within the EAR. - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - artifactGroupId - artifactId - true - - - - - - -+--------- diff --git a/src/site/apt/examples/skinny-modules.apt.vm b/src/site/apt/examples/skinny-modules.apt.vm deleted file mode 100644 index 36033d52..00000000 --- a/src/site/apt/examples/skinny-modules.apt.vm +++ /dev/null @@ -1,191 +0,0 @@ - ------ - Creating Skinny Modules - ------ - Marat Abrarov - ------ - 2020-10-18 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 - -Creating Skinny Modules - - This is a bit like {{{./skinny-wars.html}skinny WARs}}, but taken to the - next level and applied to EAR modules of type: - - * {{{../modules.html#webModule}WAR}} - - * {{{../modules.html#rarModule}RAR}} - - * {{{../modules.html#wsrModule}WSR}} - - * {{{../modules.html#sarModule}SAR}} - - * {{{../modules.html#harModule}HAR}} - - Starting with version 3.2.0, the Maven EAR Plugin supports referencing - external JARs packaged within the EAR via the <<>> setting - in EAR module <<>>. - - You need to change the EAR project's <<>> to package those JARs - in the EAR and to use the - {{{../ear-mojo.html#skinnyModules}skinnyModules}} parameter. - - <> In this example we package all JARs into a <<>> directory - within the EAR. This is just to distinguish between Java EE modules - (which will be packaged in the root of the EAR) and Java libraries - (which are packaged in <<>>). Also, we use non-standard - <<>> to shorten names of files packaged - in EAR and to keep them close to the names used in local repository - for a better readability. - -+-----------------+ - - ... - - - - com.acme - shared-jar - 1.0.0 - - - com.acme - war - 1.0.0 - war - - - com.acme - rar - 1.0.0 - rar - - - com.acme - sar - 1.0.0 - sar - - - ... - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - @{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ - libs/ - true - - - - - ... - -+-----------------+ - - Your EAR will contain something like this: - -+-----------------+ - . - |-- META-INF - | `-- application.xml - |-- libs - | `-- shared-jar-1.0.0.jar - |-- war-1.0.0.war - |-- sar-1.0.0.sar - `-- rar-1.0.0.rar -+-----------------+ - - If you look inside the copies of <<>>, <<>> - and <<>>, that are packaged within the EAR, you will see that - they no longer contain <<>>, - <<>> and <<>> files respectively. - - Also, if you inspect the <<>> of WAR, SAR and HAR modules of EAR - you will notice that the <<>> entry has been modified or added, - if it was missing, and now has a reference to <<>>. - - If an archive representing the EAR module has non-standard location of libraries, - then this location can be configured using the <<>> property. - - Here is example for SAR which contains libraries at the root of the archive - (refer to {{{../modules.html#sarModule}sarModule}} for description of - <<>> property): - -+-----------------+ - - .... - - - - com.acme - shared-jar - 1.0.0 - - - com.acme - war - 1.0.0 - war - - - com.acme - rar - 1.0.0 - rar - - - - com.acme - sar - 1.0.0 - sar - - - ... - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - @{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ - libs/ - true - - - com.acme - sar - / - - - - - - - ... - -+-----------------+ diff --git a/src/site/apt/examples/skinny-wars.apt.vm b/src/site/apt/examples/skinny-wars.apt.vm deleted file mode 100644 index 1adfefd4..00000000 --- a/src/site/apt/examples/skinny-wars.apt.vm +++ /dev/null @@ -1,116 +0,0 @@ - ------ - Creating Skinny WARs - ------ - Mike Perham - Dennis Lundberg - ------ - 2011-12-09 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 - -Creating Skinny WARs - - In a typical J2EE environment, a WAR is packaged within an EAR for deployment. The - WAR can contain all its dependent JARs in <<>> but then the EAR can quickly grow - very large if there are multiple WARs, due to the presence of duplicate JARs. Instead - the J2EE specification allows WARs to reference external JARs packaged within the EAR - via the <<>> setting in their <<>>. - - Starting with version 2.7 Maven EAR Plugin has basic support for this mode of - operation. - - First we need to change the EAR project's <<>> to package those JARs - in the EAR, using the <<>> parameter. - - <> In this example we package all JARs into a <<>> directory - within the EAR. This is just to distinguish between J2EE modules (which will be - packaged in the root of the EAR) and Java libraries (which are packaged in - <<>>). - -+-----------------+ - - ... - - - - maven-ear-plugin - ${project.version} - - lib/ - true - - - - - ... - -+-----------------+ - - Now the painful part. Your EAR project's <<>> needs to list every - dependency that you want to share through the EAR. - -+-----------------+ - - .... - - - - com.acme - shared-jar - 1.0.0 - - - com.acme - war1 - 1.0.0 - war - - - com.acme - war2 - 1.0.0 - war - - - ... - -+-----------------+ - - Your EAR will contain something like this: - -+-----------------+ - . - |-- META-INF - | `-- application.xml - |-- lib - | `-- shared-jar-1.0.0.jar - |-- war1-1.0.0.war - `-- war2-1.0.0.war -+-----------------+ - - If you look inside the copies of <<>> and <<>>, - that are packaged within the EAR, you will see that they no longer contain the - file <<>>. - - Also, if you inspect the <<>> of the WARs you will notice that the - <<>> entry has been modified and now has a reference to - <<>>. diff --git a/src/site/apt/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.apt.vm b/src/site/apt/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.apt.vm deleted file mode 100644 index 880b4216..00000000 --- a/src/site/apt/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.apt.vm +++ /dev/null @@ -1,53 +0,0 @@ - ------ - Specifying Ejb Refs For The Generated application.xml - ------ - Karl Heinz Marbaise - ------ - 2026-02-14 - -~~ 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 - - -Specifying Ejb Ref entries For The Generated application.xml - - Ejb Ref entries can be added as from the JavaEE 6 spec. For instance: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - 6 - [...] - - - A description test - first-name - java.lang.String - java-test - - - - - - -+--------- diff --git a/src/site/apt/examples/specifying-security-roles-for-the-generated-application-xml.apt.vm b/src/site/apt/examples/specifying-security-roles-for-the-generated-application-xml.apt.vm deleted file mode 100644 index 7ef846d5..00000000 --- a/src/site/apt/examples/specifying-security-roles-for-the-generated-application-xml.apt.vm +++ /dev/null @@ -1,53 +0,0 @@ - ------ - Specifying Security Roles For The Generated application.xml - ------ - Stephane Nicoll - - ------ - 2005-09-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 - - -Specifying Security Roles For The Generated application.xml - - Security roles might be specified as follows - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - [...] - - - manager - - - My cool description - teller - - - - - - -+--------- diff --git a/src/site/apt/examples/unpacking-a-module.apt.vm b/src/site/apt/examples/unpacking-a-module.apt.vm deleted file mode 100644 index 9f4df6dd..00000000 --- a/src/site/apt/examples/unpacking-a-module.apt.vm +++ /dev/null @@ -1,74 +0,0 @@ - ------ - Unpacking A Module - ------ - Stephane Nicoll - - ------ - 2006-08-14 - -~~ 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 - - -Unpacking A Module - - If you need to unpack artifacts in the generated EAR, you can configure it in - two ways: - - * Specify the unpack attribute on the required artifact(s) - - * Specify the comma separated list of types to unpack by default - - Note that artifacts are unpacked according to their respective URI. - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - - - artifactGroupId - artifactId - true - - - - - - -+--------- - - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - rar,war,ejb - [...] - - - - -+--------- diff --git a/src/site/apt/examples/using-app-client.apt.vm b/src/site/apt/examples/using-app-client.apt.vm deleted file mode 100644 index e80b5d1a..00000000 --- a/src/site/apt/examples/using-app-client.apt.vm +++ /dev/null @@ -1,54 +0,0 @@ - ------ - Using app client - ------ - Stephane Nicoll - - ------ - 2011-04-03 - -~~ 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 - - -Using JavaEE application clients - - JavaEE application clients are handled by the maven-acr-plugin with the 'app-client' packaging type. Since this - packaging is new to Maven, you have to enable the extensions of the acr plugin for Maven to discover it. This - sample below describes what needs to be added to your project for a 'app-client-sample' application client. By - default the ear plugin adds any application client to the generated application.xml just like it does for other - JavaEE packaging types. - -+-------- - - - com.foo - app-client-sample - 1.0 - app-client - - - - - - org.apache.maven.plugins - maven-acr-plugin - 1.0 - true - - - -+--------- diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index 6562abc9..00000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,172 +0,0 @@ - ------ - Introduction - ------ - Edwin Punzalan - Stephane Nicoll - Dennis Lundberg - ------ - 2013-07-22 - ------ - -~~ 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 - - -${project.name} - - This plugin generates Java EE Enterprise Archive (EAR) file. It can also generate - the deployment descriptor file (e.g. <<>>). - - The EAR plugin supports the following artifacts: - - * ejb - - * war - - * jar - - * ejb-client - - * rar - - * ejb3 - - * par - - * sar - - * wsr - - * har - - * app-client - - [] - - For available configuration options for these artifacts, please see the - {{{./modules.html}modules configuration}}. - - For more information please visit - {{{https://jakarta.ee/}Jakarta EE}} - {{{https://www.oracle.com/java/technologies/java-ee-glance.html}Java EE at a glance}}. - -* Version 3.4.0 - - * Require at least. - - * Support . - -* Version 3.3.0 - - * Require and at least. - - * Support and <10>. - - * Use during packaging - whole modules re-packaging is not needed. - - [] - -* Version 3.2.0 - - {{{./ear-mojo.html#skinnyModules}skinnyModules}} parameter, <<>> property - of EAR modules, <<>> property of EAR modules and <<>> property of - EAR modules have been implemented. - -* Version 3.0.0 - - Starting with version 3.0.0 the usage of <> has been removed. If you need - to use a kind of file name mapping take a look at the new - {{{./examples/customize-file-name-mapping.html}outputFileNameMapping}} which is more - flexible. - -* Goals Overview - - EAR Plugin has two goals: - - * {{{./ear-mojo.html}ear:ear}} generates J2EE Enterprise Archive (EAR) files. - - * {{{./generate-application-xml-mojo.html}ear:generate-application-xml}} - generates the deployment descriptor file(s). - -* Usage - - General instructions on how to use the EAR Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. Further real-life examples are given in the plugin's - {{{./tests.html}test suite}}. - - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - To provide you with better understanding on some usages of the EAR Plugin, - you can take a look into the following examples: - - * {{{./examples/filtering-sources.html}Filtering EAR Resources}} - - * {{{./examples/filtering-advanced.html}Advanced Filtering Techniques}} - - * {{{./examples/skinny-wars.html}Creating Skinny WARs}} - - * {{{./examples/skinny-modules.html}Creating Skinny Modules}} - - * {{{./examples/customizing-a-module-filename.html}Customizing A Module - Filename}} - - * {{{./examples/customizing-context-root.html}Customizing The Context Root}} - - * {{{./examples/customizing-module-location.html}Customizing A Module Location}} - - * {{{./examples/customizing-module-uri.html}Customizing A Module URI}} - - * {{{./examples/excluding-a-module.html}Excluding A Module}} - - * {{{./examples/excluding-files-from-ear.html}Excluding Files From the EAR}} - - * {{{./examples/unpacking-a-module.html}Unpacking A Module}} - - * {{{./examples/including-a-third-party-library-in-application-xml.html} - Including A Third Party Library In application.xml}} - - * {{{./examples/specifying-security-roles-for-the-generated-application-xml.html} - Specifying Security Roles For The Generated application.xml}} - - * {{{./examples/specifying-env-entries-for-the-generated-application-xml.html} - Specifying Environment Entries For The Generated application.xml}} - - * {{{./examples/specifying-resource-ref-entries-for-the-generated-application-xml.html} - Specifying Resource Ref Entries For The Generated application.xml}} - - * {{{./examples/generating-jboss-app.html} Generating the jboss-app.xml file}} - - * {{{./examples/generating-modules-id.html} Generating modules id}} - - * {{{./examples/using-app-client.html} Using JavaEE application clients}} - - * {{{./examples/eclipse-and-maven-integration.html} Eclipse and Maven integration (without m2e)}} - - [] diff --git a/src/site/apt/modules.apt.vm b/src/site/apt/modules.apt.vm deleted file mode 100644 index 488f9a95..00000000 --- a/src/site/apt/modules.apt.vm +++ /dev/null @@ -1,641 +0,0 @@ - ------ - EAR Modules - ------ - Edwin Punzalan - ------ - 2006-07-31 - ------ - -~~ 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 - - -EAR Modules - - The EAR Plugin supports additional configurations of the following modules: - - * {{{ejbClientModule}ejbClientModule}} - - * {{{ejbModule}ejbModule}} - - * {{{jarModule}jarModule}} - - * {{{parModule}parModule}} - - * {{{rarModule}rarModule}} - - * {{{sarModule}sarModule}} - - * {{{webModule}webModule}} - - * {{{wsrModule}wsrModule}} - - * {{{harModule}harModule}} - - * {{{appClientModule}appClientModule}} - - [] - - If the artifact you want to configure is not listed above, you can create your - own custom artifact configuration by following the - {{{Custom_Artifact_Types}adding custom artifact types}} guide below this page. - - These module names go into the <<>> parameter of the EAR Plugin. For - example, to configure the properties of an EjbModule, the EAR Plugin - configuration for <<>> would look like: - -+----- - - [...] - - [...] - - [...] - - maven-ear-plugin - ${project.version} - - - - - - - - - [...] - -+----- - - -* {ejbClientModule} Properties - - The following configuration options are available for EjbClientModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'ejb-client'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the URI path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - sets archive directory which contains Java libraries (JARs) - packaged into archive. Default is <<>> meaning that archive doesn't - contain packaged libraries. - If libraries are located at the root of archive then use single slash ('/') - to configure that. - If <<>> is <<>> then <<>> setting of module - <<>> is modified to reference libraries which are packaged in EAR. - Modification here means: - - * If <<>> has no <<>> setting then it is added. - - * Existing elements of <<>> setting which match libraries packaged - in EAR are replaced with references to the matching libraries in EAR. - - * Other libraries packaged in EAR are appended to <<>> setting in order - of EAR dependency on library if - {{{./ear-mojo.html#skipClassPathModification}skipClassPathModification}} parameter - is false. - - If <<>> is not <<>> and if - {{{./examples/skinny-modules.html}skinny modules}} are used then <<>> - setting in module <<>> is modified and libraries of module located in - <<>> and matching libraries of EAR are removed from module. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is true. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {ejbModule} Properties - - The following configuration options are available for EjbModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'ejb'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - refer to the same name property of {{{ejbClientModule}ejbClientModule}}. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {jarModule} Properties - - The following configuration options are available for JarModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'jar'. Use 'test-jar' if the artifact of the module is test JAR. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - set to true to if you want to generate an entry - of this module in <<>>. Default is false. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is true. - - The module is removed from the <<>> setting of <<>> of another module - if the <<>> property is false and one of the following conditions is met: - - * Another module doesn't contain all of its dependencies (refer to the <<>> - property of particular module type). - - * {{{./ear-mojo.html#skinnyWars}skinnyWars}} parameter is true and another module is - a {{{webModule}webModule}}. - - * {{{./ear-mojo.html#skinnyModules}skinnyModules}} parameter is true. - - Existing reference to the module in the <<>> setting of <<>> - of another module is updated to match location of the module in EAR if - the <<>> property is true and one of the following conditions is met: - - * Another module doesn't contain all of its dependencies (refer to the <<>> - property of particular module type). - - * {{{./ear-mojo.html#skinnyWars}skinnyWars}} parameter is true and another module is - a {{{webModule}webModule}}. - - * {{{./ear-mojo.html#skinnyModules}skinnyModules}} parameter is true. - - The module is added into the <<>> setting of another module - if the <<>> is true, there is no existing reference to the module - in the <<>> setting and one of the following conditions is met: - - * {{{./ear-mojo.html#skinnyWars}skinnyWars}} parameter is true, another module is - a {{{webModule}webModule}} and one of the following conditions is met: - - * {{{./ear-mojo.html#skipClassPathModification}skipClassPathModification}} parameter is false. - - * {{{./ear-mojo.html#version}version}} parameter is less than 5. - - * {{{./ear-mojo.html#skinnyModules}skinnyModules}} parameter is true and - one of the following conditions is met: - - * {{{./ear-mojo.html#skipClassPathModification}skipClassPathModification}} parameter is false. - - * {{{./ear-mojo.html#version}version}} parameter is less than 5. - - -* {parModule} Properties - - The following configuration options are available for ParModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'par'. If the artifact you want to configure is built with - {{{https://github.com/mojohaus/jboss-packaging-maven-plugin}JBoss Packaging Maven Plugin}} - and has 'jboss-par' type, then that type should be specified explicitly. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - refer to the same name property of {{{ejbClientModule}ejbClientModule}}. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {rarModule} Properties - - The following configuration options are available for RarModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'rar'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - sets archive directory which contains Java libraries - packaged into archive. Default is '/' meaning that libraries are located - at the root of archive. Refer to the same name property of - {{{ejbClientModule}ejbClientModule}} for details. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {sarModule} Properties - - The following configuration options are available for SarModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'sar'. If the artifact you want to configure is built with - {{{https://github.com/mojohaus/jboss-packaging-maven-plugin}JBoss Packaging Maven Plugin}} - and has 'jboss-sar' type, then that type should be specified explicitly. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the id of the module in the generated application.xml. - - * <> - sets archive directory which contains Java libraries - packaged into archive. Default is 'lib'. Refer to the same name property of - {{{ejbClientModule}ejbClientModule}} for details. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {webModule} Properties - - The following configuration options are available for WebModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'war'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - sets the context root of this web artifact. - - * <> - sets archive directory which contains Java libraries - packaged into archive. Default is 'WEB-INF/lib'. Refer to the same name property - of {{{ejbClientModule}ejbClientModule}} for details. - If <<>> is not <<>> and if - {{{./examples/skinny-wars.html}skinny WARs}} or - {{{./examples/skinny-modules.html}skinny modules}} are used then <<>> - setting in module <<>> is modified and libraries of module located in - <<>> and matching libraries of EAR are removed from module. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {wsrModule} Properties - - The following configuration options are available for WsrModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'wsr'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - sets archive directory which contains Java libraries - packaged into archive. Default is 'lib'. Refer to the same name property of - {{{ejbClientModule}ejbClientModule}} for details. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {harModule} Properties - - The following configuration options are available for HarModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'har'. If the artifact you want to configure is built with - {{{https://github.com/mojohaus/jboss-packaging-maven-plugin}JBoss Packaging Maven Plugin}} - and has 'jboss-har' type, then that type should be specified explicitly. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets archive directory which contains Java libraries - packaged into archive. Default is 'lib'. Refer to the same name property of - {{{ejbClientModule}ejbClientModule}} for details. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* {appClientModule} Properties - - The following configuration options are available for AppClientModule: - - * <> - sets the groupId of the artifact you want to configure. - - * <> - sets the artifactId of the artifact you want to configure. - - * <> - sets the type of the artifact you want to configure. - Default is 'app-client'. - - * <> - sets the classifier of the artifact you want to - configure if multiple artifacts matches the groupId/artifactId/type. Use - the mainArtifactId ('none' by default) to define the main artifact (e.g. - the artifact without a classifier). - - * <> - sets the location of this artifact inside the ear archive. - If not set, this artifact will be packaged in the root of the archive. - - * <> - sets the new name of this artifact inside the ear - archive. If not set, the artifact's filename in the repository is used. - - * <> - set to true to exclude this artifact from being packaged into - the ear archive. Default is false. - - * <> - sets the uri path of this artifact within the ear archive. - Automatically determined when not set. - - * <> - set to true to unpack this artifact into the ear archive according - to its uri. Default is false. - - * <> - sets the alternative deployment descriptor for - this module. - - * <> - sets the id of the module in the generated application.xml. - - * <> - defines if the module is an element of the <<>> setting - of <<>> of other modules. Default is false. Refer to the <<>> - property of {{{jarModule}jarModule}} for the cases when the module is removed from - the <<>> setting or added into the <<>> setting or existing - reference to the module is updated in the <<>> setting of <<>> - of other modules. - - -* Adding {Custom Artifact Types} - - If you need to map a custom artifact type to one of those types, use the - <<>>. - - For instance, to map a custom 'my-rar' to the 'rar' standard artifact's type, - add the following to the pom's configuration: - -+-------- - - - - org.apache.maven.plugins - maven-ear-plugin - ${project.version} - - - - - - - - -+--------- diff --git a/src/site/apt/tests.apt b/src/site/apt/tests.apt deleted file mode 100644 index 2f867856..00000000 --- a/src/site/apt/tests.apt +++ /dev/null @@ -1,193 +0,0 @@ - ------ - Tests - ------ - Stephane Nicoll - ------ - 2006-10-29 - ------ - -~~ 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 - - -EAR Plugin Tests - - This page lists the EAR Plugin integration tests. Each tests is built on top of a sample project available in - the {{{https://gitbox.apache.org/repos/asf?p=maven-ear-plugin.git;a=tree;f=src/test/resources/projects}git repository}}. - This structure provides lots of concrete use cases for beginners. - - * project-001: builds an EAR with a single EJB and no configuration. - - * project-002: builds an EAR with a customized artifact location and a customized artifact name - - * project-003: builds an EAR with a default bundle directory for _java_ modules - - * project-004: builds an EAR with a default bundle directory for _java_ modules and a custom location overriding the default - - * project-005: builds an EAR with a custom URI - - * project-006: builds an EAR with an excluded module - - * project-007: builds an EAR with a classified artifact and no extra configuration - - * project-008: builds an EAR with deployment descriptor configuration for J2EE 1.3 - - * project-009: builds an EAR with deployment descriptor configuration for J2EE 1.4 - - * project-010: builds an EAR with deployment descriptor configuration for Java EE 5 - - * project-011: builds an EAR and make sure that deployment descriptor default settings are applied - - * project-012: builds an EAR and make sure that EAR resources are bundled within the EAR - - * project-013: builds an EAR and make sure that EAR resources in a customized resources directory are bundled within the EAR - - * project-014: builds an EAR and make sure that EAR resources are bundled within the EAR using includes and excludes - - * project-015: builds an EAR and make sure that default manifest is taken into account - - * project-016: builds an EAR and make sure that custom manifest is taken into account - - * project-017: builds an EAR and make sure that custom application.xml is taken into account - - * project-018: builds an EAR with a custom final name - - * project-019: builds an EAR with unpacked archives using the unpackTypes. - - * project-020: builds an EAR with unpacked archives using the unpack module attribute - - * project-021: builds an EAR with unpacked archives using both unpackTypes and the unpack module attribute - - * project-022: builds an EAR with a classifier - - * project-023: builds an EAR and make sure that a single classified dependency is detected without specifying the classifier - - * project-024: builds an EAR and make sure that a single classified dependency is detected when specifying the classifier - - * project-025: builds an EAR and make sure that a classified dependency with multiple candidates is detected when specifying the classifier - - * project-026: builds an EAR and make sure that the build fails if a unclassified module configuration with multiple candidates is specified - - * project-027: builds an EAR and make sure that provided dependencies are not included in the EAR - - * project-028: builds an EAR and make sure that test dependencies are not included in the EAR - - * project-029: builds an EAR and make sure that system dependencies are not included in the EAR - - * project-030: builds an EAR and make sure that ejb-client dependencies are detected and not added by default in the generated application.xml - - * project-031: builds an EAR with a Jboss 4 configuration specifying the security domain and the unauthenticated-principal to use - - * project-032: builds an EAR with a Jboss 3.2 configuration specifying the jmx-name to use - - * project-033: builds an EAR with a Jboss 4 configuration and Jboss specific modules - - * project-034: builds an EAR with custom security settings - - * project-035: builds an EAR with a full filename mapping and make sure that custom locations are not overridden - - * project-036: builds an EAR with a full filename mapping and make sure that groupIds with dots are replaced by dashes in filenames - - * project-037: builds an EAR and make sure that ejb-client dependencies are detected and added in the generated application.xml if includeInApplicationXml is set - - * project-038: builds an EAR and make sure that a non-classified dependency with multiple candidates is detected when specifying the mainArtifactId as classifier - - * project-039: builds an EAR with a Jboss 4 configuration specifying the loader repository to use - - * project-040: builds an EAR with deployment descriptor configuration for Java EE 5 and an alternative deployment descriptor - - * project-041: builds an EAR with a Jboss 4.2 configuration specifying the module order to use - - * project-042: builds an EAR with a Jboss 4.2 configuration specifying a datasource to add - - * project-043: builds an EAR with a custom descriptor location (generatedDescriptorLocation setting) - - * project-044: builds an EAR with a custom library-directory - - * project-045: builds an EAR and filter the content of the sources directory - - * project-046: builds an EAR and filter the content of the sources directory using a custom filter file - - * project-047: builds an EAR and filter the content with a list of extensions - - * project-048: builds an EAR with a Jboss 5 configuration containing library directory - - * project-049: builds an EAR with a Jboss 4.2 configuration containing a library directory - - * project-050: builds an EAR with a Jboss 5 configuration containing a loader repository configuration definition - - * project-051: builds an EAR with a Jboss 5 configuration containing a loader repository class definition - - * project-052: builds an EAR with a Jboss 5 configuration containing a configuration parser class definition - - * project-053: builds an EAR with a Jboss 5 configuration containing only the loader repo configuration - - * project-054: builds an EAR with deployment descriptor configuration for Java EE 5 and no application.xml - - * project-055: builds an EAR with jar dependencies added in application.xml - - * project-056: builds an EAR with deployment descriptor configuration for J2EE 1.4 and an alternative deployment descriptor - - * project-057: builds an EAR with a complete JBoss 4.2 configuration and validate it matches the DTD (MEAR-104) - - * project-058: builds an EAR with deployment descriptor configuration for Java EE 6 - - * project-059: builds an EAR with no display name entry at all - - * project-060: builds an EAR with ejb-client packaged for J2EE 1.3 - - * project-061: builds an EAR with ejb-client packaged for J2EE 1.4 - - * project-062: builds an EAR with ejb-client packaged for JavaEE 5 - - * project-063: builds an EAR with ejb-client packaged for JavaEE 6 - - * project-064: builds an EAR with ejb-client packaged for JavaEE 5 and still put it in the root - - * project-065: builds an EAR with a custom moduleId - - * project-066: builds an EAR with generateModuleId enabled - - * project-067: builds an EAR with generateModuleId enabled and a custom module - - * project-068: builds an EAR with the no-version file name mapping - - * project-069: builds an EAR with a custom library-directory and JavaEE 6 - - * project-070: builds an EAR with application-name and initialize-in-order tags - - * project-071: builds an EAR with application-name and initialize-in-order tags for unsupported version - - * project-072: builds an EAR with an application client module (app-client) - - * project-073: builds an EAR with an application client module (app-client) and a default bundle directory for _java_ modules - - * project-074: builds an EAR with custom env entries settings and J2EE 1.3 (Not supported by the specification) - - * project-075: builds an EAR with custom env entries settings and J2EE 1.4 (Not supported by the specification) - - * project-076: builds an EAR with custom env entries settings and JavaEE 5 (Not supported by the specification) - - * project-077: builds an EAR with custom env entries settings and JavaEE 6 - - * project-078: builds an EAR with the no version for ejb file name mapping - - * project-079: builds an EAR with the 'default' library directory mode. Uses the value of the defaultLibBundleDir - - * project-080: builds an EAR with the 'empty' library directory mode. Generate an empty library-directory element - - * project-081: builds an EAR with the 'none' library directory mode. Does not generate an library-directory element diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index ee085f2a..00000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,203 +0,0 @@ - ------ - Usage - ------ - Stephane Nicoll - - ------ - 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. - <<>>. 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: - -+----- - - [...] - - [...] - - [...] - - maven-ear-plugin - ${project.version} - - - - - [...] - -+----- - - When configuring the EAR Plugin in your <<>>, you do not declare an - <<<\>>> element in it because it is always invoked at least once - during the <<>> phase of an <<>> project. - -* Executing and Generating your EAR Package - - The EAR Plugin replaces the JAR Plugin when your project <<<\>>> is - <<>>. So to generate your EAR package, you need only call the <<>> - phase like this: - -+----- -mvn package -+----- - -* Copying resources - - The default resource directory for an EAR is <<>> as - defined by the <<>> parameter. The content of this - directory may be filtered if necessary using the <<>> parameter. - - For more details, have a look at the examples. - -* Advanced Configuration - - Any EAR module might be further customized as follows: - - * <>: the directory in the EAR structure where the artifact will be - stored. - - * <>: the name of the artifact in the EAR structure. - - * <>: the complete path in the EAR structure for the artifact. - - * <>: excludes the artifact from the generated EAR. - - * <>: unpack the artifact in the generated EAR. - - The context root of a Web module might be customized using the <<>> - parameter. - - Please note that third party libraries (i.e. JarModule) are not included - in the generated <<>> (only <<>> should be included in - a entry). However, a <<>> dependency could be included in the - generated <<>> by specifying the <<>> flag. - - It is also possible to specify a default bundle directory for all third party - libraries by specifying the <<>> parameter. - - The security settings might be specified under the <<>> parameter. - - The artifact types that should be unpacked by default can be specified - using the <<>> parameter. - - The file name mapping to use for artifacts stored in the EAR can be specified - using the <<>> parameter. Valid values for this parameter - are <<>> (default), <<>>, <<>> and - <<>>. By specifying <<>> as file name mapping, - artifacts are prefixed by the <<>> where dots have been replaced by - dashes. <<>> can be used as a replacement of the default mapping; - the only difference is that the version is omitted. <<>> - 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 <<>> automatically. To do so, the <<<\>>> - element must be configured and takes the following child elements: - - * <>: the targeted JBoss version to use, 3.2, 4, 4.2 or 5 (the default is 4). - - * <>: the directory where libraries can be found in the EAR (JBoss 4.2+ only). - - * <>: the JNDI name of the security manager (JBoss 4+ only). - - * <>: the unauthenticated principal (JBoss 4+ only). - - * <>: 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 <> attribute - that defines the class loader repository class to use. - - * <>: the class loader repository configuration. If no <> - element is defined, a default one is added. It can have a <> attribute that defines - the class loader's configuration parser class to use. - - The POM snippet below fully configures the following loader repository - -+----- - - dot.com:loader=unique-archive-name - - java2ParentDelegation=true - - -+----- - -+----- - - - [...] - - dot.com:loader=unique-archive-name - - - java2ParentDelegation=true - - - -+----- - - * <>: the object name of the EAR MBean. - - * <>: specify the order in which the modules specified in the <<>> file gets loaded (JBoss 4.2+ only). - - * <>: specify the desired data source(s) to add into the <<>>, usage is as follows: - -+----- - - - [...] - - main-ds.xml - config/secondary-ds.xml - [...] - - - -+----- - - - Hibernate archives (HAR) and Service archives (SAR) will be recognized automatically - and added the the <<>> file. - - You can take a look at the examples for more information on the JBoss support. - diff --git a/src/site/markdown/examples/customize-file-name-mapping.md.vm b/src/site/markdown/examples/customize-file-name-mapping.md.vm new file mode 100644 index 00000000..a57d2d18 --- /dev/null +++ b/src/site/markdown/examples/customize-file-name-mapping.md.vm @@ -0,0 +1,59 @@ + + +# Customizing The File Name Mapping + +It might happen that you need to change the naming of the artifacts within the EAR file. This can be achieved by using the `outputFileNameMapping`. The following shows how it could be configured in your pom file. + +In this example the default value is given as a starting point. + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + @{groupId}@-@{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ + + + + +``` + +Based on the given things you can influence the resulting naming based on your wishes. For example you want to have all artifacts within your ear file without a version you can change the configuration like the following: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + @{groupId}@-@{artifactId}@@{dashClassifier?}@.@{extension}@ + + + + +``` + +- `@{dashClassifier?}@` - expands to a classifier including the preceding dash which is needed to separate it from other parts of the artifact +- `@{version}@` - expands to artifact version, for `SNAPSHOT` artifacts can contain timestamp postfix instead of `SNAPSHOT` +- `@{baseVersion}@` - expands to base artifact version, for `SNAPSHOT` artifacts we will always have `SNAPSHOT` postfix diff --git a/src/site/markdown/examples/customizing-a-module-filename.md.vm b/src/site/markdown/examples/customizing-a-module-filename.md.vm new file mode 100644 index 00000000..caf5bf42 --- /dev/null +++ b/src/site/markdown/examples/customizing-a-module-filename.md.vm @@ -0,0 +1,41 @@ + + +# Customizing A Module Filename + +The example below shows how to rename a module being placed in the EAR file: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + anotherName-1.2.3.jar + + + + + + +``` diff --git a/src/site/markdown/examples/customizing-context-root.md.vm b/src/site/markdown/examples/customizing-context-root.md.vm new file mode 100644 index 00000000..eb587cb4 --- /dev/null +++ b/src/site/markdown/examples/customizing-context-root.md.vm @@ -0,0 +1,41 @@ + + +# Customizing The Context Root + +The sample below shows how to customize the context root of an artifact to be placed in the EAR file: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + /custom-context-root + + + + + + +``` diff --git a/src/site/markdown/examples/customizing-module-location.md.vm b/src/site/markdown/examples/customizing-module-location.md.vm new file mode 100644 index 00000000..9886a94b --- /dev/null +++ b/src/site/markdown/examples/customizing-module-location.md.vm @@ -0,0 +1,68 @@ + + +# Customizing A Module Location + +The example below shows how to place a library in the APP-INF/lib directory of the EAR file: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + APP-INF/lib + + + + + + +``` + +Note that it is possible to specify a default bundle directory for all libraries. If a jarModule does not have the bundleDir property above, the default one is used. Below is an example of such configuration: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + APP-INF/lib + + + artifactGroupId + artifactId + / + + + + + + +``` + +In the above case, jarModules (i.e. libraries) will be placed in the APP-INF/lib directory except the specified artifact which will be placed at the root of the EAR structure. diff --git a/src/site/markdown/examples/customizing-module-uri.md.vm b/src/site/markdown/examples/customizing-module-uri.md.vm new file mode 100644 index 00000000..69dfa42d --- /dev/null +++ b/src/site/markdown/examples/customizing-module-uri.md.vm @@ -0,0 +1,41 @@ + + +# 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: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + APP-INF/lib/anotherName-1.2.3.jar + + + + + + +``` diff --git a/src/site/markdown/examples/eclipse-and-maven-integration.md.vm b/src/site/markdown/examples/eclipse-and-maven-integration.md.vm new file mode 100644 index 00000000..85432eed --- /dev/null +++ b/src/site/markdown/examples/eclipse-and-maven-integration.md.vm @@ -0,0 +1,50 @@ + + +# Eclipse and Maven Integration (without m2e) + +This page describes how to integrate an EAR project in Eclipse or Eclipse-based IDE **without** [m2e](http://www.eclipse.org/m2e/) support. Normally however, using m2e (and m2e-wtp) should be the preferred way to integrate Maven and Eclipse. But in some rare cases that might not be possible. + +If you have used `mvn eclipse:eclipse` to generate the metadata for an EAR project, it will want the `application.xml` file in the `src/main/application/META-INF` directory. + +If you edit `application.xml` using the WTP based Application Deployment Descriptor editor, it will use the name of the projects (Web, EJB etc) as the name of the modules. Here is an example: + +```xml + + + FireDragon + + + FireDragonWeb.war + firedragon + + + +``` + +Obviously this does not have the typical Maven based version naming convention applied to it. This allows us to run the application internally within Eclipse using the test environments. When Maven is used to create the ear using `mvn package`, it will create the versionized `application.xml` file, if told to. However, by default it will not pick up the generated (versionized) one, it will use the existing one in the `src/main/application/META-INF` directory. + +The solution to resolve this conflict is to have Maven generate the `application.xml` and use the generated one as opposed to the existing one. + +This can be achieved via these two directives: + +```xml + true + \${project.build.directory}/application.xml +``` + +The first line tells Maven to generate a new `application.xml` file, by default in the target directory. The second line tells Maven to use it. diff --git a/src/site/markdown/examples/excluding-a-module.md.vm b/src/site/markdown/examples/excluding-a-module.md.vm new file mode 100644 index 00000000..383585bb --- /dev/null +++ b/src/site/markdown/examples/excluding-a-module.md.vm @@ -0,0 +1,41 @@ + + +# 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: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + true + + + + + + +``` diff --git a/src/site/markdown/examples/excluding-files-from-ear.md.vm b/src/site/markdown/examples/excluding-files-from-ear.md.vm new file mode 100644 index 00000000..72af69d1 --- /dev/null +++ b/src/site/markdown/examples/excluding-files-from-ear.md.vm @@ -0,0 +1,167 @@ + + +# Excluding Files From the EAR + +It is possible to exclude certain files from the EAR, by using the `` and `` configuration parameters. They each take a comma-separated list of Ant file set patterns. You can use wildcards such as `**` to indicate multiple directories and `*` to indicate an optional part of a file or directory name. + +Shared libraries +---------------- + +One use case for this is if you want to use shared libraries in your application server. This involves configuring a location in your application server that contains some libraries that you want to share between several EARs. This is a bit like [skinny WARs](./skinny-wars.html), but taken to the next level. With skinny WARs you share libraries (JARs) between web applications within an enterprise application. Shared libraries as described here shares libraries (JARs) between enterprise applications. + +As an example, let's say that we want to exclude all non-in-house artifacts from the generated EARs, so that the EAR files we distribute only contains our own artifacts. The other dependencies we want to put in a shared library on our application server. They only serve to bloat our EAR files, especially if we're building or deploying several EARs, each with all of those dependencies in them. + +Our company in this example, the Acme Corporation, have wisely set a naming convention for all their in-house artifacts. The artifactId is always prefixed with "acme-". If they do not use a shared library, the directory layout for their applications might look like this: + +```unknown + acme-ear-1 + |-- acme-ejb-1.jar + |-- acme-library-1.jar + |-- acme-library-2.jar + |-- acme-war-1.war + |-- acme-war-2.war + |-- external-library-1.jar + |-- external-library-2.jar + `-- external-library-3.jar + + acme-ear-2 + |-- acme-ejb-1.war + |-- acme-library-1.jar + |-- acme-library-2.jar + |-- acme-war-3.war + |-- acme-war-4.war + |-- external-library-2.jar + |-- external-library-3.jar + `-- external-library-4.jar +``` + +#[[### Configuring the EARs]]# + +In order for us to avoid having duplicate copies of the external libraries we need to do two things. First we make sure that our EARs only contain our own artifacts. We do this with the `` parameter, which tells the EAR Plugin what files to include in the EAR. Everything else will be excluded. This configuration should be used in all of Acme's EAR projects, so it would be better to move this configuration to a parent that is shared by all of Acme's EAR projects. + +```xml + + ... + + + + maven-ear-plugin + ${project.version} + + META-INF/**,**/acme-*.jar,**/acme-*.war + + + + + ... + +``` + +#[[### Creating the shared library EAR]]# + +Next we create a shared library EAR that contains all the dependencies that we want to share between the EARs. In this example we are packaging our shared library as an EAR. What type of packaging you can use differ between various application servers. + +**Note:** The `` elements of the dependencies have been omitted here for brevity. + +```xml + + ... + external-shared-libraries + ear + ... + + + com.external.supplier + external-library-1.jar + + + com.external.supplier + external-library-2.jar + + + com.external.supplier + external-library-3.jar + + + com.external.supplier + external-library-4.jar + + + ... + + + + maven-ear-plugin + ${project.version} + + + + ... + +``` + +#[[### The results]]# + +With all the Maven configuration done, the resulting directory layout would look like this: + +```unknown + external-shared-libraries + |-- external-library-1.jar + |-- external-library-2.jar + |-- external-library-3.jar + `-- external-library-4.jar + + acme-ear-1 + |-- acme-ejb-1.jar + |-- acme-library-1.jar + |-- acme-library-2.jar + |-- acme-war-1.war + `-- acme-war-2.war + + acme-ear-2 + |-- acme-ejb-1.war + |-- acme-library-1.jar + |-- acme-library-2.jar + |-- acme-war-3.war + `-- acme-war-4.war +``` + +**Note:** You would also need to configure your application server to use `external-shared-libraries` as a shared library. How you do that is however out of scope for this example. + +Transitive artifacts +-------------------- + +For those who have good reason to exclude transitive dependencies, they can configure their `pom.xml` like this when using Maven3 + +```xml + + GROUPID + ARTIFACTID + VERSION + + + * + * + + + +``` + +As you can see `exclusions` support wildcard expressions, so you can have fast and full control over all the dependencies you'd like to exclude. diff --git a/src/site/markdown/examples/filtering-advanced.md.vm b/src/site/markdown/examples/filtering-advanced.md.vm new file mode 100644 index 00000000..f812e196 --- /dev/null +++ b/src/site/markdown/examples/filtering-advanced.md.vm @@ -0,0 +1,87 @@ + + +# Filtering: Advanced techniques + +The following features are described in this document: + +- Escaping properties that should not be filtered +- Ignoring files based on its extension + +Escaping properties +------------------- + +It may be necessary to filters some properties in a file and ignore another. The filtering mechanism won't touch a token that is not recognized (i.e. that represents an unknown property). This won't work if the property is known obviously so it should be escaped explicitely. + +The following configuration defines the value of the `escapeString` which will stop the interpolation of a property if it starts with that value + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + true + \ + [...] + + + + +``` + +Assuming the following file + +```properties +jdbc.url=${db.url} +jdbc.user=${db.username} +jdbc.password=${db.password} +``` + +Filtering the content of such a file with this config will produce this content. Note that that the escaped property can now be filtered the usual way later if necessary\! + +```properties +jdbc.url=jdbc:oracle:thin:@localhost:1521:orcl +jdbc.user=someuser +jdbc.password=${db.password} +``` + +Ignoring files based on its extension +------------------------------------- + +Filtering binary files corrupt them so it may be necessary to exclude files from filtering based on the extension. To do so, configure the plugin as follow + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + true + + png + jpeg + + [...] + + + + +``` diff --git a/src/site/markdown/examples/filtering-sources.md.vm b/src/site/markdown/examples/filtering-sources.md.vm new file mode 100644 index 00000000..3760c898 --- /dev/null +++ b/src/site/markdown/examples/filtering-sources.md.vm @@ -0,0 +1,56 @@ + + +# Filtering the sources + +Filtering the content of the `src/main/application` directory or the one defined by the `earSourceDirectory` parameter is as easy as: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + true + [...] + + + + +``` + +Note that the standard properties are available for filtering. It is also possible to specify a set of property files to add extra values if necessary. The configuration below uses also the properties defined in `src/main/filters/config.properties` + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + true + + src/main/filters/config.properties + + [...] + + + + +``` diff --git a/src/site/markdown/examples/generating-jboss-app.md.vm b/src/site/markdown/examples/generating-jboss-app.md.vm new file mode 100644 index 00000000..e74b2989 --- /dev/null +++ b/src/site/markdown/examples/generating-jboss-app.md.vm @@ -0,0 +1,39 @@ + + +# Generating the JBoss deployment descriptor file + +To trigger the generation of the jboss-app.xml file you need to configure the 'jboss' element. For instance to target version 4 of JBoss with a 'guest' unauthenticated principal and a scoped classloader: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + 4 + guest + com.foo:loader=foo-application-1.0.ear + + + + + +``` diff --git a/src/site/markdown/examples/generating-modules-id.md.vm b/src/site/markdown/examples/generating-modules-id.md.vm new file mode 100644 index 00000000..1ac774cf --- /dev/null +++ b/src/site/markdown/examples/generating-modules-id.md.vm @@ -0,0 +1,59 @@ + + +# Generating modules ID + +Some environment requires an ID to be generated for each module defined in the **application.xml**. Enabling the automatic IDs generation can be done as follows: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + true + + + + +``` + +As a result, each module defined in the **application.xml** will have an ID unless an ID was provided in the configuration. To provide an explicit ID for a given module, use the **moduleId** attribute; for instance: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + some-id + + + + + + +``` diff --git a/src/site/markdown/examples/including-a-third-party-library-in-application-xml.md.vm b/src/site/markdown/examples/including-a-third-party-library-in-application-xml.md.vm new file mode 100644 index 00000000..283f447f --- /dev/null +++ b/src/site/markdown/examples/including-a-third-party-library-in-application-xml.md.vm @@ -0,0 +1,41 @@ + + +# Including A Third Party Library In 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 jar modules since they define third party libraries packaged within the EAR. + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + artifactGroupId + artifactId + true + + + + + + +``` diff --git a/src/site/markdown/examples/skinny-modules.md.vm b/src/site/markdown/examples/skinny-modules.md.vm new file mode 100644 index 00000000..2f90c277 --- /dev/null +++ b/src/site/markdown/examples/skinny-modules.md.vm @@ -0,0 +1,159 @@ + + +# Creating Skinny Modules + +This is a bit like [skinny WARs](./skinny-wars.html), but taken to the next level and applied to EAR modules of type: + +- [WAR](../modules.html#webModule) +- [RAR](../modules.html#rarModule) +- [WSR](../modules.html#wsrModule) +- [SAR](../modules.html#sarModule) +- [HAR](../modules.html#harModule) + +Starting with version 3.2.0, the Maven EAR Plugin supports referencing external JARs packaged within the EAR via the `Class-Path` setting in EAR module `MANIFEST.MF`. + +You need to change the EAR project's `pom.xml` to package those JARs in the EAR and to use the [skinnyModules](../ear-mojo.html#skinnyModules) parameter. + +**Note:** In this example we package all JARs into a `libs/` directory within the EAR. This is just to distinguish between Java EE modules (which will be packaged in the root of the EAR) and Java libraries (which are packaged in `libs/`). Also, we use non-standard `outputFileNameMapping` to shorten names of files packaged in EAR and to keep them close to the names used in local repository for a better readability. + +```xml + + ... + + + + com.acme + shared-jar + 1.0.0 + + + com.acme + war + 1.0.0 + war + + + com.acme + rar + 1.0.0 + rar + + + com.acme + sar + 1.0.0 + sar + + + ... + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + @{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ + libs/ + true + + + + + ... + +``` + +Your EAR will contain something like this: + +```unknown + . + |-- META-INF + | `-- application.xml + |-- libs + | `-- shared-jar-1.0.0.jar + |-- war-1.0.0.war + |-- sar-1.0.0.sar + `-- rar-1.0.0.rar +``` + +If you look inside the copies of `war-1.0.0.war`, `rar-1.0.0.ear` and `sar-1.0.0.sar`, that are packaged within the EAR, you will see that they no longer contain `WEB-INF/lib/shared-jar-1.0.0.jar`, `shared-jar-1.0.0.jar` and `lib/shared-jar-1.0.0.jar` files respectively. + +Also, if you inspect the `MANIFEST.MF` of WAR, SAR and HAR modules of EAR you will notice that the `Class-Path` entry has been modified or added, if it was missing, and now has a reference to `libs/shared-jar-1.0.0.jar`. + +If an archive representing the EAR module has non-standard location of libraries, then this location can be configured using the `libDirectory` property. + +Here is example for SAR which contains libraries at the root of the archive (refer to [sarModule](../modules.html#sarModule) for description of `libDirectory` property): + +```xml + + .... + + + + com.acme + shared-jar + 1.0.0 + + + com.acme + war + 1.0.0 + war + + + com.acme + rar + 1.0.0 + rar + + + + com.acme + sar + 1.0.0 + sar + + + ... + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + @{artifactId}@-@{version}@@{dashClassifier?}@.@{extension}@ + libs/ + true + + + com.acme + sar + / + + + + + + + ... + +``` diff --git a/src/site/markdown/examples/skinny-wars.md.vm b/src/site/markdown/examples/skinny-wars.md.vm new file mode 100644 index 00000000..93a8f0af --- /dev/null +++ b/src/site/markdown/examples/skinny-wars.md.vm @@ -0,0 +1,92 @@ + + +# Creating Skinny WARs + +In a typical J2EE environment, a WAR is packaged within an EAR for deployment. The WAR can contain all its dependent JARs in `WEB-INF/lib` but then the EAR can quickly grow very large if there are multiple WARs, due to the presence of duplicate JARs. Instead the J2EE specification allows WARs to reference external JARs packaged within the EAR via the `Class-Path` setting in their `MANIFEST.MF`. + +Starting with version 2.7 Maven EAR Plugin has basic support for this mode of operation. + +First we need to change the EAR project's `pom.xml` to package those JARs in the EAR, using the `skinnyWars` parameter. + +**Note:** In this example we package all JARs into a `lib/` directory within the EAR. This is just to distinguish between J2EE modules (which will be packaged in the root of the EAR) and Java libraries (which are packaged in `lib/`). + +```xml + + ... + + + + maven-ear-plugin + ${project.version} + + lib/ + true + + + + + ... + +``` + +Now the painful part. Your EAR project's `pom.xml` needs to list every dependency that you want to share through the EAR. + +```xml + + .... + + + + com.acme + shared-jar + 1.0.0 + + + com.acme + war1 + 1.0.0 + war + + + com.acme + war2 + 1.0.0 + war + + + ... + +``` + +Your EAR will contain something like this: + +```unknown + . + |-- META-INF + | `-- application.xml + |-- lib + | `-- shared-jar-1.0.0.jar + |-- war1-1.0.0.war + `-- war2-1.0.0.war +``` + +If you look inside the copies of `war1-1.0.0.war` and `war2-1.0.0.war`, that are packaged within the EAR, you will see that they no longer contain the file `WEB-INF/lib/shared-jar-1.0.0.jar`. + +Also, if you inspect the `MANIFEST.MF` of the WARs you will notice that the `Class-Path` entry has been modified and now has a reference to `lib/shared-jar-1.0.0.jar`. diff --git a/src/site/markdown/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.md.vm b/src/site/markdown/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.md.vm new file mode 100644 index 00000000..15d7cb51 --- /dev/null +++ b/src/site/markdown/examples/specifying-ejb-ref-entries-for-the-generated-application-xml.md.vm @@ -0,0 +1,44 @@ + + +# Specifying Ejb Ref entries For The Generated application.xml + +Ejb Ref entries can be added as from the JavaEE 6 spec. For instance: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + 6 + [...] + + + A description test + first-name + java.lang.String + java-test + + + + + + +``` diff --git a/src/site/apt/examples/specifying-env-entries-for-the-generated-application-xml.apt.vm b/src/site/markdown/examples/specifying-env-entries-for-the-generated-application-xml.md.vm similarity index 51% rename from src/site/apt/examples/specifying-env-entries-for-the-generated-application-xml.apt.vm rename to src/site/markdown/examples/specifying-env-entries-for-the-generated-application-xml.md.vm index fd092af5..ae7a6862 100644 --- a/src/site/apt/examples/specifying-env-entries-for-the-generated-application-xml.apt.vm +++ b/src/site/markdown/examples/specifying-env-entries-for-the-generated-application-xml.md.vm @@ -1,34 +1,24 @@ - ------ - Specifying Security Roles For The Generated application.xml - ------ - Stephane Nicoll - - ------ - 2017-08-27 + -Specifying Environment entries For The Generated application.xml +# Specifying Environment entries For The Generated application.xml - Environment entries can be added as from the JavaEE 6 spec. For instance: +Environment entries can be added as from the JavaEE 6 spec. For instance: -+-------- +```xml @@ -60,4 +50,4 @@ Specifying Environment entries For The Generated application.xml -+--------- +``` diff --git a/src/site/apt/examples/specifying-resource-ref-entries-for-the-generated-application-xml.apt.vm b/src/site/markdown/examples/specifying-resource-ref-entries-for-the-generated-application-xml.md.vm similarity index 50% rename from src/site/apt/examples/specifying-resource-ref-entries-for-the-generated-application-xml.apt.vm rename to src/site/markdown/examples/specifying-resource-ref-entries-for-the-generated-application-xml.md.vm index 3646aad1..cfcb5179 100644 --- a/src/site/apt/examples/specifying-resource-ref-entries-for-the-generated-application-xml.apt.vm +++ b/src/site/markdown/examples/specifying-resource-ref-entries-for-the-generated-application-xml.md.vm @@ -1,33 +1,24 @@ - ------ - Specifying Resource Refs For The Generated application.xml - ------ - Karl Heinz Marbaise - ------ - 2017-08-27 + -Specifying Resource Ref entries For The Generated application.xml +# Specifying Resource Ref entries For The Generated application.xml - Resource Ref entries can be added as from the JavaEE 6 spec. For instance: +Resource Ref entries can be added as from the JavaEE 6 spec. For instance: -+-------- +```xml @@ -59,4 +50,4 @@ Specifying Resource Ref entries For The Generated application.xml -+--------- +``` diff --git a/src/site/markdown/examples/specifying-security-roles-for-the-generated-application-xml.md.vm b/src/site/markdown/examples/specifying-security-roles-for-the-generated-application-xml.md.vm new file mode 100644 index 00000000..823cd8e6 --- /dev/null +++ b/src/site/markdown/examples/specifying-security-roles-for-the-generated-application-xml.md.vm @@ -0,0 +1,43 @@ + + +# Specifying Security Roles For The Generated application.xml + +Security roles might be specified as follows + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + [...] + + + manager + + + My cool description + teller + + + + + + +``` diff --git a/src/site/markdown/examples/unpacking-a-module.md.vm b/src/site/markdown/examples/unpacking-a-module.md.vm new file mode 100644 index 00000000..9355c726 --- /dev/null +++ b/src/site/markdown/examples/unpacking-a-module.md.vm @@ -0,0 +1,61 @@ + + +# Unpacking A Module + +If you need to unpack artifacts in the generated EAR, you can configure it in two ways: + +- Specify the unpack attribute on the required artifact(s) +- Specify the comma separated list of types to unpack by default + + Note that artifacts are unpacked according to their respective URI. + + ```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + + + artifactGroupId + artifactId + true + + + + + + + ``` + + ```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + rar,war,ejb + [...] + + + + + ``` diff --git a/src/site/markdown/examples/using-app-client.md b/src/site/markdown/examples/using-app-client.md new file mode 100644 index 00000000..12e31e56 --- /dev/null +++ b/src/site/markdown/examples/using-app-client.md @@ -0,0 +1,40 @@ + + +# Using JavaEE application clients + +JavaEE application clients are handled by the maven-acr-plugin with the 'app-client' packaging type. Since this packaging is new to Maven, you have to enable the extensions of the acr plugin for Maven to discover it. This sample below describes what needs to be added to your project for a 'app-client-sample' application client. By default the ear plugin adds any application client to the generated application.xml just like it does for other JavaEE packaging types. + +```xml + + + com.foo + app-client-sample + 1.0 + app-client + + + + + + org.apache.maven.plugins + maven-acr-plugin + 1.0 + true + + + +``` diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 00000000..bff0d2c8 --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,92 @@ + + +# Apache Maven EAR Plugin + +This plugin generates Java EE Enterprise Archive (EAR) file. It can also generate the deployment descriptor file (e.g. `application.xml`). + +The EAR plugin supports the following artifacts: + +- ejb +- war +- jar +- ejb-client +- rar +- ejb3 +- par +- sar +- wsr +- har +- app-client + +For available configuration options for these artifacts, please see the [modules configuration](./modules.html). + +For more information please visit [Jakarta EE](https://jakarta.ee/) [Java EE at a glance](https://www.oracle.com/java/technologies/java-ee-glance.html). + +## Version 3.4.0 + +- Require _Maven 3.6.3_ at least. +- Support _Jakarta EE 11_. +## Version 3.3.0 + +- Require _Java 8_ and _Maven 3.2.5_ at least. +- Support _Jakarta EE 9_ and _10_. +- Use _ZipFileSystem_ during _EAR_ packaging - whole modules re-packaging is not needed. +## Version 3.2.0 + +[skinnyModules](./ear-mojo.html#skinnyModules) parameter, `libDirectory` property of EAR modules, `type` property of EAR modules and `classPathItem` property of EAR modules have been implemented. + +## Version 3.0.0 + +Starting with version 3.0.0 the usage of **fileNameMapping** has been removed. If you need to use a kind of file name mapping take a look at the new [outputFileNameMapping](./examples/customize-file-name-mapping.html) which is more flexible. + +## Goals Overview + +EAR Plugin has two goals: + +- [ear:ear](./ear-mojo.html) generates J2EE Enterprise Archive (EAR) files. +- [ear:generate-application-xml](./generate-application-xml-mojo.html) generates the deployment descriptor file(s). +## Usage + +General instructions on how to use the EAR Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. Further real-life examples are given in the plugin's [test suite](./tests.html). + +In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). + +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html). + +## Examples + +To provide you with better understanding on some usages of the EAR Plugin, you can take a look into the following examples: + +- [Filtering EAR Resources](./examples/filtering-sources.html) +- [Advanced Filtering Techniques](./examples/filtering-advanced.html) +- [Creating Skinny WARs](./examples/skinny-wars.html) +- [Creating Skinny Modules](./examples/skinny-modules.html) +- [Customizing A Module Filename](./examples/customizing-a-module-filename.html) +- [Customizing The Context Root](./examples/customizing-context-root.html) +- [Customizing A Module Location](./examples/customizing-module-location.html) +- [Customizing A Module URI](./examples/customizing-module-uri.html) +- [Excluding A Module](./examples/excluding-a-module.html) +- [Excluding Files From the EAR](./examples/excluding-files-from-ear.html) +- [Unpacking A Module](./examples/unpacking-a-module.html) +- [Including A Third Party Library In application.xml](./examples/including-a-third-party-library-in-application-xml.html) +- [Specifying Security Roles For The Generated application.xml](./examples/specifying-security-roles-for-the-generated-application-xml.html) +- [Specifying Environment Entries For The Generated application.xml](./examples/specifying-env-entries-for-the-generated-application-xml.html) +- [Specifying Resource Ref Entries For The Generated application.xml](./examples/specifying-resource-ref-entries-for-the-generated-application-xml.html) +- [Generating the jboss-app.xml file](./examples/generating-jboss-app.html) +- [Generating modules id](./examples/generating-modules-id.html) +- [Using JavaEE application clients](./examples/using-app-client.html) +- [Eclipse and Maven integration (without m2e)](./examples/eclipse-and-maven-integration.html) diff --git a/src/site/markdown/modules.md.vm b/src/site/markdown/modules.md.vm new file mode 100644 index 00000000..3665ef3b --- /dev/null +++ b/src/site/markdown/modules.md.vm @@ -0,0 +1,294 @@ + + +# EAR Modules + +The EAR Plugin supports additional configurations of the following modules: + +- [ejbClientModule](#ejbClientModule) +- [ejbModule](#ejbModule) +- [jarModule](#jarModule) +- [parModule](#parModule) +- [rarModule](#rarModule) +- [sarModule](#sarModule) +- [webModule](#webModule) +- [wsrModule](#wsrModule) +- [harModule](#harModule) +- [appClientModule](#appClientModule) + +If the artifact you want to configure is not listed above, you can create your own custom artifact configuration by following the [adding custom artifact types](#Custom_Artifact_Types) guide below this page. + +These module names go into the `modules` parameter of the EAR Plugin. For example, to configure the properties of an EjbModule, the EAR Plugin configuration for `modules` would look like: + +```xml + + [...] + + [...] + + [...] + + maven-ear-plugin + ${project.version} + + + + + + + + + [...] + +``` + +ejbClientModule Properties +------------------------------------------------------ + +The following configuration options are available for EjbClientModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'ejb-client'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the URI path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - sets archive directory which contains Java libraries (JARs) packaged into archive. Default is `null` meaning that archive doesn't contain packaged libraries. If libraries are located at the root of archive then use single slash ('/') to configure that. If `libDirectory` is `null` then `Class-Path` setting of module `MANIFEST.MF` is modified to reference libraries which are packaged in EAR. Modification here means: + - If `MANIFEST.MF` has no `Class-Path` setting then it is added. + - Existing elements of `Class-Path` setting which match libraries packaged in EAR are replaced with references to the matching libraries in EAR. + - Other libraries packaged in EAR are appended to `Class-Path` setting in order of EAR dependency on library if [skipClassPathModification](./ear-mojo.html#skipClassPathModification) parameter is false. + + If `libDirectory` is not `null` and if [skinny modules](./examples/skinny-modules.html) are used then `Class-Path` setting in module `MANIFEST.MF` is modified and libraries of module located in `libDirectory` and matching libraries of EAR are removed from module. + +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is true. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +ejbModule Properties +------------------------------------------ + +The following configuration options are available for EjbModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'ejb'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - refer to the same name property of [ejbClientModule](#ejbClientModule). +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +jarModule Properties +------------------------------------------ + +The following configuration options are available for JarModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'jar'. Use 'test-jar' if the artifact of the module is test JAR. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **includeInApplicationXml** - set to true to if you want to generate an entry of this module in `application.xml`. Default is false. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is true. + + The module is removed from the `Class-Path` setting of `MANIFEST.MF` of another module if the `classPathItem` property is false and one of the following conditions is met: + + - Another module doesn't contain all of its dependencies (refer to the `libDirectory` property of particular module type). + - [skinnyWars](./ear-mojo.html#skinnyWars) parameter is true and another module is a [webModule](#webModule). + - [skinnyModules](./ear-mojo.html#skinnyModules) parameter is true. + + Existing reference to the module in the `Class-Path` setting of `MANIFEST.MF` of another module is updated to match location of the module in EAR if the `classPathItem` property is true and one of the following conditions is met: + + - Another module doesn't contain all of its dependencies (refer to the `libDirectory` property of particular module type). + - [skinnyWars](./ear-mojo.html#skinnyWars) parameter is true and another module is a [webModule](#webModule). + - [skinnyModules](./ear-mojo.html#skinnyModules) parameter is true. + + The module is added into the `Class-Path` setting of another module if the `classPathItem` is true, there is no existing reference to the module in the `Class-Path` setting and one of the following conditions is met: + + - [skinnyWars](./ear-mojo.html#skinnyWars) parameter is true, another module is a [webModule](#webModule) and one of the following conditions is met: + - [skipClassPathModification](./ear-mojo.html#skipClassPathModification) parameter is false. + - [version](./ear-mojo.html#version) parameter is less than 5. + - [skinnyModules](./ear-mojo.html#skinnyModules) parameter is true and one of the following conditions is met: + - [skipClassPathModification](./ear-mojo.html#skipClassPathModification) parameter is false. + - [version](./ear-mojo.html#version) parameter is less than 5. + +parModule Properties +------------------------------------------ + +The following configuration options are available for ParModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'par'. If the artifact you want to configure is built with [JBoss Packaging Maven Plugin](https://github.com/mojohaus/jboss-packaging-maven-plugin) and has 'jboss-par' type, then that type should be specified explicitly. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - refer to the same name property of [ejbClientModule](#ejbClientModule). +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +rarModule Properties +------------------------------------------ + +The following configuration options are available for RarModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'rar'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - sets archive directory which contains Java libraries packaged into archive. Default is '/' meaning that libraries are located at the root of archive. Refer to the same name property of [ejbClientModule](#ejbClientModule) for details. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +sarModule Properties +------------------------------------------ + +The following configuration options are available for SarModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'sar'. If the artifact you want to configure is built with [JBoss Packaging Maven Plugin](https://github.com/mojohaus/jboss-packaging-maven-plugin) and has 'jboss-sar' type, then that type should be specified explicitly. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - sets archive directory which contains Java libraries packaged into archive. Default is 'lib'. Refer to the same name property of [ejbClientModule](#ejbClientModule) for details. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +webModule Properties +------------------------------------------ + +The following configuration options are available for WebModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'war'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **contextRoot** - sets the context root of this web artifact. +- **libDirectory** - sets archive directory which contains Java libraries packaged into archive. Default is 'WEB-INF/lib'. Refer to the same name property of [ejbClientModule](#ejbClientModule) for details. If `libDirectory` is not `null` and if [skinny WARs](./examples/skinny-wars.html) or [skinny modules](./examples/skinny-modules.html) are used then `Class-Path` setting in module `MANIFEST.MF` is modified and libraries of module located in `libDirectory` and matching libraries of EAR are removed from module. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +wsrModule Properties +------------------------------------------ + +The following configuration options are available for WsrModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'wsr'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **libDirectory** - sets archive directory which contains Java libraries packaged into archive. Default is 'lib'. Refer to the same name property of [ejbClientModule](#ejbClientModule) for details. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +harModule Properties +------------------------------------------ + +The following configuration options are available for HarModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'har'. If the artifact you want to configure is built with [JBoss Packaging Maven Plugin](https://github.com/mojohaus/jboss-packaging-maven-plugin) and has 'jboss-har' type, then that type should be specified explicitly. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **libDirectory** - sets archive directory which contains Java libraries packaged into archive. Default is 'lib'. Refer to the same name property of [ejbClientModule](#ejbClientModule) for details. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +appClientModule Properties +------------------------------------------------------ + +The following configuration options are available for AppClientModule: + +- **groupId** - sets the groupId of the artifact you want to configure. +- **artifactId** - sets the artifactId of the artifact you want to configure. +- **type** - sets the type of the artifact you want to configure. Default is 'app-client'. +- **classifier** - sets the classifier of the artifact you want to configure if multiple artifacts matches the groupId/artifactId/type. Use the mainArtifactId ('none' by default) to define the main artifact (e.g. the artifact without a classifier). +- **bundleDir** - sets the location of this artifact inside the ear archive. If not set, this artifact will be packaged in the root of the archive. +- **bundleFileName** - sets the new name of this artifact inside the ear archive. If not set, the artifact's filename in the repository is used. +- **excluded** - set to true to exclude this artifact from being packaged into the ear archive. Default is false. +- **uri** - sets the uri path of this artifact within the ear archive. Automatically determined when not set. +- **unpack** - set to true to unpack this artifact into the ear archive according to its uri. Default is false. +- **altDeploymentDescriptor** - sets the alternative deployment descriptor for this module. +- **moduleId** - sets the id of the module in the generated application.xml. +- **classPathItem** - defines if the module is an element of the `Class-Path` setting of `MANIFEST.MF` of other modules. Default is false. Refer to the `classPathItem` property of [jarModule](#jarModule) for the cases when the module is removed from the `Class-Path` setting or added into the `Class-Path` setting or existing reference to the module is updated in the `Class-Path` setting of `MANIFEST.MF` of other modules. + +Adding Custom Artifact Types +-------------------------------------------------------------- + +If you need to map a custom artifact type to one of those types, use the `customArtifactTypeMappings`. + +For instance, to map a custom 'my-rar' to the 'rar' standard artifact's type, add the following to the pom's configuration: + +```xml + + + + org.apache.maven.plugins + maven-ear-plugin + ${project.version} + + + + + + + + +``` diff --git a/src/site/markdown/tests.md b/src/site/markdown/tests.md new file mode 100644 index 00000000..dc1a96da --- /dev/null +++ b/src/site/markdown/tests.md @@ -0,0 +1,101 @@ + + +# EAR Plugin Tests + +This page lists the EAR Plugin integration tests. Each tests is built on top of a sample project available in the [git repository](https://gitbox.apache.org/repos/asf?p=maven-ear-plugin.git;a=tree;f=src/test/resources/projects). This structure provides lots of concrete use cases for beginners. + +- project-001: builds an EAR with a single EJB and no configuration. +- project-002: builds an EAR with a customized artifact location and a customized artifact name +- project-003: builds an EAR with a default bundle directory for \_java\_ modules +- project-004: builds an EAR with a default bundle directory for \_java\_ modules and a custom location overriding the default +- project-005: builds an EAR with a custom URI +- project-006: builds an EAR with an excluded module +- project-007: builds an EAR with a classified artifact and no extra configuration +- project-008: builds an EAR with deployment descriptor configuration for J2EE 1.3 +- project-009: builds an EAR with deployment descriptor configuration for J2EE 1.4 +- project-010: builds an EAR with deployment descriptor configuration for Java EE 5 +- project-011: builds an EAR and make sure that deployment descriptor default settings are applied +- project-012: builds an EAR and make sure that EAR resources are bundled within the EAR +- project-013: builds an EAR and make sure that EAR resources in a customized resources directory are bundled within the EAR +- project-014: builds an EAR and make sure that EAR resources are bundled within the EAR using includes and excludes +- project-015: builds an EAR and make sure that default manifest is taken into account +- project-016: builds an EAR and make sure that custom manifest is taken into account +- project-017: builds an EAR and make sure that custom application.xml is taken into account +- project-018: builds an EAR with a custom final name +- project-019: builds an EAR with unpacked archives using the unpackTypes. +- project-020: builds an EAR with unpacked archives using the unpack module attribute +- project-021: builds an EAR with unpacked archives using both unpackTypes and the unpack module attribute +- project-022: builds an EAR with a classifier +- project-023: builds an EAR and make sure that a single classified dependency is detected without specifying the classifier +- project-024: builds an EAR and make sure that a single classified dependency is detected when specifying the classifier +- project-025: builds an EAR and make sure that a classified dependency with multiple candidates is detected when specifying the classifier +- project-026: builds an EAR and make sure that the build fails if a unclassified module configuration with multiple candidates is specified +- project-027: builds an EAR and make sure that provided dependencies are not included in the EAR +- project-028: builds an EAR and make sure that test dependencies are not included in the EAR +- project-029: builds an EAR and make sure that system dependencies are not included in the EAR +- project-030: builds an EAR and make sure that ejb-client dependencies are detected and not added by default in the generated application.xml +- project-031: builds an EAR with a Jboss 4 configuration specifying the security domain and the unauthenticated-principal to use +- project-032: builds an EAR with a Jboss 3.2 configuration specifying the jmx-name to use +- project-033: builds an EAR with a Jboss 4 configuration and Jboss specific modules +- project-034: builds an EAR with custom security settings +- project-035: builds an EAR with a full filename mapping and make sure that custom locations are not overridden +- project-036: builds an EAR with a full filename mapping and make sure that groupIds with dots are replaced by dashes in filenames +- project-037: builds an EAR and make sure that ejb-client dependencies are detected and added in the generated application.xml if includeInApplicationXml is set +- project-038: builds an EAR and make sure that a non-classified dependency with multiple candidates is detected when specifying the mainArtifactId as classifier +- project-039: builds an EAR with a Jboss 4 configuration specifying the loader repository to use +- project-040: builds an EAR with deployment descriptor configuration for Java EE 5 and an alternative deployment descriptor +- project-041: builds an EAR with a Jboss 4.2 configuration specifying the module order to use +- project-042: builds an EAR with a Jboss 4.2 configuration specifying a datasource to add +- project-043: builds an EAR with a custom descriptor location (generatedDescriptorLocation setting) +- project-044: builds an EAR with a custom library-directory +- project-045: builds an EAR and filter the content of the sources directory +- project-046: builds an EAR and filter the content of the sources directory using a custom filter file +- project-047: builds an EAR and filter the content with a list of extensions +- project-048: builds an EAR with a Jboss 5 configuration containing library directory +- project-049: builds an EAR with a Jboss 4.2 configuration containing a library directory +- project-050: builds an EAR with a Jboss 5 configuration containing a loader repository configuration definition +- project-051: builds an EAR with a Jboss 5 configuration containing a loader repository class definition +- project-052: builds an EAR with a Jboss 5 configuration containing a configuration parser class definition +- project-053: builds an EAR with a Jboss 5 configuration containing only the loader repo configuration +- project-054: builds an EAR with deployment descriptor configuration for Java EE 5 and no application.xml +- project-055: builds an EAR with jar dependencies added in application.xml +- project-056: builds an EAR with deployment descriptor configuration for J2EE 1.4 and an alternative deployment descriptor +- project-057: builds an EAR with a complete JBoss 4.2 configuration and validate it matches the DTD (MEAR-104) +- project-058: builds an EAR with deployment descriptor configuration for Java EE 6 +- project-059: builds an EAR with no display name entry at all +- project-060: builds an EAR with ejb-client packaged for J2EE 1.3 +- project-061: builds an EAR with ejb-client packaged for J2EE 1.4 +- project-062: builds an EAR with ejb-client packaged for JavaEE 5 +- project-063: builds an EAR with ejb-client packaged for JavaEE 6 +- project-064: builds an EAR with ejb-client packaged for JavaEE 5 and still put it in the root +- project-065: builds an EAR with a custom moduleId +- project-066: builds an EAR with generateModuleId enabled +- project-067: builds an EAR with generateModuleId enabled and a custom module +- project-068: builds an EAR with the no-version file name mapping +- project-069: builds an EAR with a custom library-directory and JavaEE 6 +- project-070: builds an EAR with application-name and initialize-in-order tags +- project-071: builds an EAR with application-name and initialize-in-order tags for unsupported version +- project-072: builds an EAR with an application client module (app-client) +- project-073: builds an EAR with an application client module (app-client) and a default bundle directory for \_java\_ modules +- project-074: builds an EAR with custom env entries settings and J2EE 1.3 (Not supported by the specification) +- project-075: builds an EAR with custom env entries settings and J2EE 1.4 (Not supported by the specification) +- project-076: builds an EAR with custom env entries settings and JavaEE 5 (Not supported by the specification) +- project-077: builds an EAR with custom env entries settings and JavaEE 6 +- project-078: builds an EAR with the no version for ejb file name mapping +- project-079: builds an EAR with the 'default' library directory mode. Uses the value of the defaultLibBundleDir +- project-080: builds an EAR with the 'empty' library directory mode. Generate an empty library-directory element +- project-081: builds an EAR with the 'none' library directory mode. Does not generate an library-directory element diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm new file mode 100644 index 00000000..88073e3c --- /dev/null +++ b/src/site/markdown/usage.md.vm @@ -0,0 +1,152 @@ + + +# Usage + +To handle archiving this version of Maven EAR Plugin uses [Maven Archiver](http://maven.apache.org/shared/maven-archiver/index.html) ${mavenArchiverVersion}. + +To handle filtering this version of Maven EAR Plugin uses [Maven Filtering](http://maven.apache.org/shared/maven-filtering/index.html) ${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 [the goals description](./plugin-info.html). + +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: + +```xml + + [...] + + [...] + + [...] + + maven-ear-plugin + ${project.version} + + + + + [...] + +``` + +When configuring the EAR Plugin in your `pom.xml`, you do not declare an `` 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 `` is `ear`. So to generate your EAR package, you need only call the `package` phase like this: + +```shell +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 configuration](./modules.html) 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 `` 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 + + ```xml + + dot.com:loader=unique-archive-name + + java2ParentDelegation=true + + + ``` + + ```xml + + + [...] + + dot.com:loader=unique-archive-name + + + java2ParentDelegation=true + + + + ``` + +- **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: + + ```xml + + + [...] + + main-ds.xml + config/secondary-ds.xml + [...] + + + + ``` + +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.