<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 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.
 */
 -->

<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>&lt;servlet&gt;</code> tag are loadable
              from the war file and <strong>not</strong> the classpath</li>
            <li>JSPs defined by a <code>&lt;servlet&gt;</code> tag exist in the war
            </li>
            <li>Taglibs defined by a <code>&lt;taglib&gt;</code> have a <code>
              &lt;taglib-location&gt;</code> that exists in the war</li>
            <li>Error pages specified by a <code>&lt;location&gt;</code> nested
              within an <code>&lt;error-page&gt;</code> element must exist in the
              war file</li>
            <li>Login and error pages specified in the <code>&lt;form-login-config
              &gt;</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://ant.apache.org/">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 '&amp;' 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>
