Change ejbjar so that the deployment descriptors and class files can come from

different directory trees.
Update ejbjar documentation.
Update WhatsNew


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@267940 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -28,10 +28,12 @@ have been removed.
 it changed to and invoke this instead of command if present. This
 behavior has been dropped.
 
+* <ejbjar> task syntax has been changed significantly
+
 Other changes:
 --------------
 
-* New tasks: antstructure, cab, execon, ftp, genkey, junit, sql.
+* New tasks: antstructure, cab, execon, ftp, genkey, junit, sql, javacc, jjtree, starteam.
 
 * New tasks mparse pending documentation.
 
@@ -58,6 +60,10 @@ on log output.
 
 * <replace> can now use tokens and/or values that cross line boundaries.
 
+* <ejbc> optional task no longer uses a separate VM to invoke the ejbc tool.
+
+* project specific help can now be obtained with the -projecthelp option.
+
 Fixed bugs:
 -----------
 

docs/ejb.html

@@ -163,32 +163,38 @@ or are out of date, the ejbc tool is run to generate new versions.
 <h3><b>Description:</b></h3>
 <p>This task is designed to support building of arbitrary EJB1.1 jar files. Support is currently
    provided for 'vanilla' EJB1.1 jar files - i.e. those containing only the user generated class
-    files and the standard deployment descriptor, as well as for WebLogic 5.1 jar files.</p>
- 
+   files and the standard deployment descriptor. Nested elements provide support for vendor
+   specific deployment tools. Currently a nested element is provided for Weblogic 5.1 using the 
+   weblogic.ejbc tool.</p>
+
+<p>This task assumes a particular naming convention for deployment descriptor files. For an 
+   Account bean, for example, the deployment descriptor would be named <code>Account-ejb-jar.xml</code>.
+   This naming convention allows the task to distinguish deployment descriptors without relying on 
+   their positioning within a source tree. It is also used to derive the name of the .jar file 
+   which is generated. For the example this would be <code>Account.jar</code>. Vendor specific files 
+   are assumed to be named in a similar fashion. The deployment descriptor file which defines 
+   additional weblogic specific information for the above bean would be 
+   <code>Account-weblogic-ejb-jar.xml</code>.
+   
 <p>The task works as a directory scanning task, and performs an action for each deployment descriptor
    found. As such the includes and excludes should be set to ensure that all desired EJB1.1
    descriptors are found, but no application server descriptors are found. For each descriptor
-   found, ejbjar will parse the deployment descriptor to determine the necessary class files to
-   include and assemble those files and necessary deployment descriptors into a well formed EJB
-   jar file. If generateweblogic is set to true, weblogic.ejbc is then invoked (in VM) to create
-   the WebLogic jar file.</p>
+   found, ejbjar will parse the deployment descriptor to determine the necessary class files which
+   implement the bean. These files are assembled along with the deployment descriptors into a well 
+   formed EJB jar file. Note that support classes used by the bean but which are not part of the 
+   bean's interfaces are not included in the assembled jar. These need to be collected into a
+   separate support jar file.</p>
 
-<p>In order to locate the WebLogic deployment descriptors for each jar file, certain naming 
-   conventions are assumed. For the purpose of this document we will assume a basenameterminator
-   of '-' (see below for how to specify this option). If you have a deployment descriptor called
-   FooBean-ejb-jar.xml, the basename will be taken as FooBean, the string up to the basenameterminator.
-   Descriptors will then be searched for called FooBean-weblogic-ejb-jar.xml and also
-   FooBean-weblogic-cmp-rdbms-jar.xml. If generateweblogic is false, neither WebLogic descriptor is
-   required, but will still be embedded if found. If generateweblogic is true, only
-   FooBean-weblogic-ejb-jar.xml is required, but again, both will be embedded in the jar file if
-   they are found.</p>
+<p>If no nested vendor-specific deployment elements are present, the task will simply generate a
+   generic EJB jar. Such jars are typically used as the input to vendor-specific deployment tools.
+   For each nested deployment element, a vendor specific deployment tool is run to generate a jar file
+   ready for deployment in that vendor's EJB container. Note that at this time the only supported tool is
+   Weblogic's ejbc tool.
 
-<p>The jar files are only built if they are out of date.  As more than one jar file can be built
-   per deployment descriptor, this process works as follows. If generateweblogic is true use the
-   modification date of the WebLogic jar file as the jar file modification date, otherwise use the
-   modification date of the generic jar file. If the modification timestamp of any of the class
-   files or deployment descriptors is later than the selected jar file's, a build is executed,
-   otherwise a message is logged that the jar file is up to date.</p>
+<p>The jar files are only built if they are out of date.  Each deployment tool element will examine
+   its target jar file and determine if it is out of date with respect to the class files and 
+   deployment descriptors that make up the bean. If any of these files are newer than the jar file
+   the jar will be rebuilt otherwise a message is logged that the jar file is up to date.</p>
 
 <h3>Parameters:</h3>
 <table border="1" cellpadding="2" cellspacing="0">
@@ -198,28 +204,24 @@ or are out of date, the ejbc tool is run to generate new versions.
     <td align="center" valign="top"><b>Required</b></td>
   </tr>
   <tr>
-    <td valign="top">srcdir</td>
+    <td valign="top">descriptordir</td>
     <td valign="top">The base directory under which to scan for EJB deployment descriptors.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
-    <td valign="top">destdir</td>
-    <td valign="top">The base directory under which generated jar files are deposited. Jar files are deposited in
-                     directories correpsonding to the package in which their deployment descriptor was found.</td>
+    <td valign="top">srcdir</td>
+    <td valign="top">The base directory containg the .class files that make up the bean.
+                     Note that this can be the same as the descrptordir if all files are
+                     in the same directory tree.</td>
     <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
-    <td valign="top">generateweblogic</td>
-    <td valign="top">Boolean value specifying whether or not ejbc should be invoked to create the weblogic jar file.
-                     Acceptable values are 'true' and 'false'.</td>
-    <td valign="top" align="center">No, defaults to 'false'.</td>
-  </tr>
-  <tr>
-    <td valign="top">keepgeneric</td>
-    <td valign="top">Boolean value specifying whether or not to keep the generic EJB1.1 jar files created. If you are
-                     only interested in the generated WebLogic jar files, set this to false to remove the temporary
-                     jar files created. Acceptable values are 'true' and 'false'.</td>
-    <td valign="top" align="center">No, defaults to 'true'.</td>
+    <td valign="top">destdir</td>
+    <td valign="top">The base directory into which generated jar files are deposited. Jar files are deposited in
+                     directories correpsonding to their location within the descriptordir namespace. Note that 
+                     this attribute is only used if the task is generating generic jars (i.e. no vendor-specific
+                     deployment elements have been specified).</td>
+    <td valign="top" align="center">Yes</td>
   </tr>
   <tr>
     <td valign="top">basenameterminator</td>
@@ -237,22 +239,62 @@ or are out of date, the ejbc tool is run to generate new versions.
                      generic EJB jar file.</td>
     <td valign="top" align="center">No, defaults to '-generic.jar'.</td>
   </tr>
+</table>
+
+<h3>Vendor-specific deployment elements</h3>
+
+Each vendor-specific nested element controls the generation of a deployable jar specific to that vendor's
+EJB container. The parameters for each supported deployment element are detailed here.
+
+<h3>Weblogic element</h3>
+<table border="1" cellpadding="2" cellspacing="0">
   <tr>
-    <td valign="top">weblogicjarsuffix</td>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+  </tr>
+  <tr>
+    <td valign="top">destdir</td>
+    <td valign="top">The base directory into which the generated weblogic ready jar files are deposited. Jar files are deposited in
+                     directories correpsonding to their location within the descriptordir namespace. </td>
+    <td valign="top" align="center">Yes</td>
+  </tr>
+  <tr>
+    <td valign="top">genericjarsuffix</td>
+    <td valign="top">A generic jar is generated as an intermeditate step in build the weblogic deployment
+                     jar. The suffix used to generate the generic jar file is not particularly important
+                     unless it is desired to keep the generic jar file. It should not, however, be the same
+                     as the suffix setting.</td>
+    <td valign="top" align="center">No, defaults to '-generic.jar'.</td>
+  </tr>
+  <tr>
+    <td valign="top">suffix</td>
     <td valign="top">String value appended to the basename of the deployment descriptor to create the filename of the
                      WebLogic EJB jar file.</td>
-    <td valign="top" align="center">No, defaults to '-wl.jar'.</td>
+    <td valign="top" align="center">No, defaults to '.jar'.</td>
+  </tr>
+  <tr>
+    <td valign="top">classpath</td>
+    <td valign="top">The classpath to be used when running the weblogic ejbc tool. Note that this tool 
+                     typically requires the classes that make up the bean to be available on the classpath. 
+                     Currently, however, this will cause the ejbc tool to be run in a separate VM</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">keepgeneric</td>
+    <td valign="top">This controls whether the generic fiule used as input to ejbc is retained.</td>
+    <td valign="top" align="center">No, defaults to false</td>
   </tr>
 </table>
 
+
 <h3>Examples</h3>
+This example shows ejbjar being used to generate deployment jars for a Weblogic EJB container.
 <pre>
-    &lt;ejbjar srcdir="classes"
-            destdir="classes"
-            generateweblogic="true"
-            keepgeneric="false"
-            genericjarsuffix="-temp.jar"
-            weblogicjarsuffix=".jar"&gt;
+    &lt;ejbjar srcdir="${build.classes}"
+            descriptordir="${descriptor.dir}"&gt;
+      &lt;weblogic destdir="${deploymentjars.dir}"
+                classpath="${descriptorbuild.classpath}"/&gt;
       &lt;include name="**/*-ejb-jar.xml"/&gt;
       &lt;exclude name="**/*weblogic*.xml"/&gt;
     &lt;/ejbjar&gt;

src/main/org/apache/tools/ant/taskdefs/optional/ejb/EJBDeploymentTool.java

@@ -69,7 +69,7 @@ public interface EJBDeploymentTool {
      * @param descriptorFilename the name of the deployment descriptor
      * @param saxParser a SAX parser which can be used to parse the deployment descriptor. 
      */
-    public void processDescriptor(File srcDir, String descriptorFilename, SAXParser saxParser) 
+    public void processDescriptor(File srcDir, File descriptorDir, String descriptorFilename, SAXParser saxParser) 
         throws BuildException;
     
     /**

src/main/org/apache/tools/ant/taskdefs/optional/ejb/EjbJar.java

@@ -102,9 +102,12 @@ import org.apache.tools.ant.taskdefs.MatchingTask;
  */
 public class EjbJar extends MatchingTask {
 
-    /** Stores a handle to the directory under which to search for files */
+    /** Stores a handle to the directory under which to search for class files */
     private File srcdir = null;
 
+    /** Stores a handle to the directory under which to search for deployment descriptors */
+    private File descriptordir = null;
+
     /** Stores a handle to the directory to put the Jar files in */
     private File destdir = null;
 
@@ -140,6 +143,14 @@ public class EjbJar extends MatchingTask {
         this.srcdir = inDir;
     }
 
+    /**
+     * Setter used to store the value of descriptordir prior to execute() being called.
+     * @param inDir the directory containing the deployment descriptors.
+     */
+    public void setDescriptordir(File inDir) {
+        this.descriptordir = inDir;
+    }
+
     /**
      * Setter used to store the value of destination directory prior to execute()
      * being called.
@@ -188,6 +199,9 @@ public class EjbJar extends MatchingTask {
         if (srcdir == null) {
             throw new BuildException("The srcdir attribute must be specified");
         }
+        if (descriptordir == null) {
+            throw new BuildException("The descriptordir attribute must be specified");
+        }
         
         if (deploymentTools.size() == 0) {
             GenericDeploymentTool genericTool = new GenericDeploymentTool();
@@ -210,7 +224,7 @@ public class EjbJar extends MatchingTask {
             saxParserFactory.setValidating(true);
             SAXParser saxParser = saxParserFactory.newSAXParser();
     
-            DirectoryScanner ds = getDirectoryScanner(srcdir);
+            DirectoryScanner ds = getDirectoryScanner(descriptordir);
             ds.scan();
             String[] files = ds.getIncludedFiles();
     
@@ -245,7 +259,7 @@ public class EjbJar extends MatchingTask {
     private void processDescriptor(String descriptorFilename, SAXParser saxParser,
                                    EJBDeploymentTool tool) {
 
-        tool.processDescriptor(srcdir, descriptorFilename, saxParser);
+        tool.processDescriptor(srcdir, descriptordir, descriptorFilename, saxParser);
     }
 }
 

src/main/org/apache/tools/ant/taskdefs/optional/ejb/GenericDeploymentTool.java

@@ -191,7 +191,8 @@ public class GenericDeploymentTool implements EJBDeploymentTool {
         return new DescriptorHandler(srcDir);
     }
     
-    public void processDescriptor(File srcDir, String descriptorFilename, SAXParser saxParser) {
+    public void processDescriptor(File srcDir, File descriptorDir,
+                                  String descriptorFilename, SAXParser saxParser) {
         try {
             DescriptorHandler handler = getDescriptorHandler(srcDir);
             
@@ -201,7 +202,7 @@ public class GenericDeploymentTool implements EJBDeploymentTool {
              */
             saxParser.parse(new InputSource
                             (new FileInputStream
-                             (new File(srcDir, descriptorFilename))),
+                             (new File(descriptorDir, descriptorFilename))),
                             handler);
                             
             Hashtable ejbFiles = handler.getFiles();
@@ -225,9 +226,9 @@ public class GenericDeploymentTool implements EJBDeploymentTool {
 
             // First the regular deployment descriptor
             ejbFiles.put(META_DIR + EJB_DD,
-                         new File(srcDir, descriptorFilename));
+                         new File(descriptorDir, descriptorFilename));
                          
-            addVendorFiles(ejbFiles, srcDir, baseName);
+            addVendorFiles(ejbFiles, srcDir, descriptorDir, baseName);
 
             // Lastly create File object for the Jar files. If we are using
             // a flat destination dir, then we need to redefine baseName!
@@ -290,7 +291,7 @@ public class GenericDeploymentTool implements EJBDeploymentTool {
             String msg = "IOException while parsing'"
                 + descriptorFilename.toString()
                 + "'.  This probably indicates that the descriptor"
-                + " doesn't exist. Details:"
+                + " doesn't exist. Details: "
                 + ioe.getMessage();
             throw new BuildException(msg, ioe);
         }
@@ -300,7 +301,7 @@ public class GenericDeploymentTool implements EJBDeploymentTool {
      * Add any vendor specific files which should be included in the 
      * EJB Jar.
      */
-    protected void addVendorFiles(Hashtable ejbFiles, File srcDir, String baseName) {
+    protected void addVendorFiles(Hashtable ejbFiles, File srcDir, File descriptorDir, String baseName) {
     }
 
 

src/main/org/apache/tools/ant/taskdefs/optional/ejb/WeblogicDeploymentTool.java

@@ -61,6 +61,7 @@ import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.Project;
 import org.apache.tools.ant.Task;
 import org.apache.tools.ant.types.Path;
+import org.apache.tools.ant.types.Commandline;
 import org.apache.tools.ant.taskdefs.Java;
 
 public class WeblogicDeploymentTool extends GenericDeploymentTool {
@@ -68,12 +69,12 @@ public class WeblogicDeploymentTool extends GenericDeploymentTool {
     protected static final String WL_CMP_DD = "weblogic-cmp-rdbms-jar.xml";
 
     /** Instance variable that stores the suffix for the weblogic jarfile. */
-    private String jarSuffix = "-wl.jar";
+    private String jarSuffix = ".jar";
 
     private Path classpath;
 
     /** Instance variable that determines whether generic ejb jars are kept. */
-    private boolean keepgeneric = true;
+    private boolean keepgeneric = false;
     
     /**
      * Set the classpath to be used for this compilation.
@@ -109,9 +110,9 @@ public class WeblogicDeploymentTool extends GenericDeploymentTool {
      * Add any vendor specific files which should be included in the 
      * EJB Jar.
      */
-    protected void addVendorFiles(Hashtable ejbFiles, File srcdir, String baseName) {
+    protected void addVendorFiles(Hashtable ejbFiles, File srcdir, File descriptorDir, String baseName) {
         // Then the weblogic deployment descriptor
-        File weblogicDD = new File(srcdir,
+        File weblogicDD = new File(descriptorDir,
                               baseName + getBasenameTerminator() + WL_DD);
 
         if (weblogicDD.exists()) {
@@ -120,7 +121,7 @@ public class WeblogicDeploymentTool extends GenericDeploymentTool {
         }
 
         // The the weblogic cmp deployment descriptor
-        File weblogicCMPDD = new File(srcdir,
+        File weblogicCMPDD = new File(descriptorDir,
                               baseName + getBasenameTerminator() + WL_CMP_DD);
 
         if (weblogicCMPDD.exists()) {
@@ -153,7 +154,8 @@ public class WeblogicDeploymentTool extends GenericDeploymentTool {
             
             javaTask = (Java) getTask().getProject().createTask("java");
             javaTask.setClassname("weblogic.ejbc");
-            javaTask.setArgs(args);
+            Commandline.Argument arguments = javaTask.createArg();
+            arguments.setLine(args);
             if (classpath != null) {
                 javaTask.setClasspath(classpath);
                 javaTask.setFork(true);