Maven ear Plugin: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(26 intermediate revisions by the same user not shown)
Line 6: Line 6:


* [[Maven#Plugins|Maven]]
* [[Maven#Plugins|Maven]]
=TODO=
<font color=red>Deplete https://home.feodorov.com:9443/wiki/Wiki.jsp?page=MavenTemplateEnterprise</font>


=Overview=
=Overview=
Line 11: Line 15:
Each Maven module creates just one artifact, and as EARs are aggregations of multiple artifacts, a project that produces an EAR has at least two modules: the module that produces the EAR and the module that produces the actual content (WAR, JAR, etc.).
Each Maven module creates just one artifact, and as EARs are aggregations of multiple artifacts, a project that produces an EAR has at least two modules: the module that produces the EAR and the module that produces the actual content (WAR, JAR, etc.).


=Playground Example=
=Examples=
 
* The following example shows how to build an EAR that contains a library JAR and a WAR. [https://github.com/NovaOrdis/playground/tree/master/jee/ear/war-and-lib It is a three-module Maven project]. The interesting pom.xml that builds the EAR is found here: https://github.com/NovaOrdis/playground/blob/master/jee/ear/war-and-lib/ear/pom.xml
* An example that builds an EAR with an EJB and a WAR: https://github.com/NovaOrdis/playground/blob/master/jee/ejb/stateless-within-ear/ear/pom.xml
 
=WAR Dependencies=


The following example shows how to build an EAR that contains a library JAR and a WAR. [https://github.com/NovaOrdis/playground/tree/master/jee/ear/war-and-lib It is a three-module Maven project].
A WAR dependency must be explicitly declared of type "war" in the <tt><dependencies></tt> section, otherwise the dependency management will attempt to find a JAR and fail. The corresponding JEE module declaration is <webModule>.


The interesting pom.xml that builds the EAR is found here:
=EJB Dependencies=


<blockquote style="background-color: AliceBlue; border: solid thin LightSteelBlue;">
An EJB dependency must be explicitly declared of type "ejb" in the <tt><dependencies></tt> section, otherwise the dependency management will attempt to find a JAR and fail. The corresponding JEE module declaration is <ejbModule>.
:<br>https://github.com/NovaOrdis/playground/blob/master/jee/ear/war-and-lib/ear/pom.xml<br><br>
</blockquote>


==Notes==
=JEE Deployment Descriptor Generation=


* The WAR dependency must be explicitly declared of type "war", otherwise the dependency management will attempt to find a JAR and fail.
The EAR plugin automatically generates an <tt>application.xml</tt>:
* The EAR plugin automatically generates an <tt>application.xml</tt>:


<pre>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC
<!DOCTYPE application PUBLIC
        "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
"-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
        "http://java.sun.com/dtd/application_1_3.dtd">
"http://java.sun.com/dtd/application_1_3.dtd">
<application>
<application>
   <display-name>ear-example</display-name>
   <display-name>ear-example</display-name>
Line 36: Line 42:
     <web>
     <web>
       <web-uri>ear-embedded-web-application-1.war</web-uri>
       <web-uri>ear-embedded-web-application-1.war</web-uri>
       <context-root>/test</context-root>
       <context-root>/example</context-root>
     </web>
     </web>
   </module>
   </module>
  ...
</application>
</application>
</pre>
</pre>


* If <tt><jboss></tt> is specified in the plugin's configuration, Maven will also generate a JBoss-specific deployment descriptor.
If <tt><jboss></tt> is specified in the plugin's configuration, Maven will also generate a JBoss-specific deployment descriptor. Versions seem to be supported by default up to 5.


<font color=red>
If we want to use a custom <tt>application.xml</tt> that is specified in the source tree, the plugin must be explicitly configured to include it, as shown below. If not configured as such, the plugin will generate <tt>application.xml</tt> even if a file <tt>src/main/resources/META-INF/application.xml</tt> exists.


<pre>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ear-plugin</artifactId>
    <version>2.10.1</version>
    <configuration>
        <applicationXml>${basedir}/src/main/resources/META-INF/application.xml</applicationXml>
        ...
    </configuration>
</plugin>
</pre>


=Including Libraries within an EAR=


!!!Working EAR Module POM example
Java libraries can be included within an EAR as ''java modules'' or as JARs within the EAR's <tt>/lib</tt> directory.


{{{
==Java Modules==
<project>
    <modelVersion>4.0.0</modelVersion>


    <name>TimeSnap Enterprise Archive Module</name>
Specify <tt><includeInApplicationXml>true</includeInApplicationXml></tt>. This will make Maven to generate <tt><java></tt> <tt><module></tt> configuration in <tt>application.xml</tt>:


    <parent>
<pre>
        <groupId>org.novaordis.timesnap</groupId>
<application>
        <artifactId>root</artifactId>
  ...
        <version>r27</version>
  <module>
    </parent>
    <java>ear-embedded-lib-1.jar</java>
  </module>
  ...
</application>
</pre>


    <groupId>org.novaordis.timesnap</groupId>
Note that this type of deployment is subject to JEE EAR module visibility rules. For a discussion on this subject, for WildFly, see [[WildFly Modules#EAR_Deployments|EAR Deployments and WildFly]].
    <artifactId>timesnap</artifactId>
    <packaging>ear</packaging>


    <build>
This is how the pom.xml should be configured:
        <plugins>
            <plugin>
                <artifactId>maven-ear-plugin</artifactId>
                <configuration>
                    <jboss>
                        <version>4</version>
                    </jboss>
                    <modules>
                        <sarModule>
                            <groupId>org.novaordis.timesnap</groupId>
                            <artifactId>timesnap-service</artifactId>
                        </sarModule>
                        <webModule>
                            <groupId>org.novaordis.timesnap</groupId>
                            <artifactId>timesnap-webapp</artifactId>
                            <context-root>/timesnap</context-root>
                        </webModule>


                        <!--
<pre>
                            For some reason Maven include junit, log4j (and probably other
<plugin>
                            dependencies) if I don't explicitely exclude them:
  <artifactId>maven-ear-plugin</artifactId>
                        -->
    <configuration>
                        <jarModule>
      <modules>
                            <groupId>junit</groupId>
        <jarModule>
                            <artifactId>junit</artifactId>
          <groupId>io.novaordis.playground.jee.ear.war-and-lib</groupId>
                            <excluded>true</excluded>
          <artifactId>ear-embedded-lib</artifactId>
                        </jarModule>
          <!--
                        <jarModule>
                If the following flag is not specified, the JAR will be embedded in the EAR's root
                            <groupId>log4j</groupId>
                but no corresponding <java> <module> will be added to application.xml module list.
                            <artifactId>log4j</artifactId>
          -->
                            <excluded>true</excluded>
          <includeInApplicationXml>true</includeInApplicationXml>
                        </jarModule>
        </jarModule>
                    </modules>
        ...
                </configuration>
      </modules>
            </plugin>
  </configuration>
        </plugins>
</plugin>
    </build>
</pre>


    <dependencies>
==JAR Files in the /lib Directory==


        <dependency>
The EAR plugin can be configured to place <tt><jarModule></tt> artifacts in a specific EAR directory - usually <tt>/lib</tt> and not declare them as Java module in <tt>application.xml</tt>:
            <groupId>org.novaordis.timesnap</groupId>
            <artifactId>timesnap-service</artifactId>
            <version>${project.version}</version>
            <type>sar</type>
        </dependency>


         <dependency>
<pre>
            <groupId>org.novaordis.timesnap</groupId>
<plugin>
            <artifactId>timesnap-webapp</artifactId>
  <artifactId>maven-ear-plugin</artifactId>
            <version>${project.version}</version>
    <configuration>
            <type>war</type>
      <!--
        </dependency>
            We have a choice of installing third-party libraries as JEE JAR modules,
            or as simple (non-module) libraries, in /lib.
      -->
      <defaultJavaBundleDir>lib/</defaultJavaBundleDir>
      <modules>
         <jarModule>
          <groupId>io.novaordis.playground</groupId>
          <artifactId>someLib</artifactId>
        </jarModule>
      </modules>
    </configuration>
</plugin>
</pre>


    </dependencies>
=Custom EE Module Filename=


</project>
By default, Maven uses the implicit deployment artifact name, which includes the version information for all JEE modes (EJB, WARs, etc.) The name can be customized using <bundleFileName> as follows:


}}}
<pre>
 
<plugin>
!!!Including a Third-Party Application Module
    <groupId>org.apache.maven.plugins</groupId>
 
    <artifactId>maven-ear-plugin</artifactId>
{{{
    <version>2.10.1</version>
<build>
    <configuration>
    <plugins>
        ...  
      <plugin>
        <modules>
        <groupId>org.apache.maven.plugins</groupId>
            <ejbModule>
        <artifactId>maven-ear-plugin</artifactId>
                <groupId>artifactGroupId</groupId>
        <configuration>
                <artifactId>artifactId</artifactId>
          [...]
                <bundleFileName>some-another-name.jar</bundleFileName>
          <modules>
             </ejbModule>
            <jarModule>
            ...
              <groupId>artifactGroupId</groupId>
        </modules>
              <artifactId>artifactId</artifactId>
    </configuration>
              <includeInApplicationXml>true</includeInApplicationXml>
</plugin>
             </jarModule>
</pre>
          </modules>
        </configuration>
      </plugin>
    </plugins>
  </build>
}}}
 
 
 
</font>

Latest revision as of 17:24, 7 April 2017

External

Internal

TODO

Deplete https://home.feodorov.com:9443/wiki/Wiki.jsp?page=MavenTemplateEnterprise

Overview

Each Maven module creates just one artifact, and as EARs are aggregations of multiple artifacts, a project that produces an EAR has at least two modules: the module that produces the EAR and the module that produces the actual content (WAR, JAR, etc.).

Examples

WAR Dependencies

A WAR dependency must be explicitly declared of type "war" in the <dependencies> section, otherwise the dependency management will attempt to find a JAR and fail. The corresponding JEE module declaration is <webModule>.

EJB Dependencies

An EJB dependency must be explicitly declared of type "ejb" in the <dependencies> section, otherwise the dependency management will attempt to find a JAR and fail. The corresponding JEE module declaration is <ejbModule>.

JEE Deployment Descriptor Generation

The EAR plugin automatically generates an application.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC
	"-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
	"http://java.sun.com/dtd/application_1_3.dtd">
<application>
  <display-name>ear-example</display-name>
  <module>
    <web>
      <web-uri>ear-embedded-web-application-1.war</web-uri>
      <context-root>/example</context-root>
    </web>
  </module>
  ...
</application>

If <jboss> is specified in the plugin's configuration, Maven will also generate a JBoss-specific deployment descriptor. Versions seem to be supported by default up to 5.

If we want to use a custom application.xml that is specified in the source tree, the plugin must be explicitly configured to include it, as shown below. If not configured as such, the plugin will generate application.xml even if a file src/main/resources/META-INF/application.xml exists.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ear-plugin</artifactId>
    <version>2.10.1</version>
    <configuration>
        <applicationXml>${basedir}/src/main/resources/META-INF/application.xml</applicationXml>
        ...
    </configuration>
</plugin>

Including Libraries within an EAR

Java libraries can be included within an EAR as java modules or as JARs within the EAR's /lib directory.

Java Modules

Specify <includeInApplicationXml>true</includeInApplicationXml>. This will make Maven to generate <java> <module> configuration in application.xml:

<application>
  ...
  <module>
    <java>ear-embedded-lib-1.jar</java>
  </module>
  ...
</application>

Note that this type of deployment is subject to JEE EAR module visibility rules. For a discussion on this subject, for WildFly, see EAR Deployments and WildFly.

This is how the pom.xml should be configured:

<plugin>
  <artifactId>maven-ear-plugin</artifactId>
    <configuration>
      <modules>
        <jarModule>
          <groupId>io.novaordis.playground.jee.ear.war-and-lib</groupId>
          <artifactId>ear-embedded-lib</artifactId>
          <!--
                 If the following flag is not specified, the JAR will be embedded in the EAR's root
                 but no corresponding <java> <module> will be added to application.xml module list.
           -->
          <includeInApplicationXml>true</includeInApplicationXml>
        </jarModule>
        ...
      </modules>
   </configuration>
</plugin>

JAR Files in the /lib Directory

The EAR plugin can be configured to place <jarModule> artifacts in a specific EAR directory - usually /lib and not declare them as Java module in application.xml:

<plugin>
  <artifactId>maven-ear-plugin</artifactId>
    <configuration>
      <!--
             We have a choice of installing third-party libraries as JEE JAR modules,
             or as simple (non-module) libraries, in /lib.
      -->
      <defaultJavaBundleDir>lib/</defaultJavaBundleDir>
      <modules>
        <jarModule>
          <groupId>io.novaordis.playground</groupId>
          <artifactId>someLib</artifactId>
        </jarModule>
      </modules>
    </configuration>
</plugin>

Custom EE Module Filename

By default, Maven uses the implicit deployment artifact name, which includes the version information for all JEE modes (EJB, WARs, etc.) The name can be customized using <bundleFileName> as follows:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ear-plugin</artifactId>
    <version>2.10.1</version>
    <configuration>
        ... 
        <modules>
            <ejbModule>
                <groupId>artifactGroupId</groupId>
                 <artifactId>artifactId</artifactId>
                 <bundleFileName>some-another-name.jar</bundleFileName>
             </ejbModule>
             ...
        </modules>
    </configuration>
</plugin>