825d9429af
PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@112861 13f79535-47bb-0310-9956-ffa450edef68
385 lines
16 KiB
XML
385 lines
16 KiB
XML
<?xml version="1.0"?>
|
|
<document>
|
|
|
|
<properties>
|
|
<author email="dion@multitask.com.au">dIon Gillard</author>
|
|
<author email="kevin@rocketred.com.au">Kevin O'Neill</author>
|
|
<author email="plynch@apache.org">Peter Lynch</author>
|
|
<title>Maven J2EE Plug-in Goals</title>
|
|
</properties>
|
|
|
|
<body>
|
|
<section name="Overview">
|
|
<p>
|
|
This document describes the supplied
|
|
<a href="http://jakarta.apache.org/commons/jelly/tags.html#jelly:werkz">goals</a>
|
|
that are available when using the J2EE Plug-in with Maven.
|
|
</p>
|
|
<p>
|
|
Please refer to the
|
|
<a href="../../start/integrate.html">Integration</a> document for
|
|
more information on how to integrate these goals into
|
|
your project.
|
|
</p>
|
|
<p>
|
|
The build file utilizes various properties for default and
|
|
user-configurable settings. All J2EE Plug-in properties are described
|
|
in the <a href="./properties.html">Properties</a> document.
|
|
|
|
The rest of this document assumes your project follows the standard
|
|
<a href="dirlayout.html">Directory Layout</a>; however, it is
|
|
possible to override many of these defaults.
|
|
</p>
|
|
</section>
|
|
<section name="J2EE Goals">
|
|
<table>
|
|
<tr><th>Goal</th><th>Description</th></tr>
|
|
<tr>
|
|
<td><a href="#j2ee:validate-war">j2ee:validate-war</a></td>
|
|
<td>Validate a <code>WAR</code> file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:ejb">j2ee:ejb</a></td>
|
|
<td>Creates an <code>EJB</code>jar file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:ear">j2ee:ear</a></td>
|
|
<td>Creates an <code>EAR</code> file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:appserver-install">j2ee:appserver-install</a></td>
|
|
<td>Installs an Application Server instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:appserver-start">j2ee:appserver-start</a></td>
|
|
<td>Starts an Application Server instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:appserver-stop">j2ee:appserver-stop</a></td>
|
|
<td>Stops an Application Server instance</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#j2ee:appserver-clean">j2ee:appserver-clean</a></td>
|
|
<td>Safely deletes the Application Server instance installation directory
|
|
specified by the <code><a href="./properties.html">${maven.appserver.dir}</a></code>
|
|
property.</td>
|
|
</tr>
|
|
</table>
|
|
<p/>
|
|
<subsection name="j2ee:validate-war">
|
|
<p>
|
|
The <code>j2ee:validate-war</code> target validates the newly
|
|
produced war file.
|
|
</p>
|
|
<p>
|
|
The validator checks the folowing:
|
|
<ol>
|
|
<li>The war file exists</li>
|
|
<li>It is readable</li>
|
|
<li>The war file has a web.xml (it's only a warning if it
|
|
doesn't exist)</li>
|
|
<li>Servlets defined by a <code><servlet></code> tag are loadable
|
|
from the war file and <strong>not</strong> the classpath</li>
|
|
<li>JSPs defined by a <code><servlet></code> tag exist in the war
|
|
</li>
|
|
<li>Taglibs defined by a <code><taglib></code> have a <code>
|
|
<taglib-location></code> that exists in the war</li>
|
|
<li>Error pages specified by a <code><location></code> nested
|
|
within an <code><error-page></code> element must exist in the
|
|
war file</li>
|
|
<li>Login and error pages specified in the <code><form-login-config
|
|
></code> element must exist in the war file</li>
|
|
</ol>
|
|
</p>
|
|
</subsection>
|
|
<subsection name="j2ee:ejb">
|
|
<p>
|
|
The <code>j2ee:ejb</code> target generates the <code>ejb</code> jar file
|
|
for the project. Optionally it can also create jars containing the local
|
|
and remote interfaces. The files are produced in the
|
|
<code><a href="../properties.html#Directory Layout Settings">${maven.build.dir}</a>/ejb</code>
|
|
directory and have a name based on the
|
|
<code><a href="properties.html#maven.j2ee.ejb.name">${maven.j2ee.ejb.name}</a></code>
|
|
property.
|
|
</p>
|
|
<p>The files generated are:
|
|
<ul>
|
|
<li><code>${maven.j2ee.ejb.name}.jar</code></li>
|
|
<li><code>${maven.j2ee.ejb.name}-remote.jar</code> <emp>(optional)</emp></li>
|
|
<li><code>${maven.j2ee.ejb.name}-local.jar</code> <emp>(optional)</emp></li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
Maven also includes the license file, LICENSE.txt, if it exists, in
|
|
the META-INF directory.
|
|
</p>
|
|
<p>
|
|
The contents of the ejb file include:
|
|
</p>
|
|
<table>
|
|
<tr><th>Item</th><th>Description</th></tr>
|
|
<tr>
|
|
<td>ejb-jar.xml</td>
|
|
<td>
|
|
A J2EE enterprise bean deployment descriptor, which
|
|
is placed in the root of the resulting ear file.
|
|
The <code><a href="properties.html#maven.j2ee.ejb.conf.dir">
|
|
${maven.j2ee.ejb.conf.dir}</a></code> and associated includes and
|
|
excludes properties defines the location of this file.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Classes</td>
|
|
<td>
|
|
The files in the <code><a href="../properties.html#Directory Layout Settings">${maven.build.dest}</a></code>
|
|
directory to be included is specified using the
|
|
<code><a href="properties.html#maven.j2ee.ejb.includes">${maven.j2ee.ejb.includes}</a></code>
|
|
and <code><a href="properties.html#maven.j2ee.ejb.excludes">${maven.j2ee.ejb.excludes}</a></code>
|
|
properties.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Meta-Inf</td>
|
|
<td>
|
|
Files to be included the <code>META-INF</code> directory of the ejb
|
|
jar file may be specified using the
|
|
<code><a href="properties.html#maven.j2ee.ejb.conf.dir">
|
|
${maven.j2ee.ejb.conf.dir}</a></code>,
|
|
<code><a href="properties.html#maven.j2ee.ejb.conf.includes">
|
|
${maven.j2ee.ejb.conf.includes}</a></code> and
|
|
<code><a href="properties.html#maven.j2ee.ejb.conf.excludes">
|
|
${maven.j2ee.ejb.conf.excludes}</a></code> properties.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
<subsection name="j2ee:ear">
|
|
<p>
|
|
The <code>j2ee:ear</code> target generates an ear file for the
|
|
project. The ear file is produced in the
|
|
<code><a href="../properties.html#Directory Layout Settings">${maven.build.dir}</a></code>
|
|
directory and has a name defined by the
|
|
<code><a href="properties.html#maven.j2ee.ear.name">${maven.j2ee.ear.name}</a></code>
|
|
property.
|
|
</p>
|
|
<p>
|
|
Maven also includes the license file, LICENSE.txt, if it exists, under
|
|
the directory META-INF.
|
|
</p>
|
|
<p>
|
|
The contents of the ear file include:
|
|
</p>
|
|
<table>
|
|
<tr><th>Item</th><th>Description</th></tr>
|
|
<tr>
|
|
<td>application.xml</td>
|
|
<td>
|
|
A J2EE enterprise application deployment descriptor, which
|
|
is placed in the META-INF of the resulting ear file.
|
|
The <code><a href="properties.html#maven.j2ee.ear.appxml">${maven.j2ee.ear.appxml}</a></code>
|
|
property defines the location of this file. It defaults to
|
|
<code>src/application.xml</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Other Content</td>
|
|
<td>
|
|
Any dependencies specified in your <code>project.xml</code>
|
|
may be included by adding the ear.bundle.jar property to the
|
|
properties, e.g.
|
|
<source><![CDATA[
|
|
<dependency>
|
|
<id>CustomerEjb</id>
|
|
<version>2.4</version>
|
|
<properties>
|
|
<ear.bundle.jar>true</ear.bundle.jar>
|
|
</properties>
|
|
</dependency>
|
|
]]></source>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<!-- j2ee:appserver-* targets ======================================= -->
|
|
|
|
<subsection name="j2ee:appserver-install">
|
|
<p>
|
|
The <code>j2ee:appserver-install</code> 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 <a href="properties.html#maven.appserver.dir">${maven.appserver.dir}</a>
|
|
, configuration files are installed using the copy task and the filter
|
|
mechanism built into <a href="http://jakarta.apache.org/ant">Ant</a>.
|
|
The exact work done by this target is specific to the
|
|
name and version of the application server you specify using
|
|
<a href="properties.html#maven.appserver.name">${maven.appserver.name}</a>
|
|
and <a href="properties.html#maven.appserver.version">${maven.appserver.version}</a>
|
|
properties.
|
|
</p>
|
|
<p>
|
|
Optionally, you can invoke the <code>install</code> target of the
|
|
Ant build.xml file copied to ${maven.appserver.dir} instead. See the
|
|
<a href="appserver.html#Appserver Proxy Build File">appserver proxy build file</a> for more
|
|
information.
|
|
</p>
|
|
<p>
|
|
During the configuration process, all
|
|
<a href="./properties.html#Application Server">maven.appserver.* properties</a>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>**/web.xml/**</li>
|
|
</ul>
|
|
<p>
|
|
This allows you to keep you webapp specific conf files in the same
|
|
directory and not have them installed with this target needlessly.
|
|
</p>
|
|
<p>
|
|
Your configuration files may require additional processing ( using additional
|
|
filter tokens for example). In that case you can use the
|
|
<a href="properties.html#maven.appserver.post-appserver-install.buildFile">maven-post-appserver-install</a>
|
|
callback target to re-configure files.
|
|
</p>
|
|
<p>
|
|
This target has different behavior
|
|
depending on the current status of the application server. The
|
|
behavior is defined by the following rules:
|
|
</p>
|
|
<table>
|
|
<tr><th>Server Status</th><th>Behavior</th></tr>
|
|
<tr>
|
|
<td>Not Installed</td>
|
|
<td>
|
|
Install and configure the application server.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installed and stopped</td>
|
|
<td>
|
|
Re-install/re-configure the application server.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installed and started</td>
|
|
<td>
|
|
Stop, re-install/re-configure, re-start the application server.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><strong>Note:</strong> In all situations, the <code>j2ee:appserver-install</code>
|
|
target will overwrite existing appserver configuration files already
|
|
installed. Maven does this because it cannot know if the you have changed
|
|
your <a href="properties.html#Application Server">maven.appserver.* related properties</a>,
|
|
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.</p>
|
|
</subsection>
|
|
|
|
<subsection name="j2ee:appserver-start">
|
|
<p>
|
|
The <code>j2ee:appserver-start</code> target
|
|
attempts to start the application server instance you have specified
|
|
via properties.
|
|
</p>
|
|
<p>Optionally, you can invoke the <code>start</code> target of the
|
|
Ant build.xml file copied to ${maven.appserver.dir} instead. See the
|
|
<a href="appserver.html#Appserver Proxy Build File">appserver proxy build file</a> for more
|
|
information.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p> For example, to run the server in the background, go to your
|
|
${maven.appserver.dir} directory and type:</p>
|
|
<source><![CDATA[ant start &]]></source>
|
|
<p>
|
|
This target has different behavior
|
|
depending on the current status of the application server. The
|
|
behavior is defined by the following rules:
|
|
</p>
|
|
<table>
|
|
<tr><th>Server Status</th><th>Behavior</th></tr>
|
|
<tr>
|
|
<td>Not Installed</td>
|
|
<td>
|
|
Install/configure, then start the application server.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installed and stopped</td>
|
|
<td>
|
|
Start the application server.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installed and started</td>
|
|
<td>
|
|
Stop and then re-start the application server. This is useful for
|
|
application servers that are not set to auto-reload resources.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
|
|
<subsection name="j2ee:appserver-stop">
|
|
<p>
|
|
The <code>j2ee:appserver-stop</code> target
|
|
attempts to stop the application server instance you have specified
|
|
via the <a href="properties.html">maven.appserver.* properties</a>.
|
|
</p>
|
|
<p>Optionally, you can invoke the <code>stop</code> target of the
|
|
Ant build.xml file copied to ${maven.appserver.dir} instead. See the
|
|
<a href="appserver.html#Appserver Proxy Build File">appserver proxy build file</a> for more
|
|
information.
|
|
</p>
|
|
<p>
|
|
This target only has relevance if the application server instance
|
|
is actually started. All other situations do nothing.
|
|
</p>
|
|
</subsection>
|
|
|
|
|
|
<subsection name="j2ee:appserver-clean">
|
|
<p>
|
|
The <code>j2ee:appserver-clean</code> target
|
|
attempts to safely delete the directory specified by
|
|
${maven.appserver.dir}.
|
|
</p>
|
|
<p>
|
|
This target has different behavior
|
|
depending on the current status of the application server. The
|
|
behavior is defined by the following rules:
|
|
</p>
|
|
<table>
|
|
<tr><th>Server Status</th><th>Behavior</th></tr>
|
|
<tr>
|
|
<td>Installed and stopped</td>
|
|
<td>
|
|
Deletes the directory specified by ${maven.appserver.dir}.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installed and started</td>
|
|
<td>
|
|
Stop the application server instance and then delete the directory
|
|
specified by ${maven.appserver.dir}.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
</section>
|
|
</body>
|
|
</document>
|