<?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>
      </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>
    </section>
  </body>
</document>
