Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the announcement. Users are encouraged to migrate to the current version of Apache Maven.

Overview

This document describes the supplied goals that are available when using the J2EE Plug-in with Maven.

Please refer to the Integration document for more information on how to integrate these goals into your project.

The build file utilizes various properties for default and user-configurable settings. All J2EE Plug-in properties are described in the Properties document. The rest of this document assumes your project follows the standard Directory Layout; however, it is possible to override many of these defaults.

J2EE Goals

GoalDescription
j2ee:validate-war Validate a WAR file.
j2ee:ejb Creates an EJBjar file.
j2ee:ear Creates an EAR file.
j2ee:appserver-install Installs an Application Server instance
j2ee:appserver-start Starts an Application Server instance
j2ee:appserver-stop Stops an Application Server instance
j2ee:appserver-clean Safely deletes the Application Server instance installation directory specified by the ${maven.appserver.dir} property.

j2ee:validate-war

The j2ee:validate-war target validates the newly produced war file.

The validator checks the folowing:

  1. The war file exists
  2. It is readable
  3. The war file has a web.xml (it's only a warning if it doesn't exist)
  4. Servlets defined by a <servlet> tag are loadable from the war file and not the classpath
  5. JSPs defined by a <servlet> tag exist in the war
  6. Taglibs defined by a <taglib> have a <taglib-location> that exists in the war
  7. Error pages specified by a <location> nested within an <error-page> element must exist in the war file
  8. Login and error pages specified in the <form-login-config > element must exist in the war file

j2ee:ejb

The j2ee:ejb target generates the ejb jar file for the project. Optionally it can also create jars containing the local and remote interfaces. The files are produced in the ${maven.build.dir}/ejb directory and have a name based on the ${maven.j2ee.ejb.name} property.

The files generated are:

  • ${maven.j2ee.ejb.name}.jar
  • ${maven.j2ee.ejb.name}-remote.jar (optional)
  • ${maven.j2ee.ejb.name}-local.jar (optional)

Maven also includes the license file, LICENSE.txt, if it exists, in the META-INF directory.

The contents of the ejb file include:

ItemDescription
ejb-jar.xml A J2EE enterprise bean deployment descriptor, which is placed in the root of the resulting ear file. The ${maven.j2ee.ejb.conf.dir} and associated includes and excludes properties defines the location of this file.
Classes The files in the ${maven.build.dest} directory to be included is specified using the ${maven.j2ee.ejb.includes} and ${maven.j2ee.ejb.excludes} properties.
Meta-Inf Files to be included the META-INF directory of the ejb jar file may be specified using the ${maven.j2ee.ejb.conf.dir}, ${maven.j2ee.ejb.conf.includes} and ${maven.j2ee.ejb.conf.excludes} properties.

j2ee:ear

The j2ee:ear target generates an ear file for the project. The ear file is produced in the ${maven.build.dir} directory and has a name defined by the ${maven.j2ee.ear.name} property.

Maven also includes the license file, LICENSE.txt, if it exists, under the directory META-INF.

The contents of the ear file include:

ItemDescription
application.xml A J2EE enterprise application deployment descriptor, which is placed in the META-INF of the resulting ear file. The ${maven.j2ee.ear.appxml} property defines the location of this file. It defaults to src/application.xml
Other Content Any dependencies specified in your project.xml may be included by adding the ear.bundle.jar property to the properties, e.g.
<dependency>
  <id>CustomerEjb</id>
  <version>2.4</version>
  <properties>
    <ear.bundle.jar>true</ear.bundle.jar>
  </properties>
</dependency>
              

j2ee:appserver-install

The j2ee:appserver-install target installs the minimum directory and file structure necessary for an individual application server instance. Once the structure is created inside the directory specified by ${maven.appserver.dir} , configuration files are installed using the copy task and the filter mechanism built into Ant. The exact work done by this target is specific to the name and version of the application server you specify using ${maven.appserver.name} and ${maven.appserver.version} properties.

Optionally, you can invoke the install target of the Ant build.xml file copied to ${maven.appserver.dir} instead. See the appserver proxy build file for more information.

During the configuration process, all maven.appserver.* properties are used as filter tokens while files in ${maven.conf.dir}/${maven.appserver.name}${maven.appserver.version} are copied to ${maven.appserver.dir}. By default, certain files are excluded from copying to ${maven.appserver.dir}. Files excluded are:

  • **/web.xml/**

This allows you to keep you webapp specific conf files in the same directory and not have them installed with this target needlessly.

Your configuration files may require additional processing ( using additional filter tokens for example). In that case you can use the maven-post-appserver-install callback target to re-configure files.

This target has different behavior depending on the current status of the application server. The behavior is defined by the following rules:

Server StatusBehavior
Not Installed Install and configure the application server.
Installed and stopped Re-install/re-configure the application server.
Installed and started Stop, re-install/re-configure, re-start the application server.

Note: In all situations, the j2ee:appserver-install target will overwrite existing appserver configuration files already installed. Maven does this because it cannot know if the you have changed your maven.appserver.* related properties, so it always re-configures the configuration files. Since this operation has low overhead, it is considered a feature that allows dynamic updates to your appserver related property values.

j2ee:appserver-start

The j2ee:appserver-start target attempts to start the application server instance you have specified via properties.

Optionally, you can invoke the start target of the Ant build.xml file copied to ${maven.appserver.dir} instead. See the appserver proxy build file for more information.

This target will cause two processes to run. One process will represent the running of the Ant build file for the Maven target. The other will be the forked JVM that actually starts the application server instance.

If you don't want the processes to block your current terminal, you can execute the call to this target in the background using the traditional '&' directive on unix-like systems.

For example, to run the server in the background, go to your ${maven.appserver.dir} directory and type:

ant start &

This target has different behavior depending on the current status of the application server. The behavior is defined by the following rules:

Server StatusBehavior
Not Installed Install/configure, then start the application server.
Installed and stopped Start the application server.
Installed and started Stop and then re-start the application server. This is useful for application servers that are not set to auto-reload resources.

j2ee:appserver-stop

The j2ee:appserver-stop target attempts to stop the application server instance you have specified via the maven.appserver.* properties.

Optionally, you can invoke the stop target of the Ant build.xml file copied to ${maven.appserver.dir} instead. See the appserver proxy build file for more information.

This target only has relevance if the application server instance is actually started. All other situations do nothing.

j2ee:appserver-clean

The j2ee:appserver-clean target attempts to safely delete the directory specified by ${maven.appserver.dir}.

This target has different behavior depending on the current status of the application server. The behavior is defined by the following rules:

Server StatusBehavior
Installed and stopped Deletes the directory specified by ${maven.appserver.dir}.
Installed and started Stop the application server instance and then delete the directory specified by ${maven.appserver.dir}.