iPlanet documentation for ejbjar and iplanet-ejbc tasks

Submitted by:   Martin Gee <martin.gee@icsynergy.com>
                Greg Nelson <greg@netscape.com>


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

docs/manual/OptionalTasks/ejb.html

@@ -13,10 +13,14 @@
 <!-- Names are in alphabetical order, on last name -->
 <ul>
   <li>Tim Fennell (<a href="mailto:tfenne@rcn.com">tfenne@rcn.com</a>)</li>
+  <li>Martin Gee (<a href="mailto:martin.gee@icsynergy.com">martin.gee@icsynergy.com</a>)</li>
   <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li>
+  <li>Greg Nelson (<a href="mailto:greg@netscape.com">greg@netscape.com</a>)</li>
 </ul>
 
-<p>Version 1.1 - 2000/07/18</p>
+<p>Version @VERSION@<br>
+$Id$
+</p>
 <hr>
 <h2>Table of Contents</h2>
 <ul>
@@ -39,9 +43,11 @@ to support additional EJB Servers.
  <tr><td><a href="BorlandGenerateClient.html">blgenclient</a></td><td colspan="2">Borland Application Server 4.5</td></tr>
  <tr><td><a href="#ddcreator">ddcreator</a></td><td colspan="2">Weblogic 4.5.1</td></tr>
  <tr><td><a href="#ejbc">ejbc</a></td><td colspan="2">Weblogic 4.5.1</td></tr>
- <tr><td rowspan="3"><a href="#ejbjar">ejbjar</a></td><td colspan="2" align="center">Nested Elements</td></tr>
- <tr><td><a href="#ejbjar_weblogic">weblogic</a></td><td>Weblogic 5.1 &amp; 6.0</td></tr>
+ <tr><td><a href="#iplanet-ejbc">iplanet-ejbc</a></td><td>iPlanet Application Server 6.0</td></tr>
+ <tr><td rowspan="4"><a href="#ejbjar">ejbjar</a></td><td colspan="2" align="center">Nested Elements</td></tr>
  <tr><td><a href="BorlandEJBTasks.html">borland</a></td><td>Borland Application Server 4.5</td></tr>
+ <tr><td><a href="#ejbjar_iplanet">iPlanet</a></td><td>iPlanet Application Server 6.0</td></tr>
+ <tr><td><a href="#ejbjar_weblogic">weblogic</a></td><td>Weblogic 5.1 &amp; 6.0</td></tr>
  <tr><td><a href="#wlrun">wlrun</a></td><td colspan="2">Weblogic 4.5.1, 5.1 &amp; 6.0</td></tr>
  <tr><td><a href="#wlstop">wlstop</a></td><td colspan="2">Weblogic 4.5.1, 5.1 &amp; 6.0</td></tr>
 
@@ -152,6 +158,130 @@ or are out of date, the ejbc tool is run to generate new versions.</p>
 &lt;/ejbc&gt;
 </pre>
 
+<hr>
+<h2>
+<a NAME="iplanet-ejbc"></a>iplanet-ejbc</h2>
+
+<h3>
+<b>Description:</b></h3>
+Task to compile EJB stubs and skeletons for the iPlanet Application Server
+6.0.  Given a standard EJB 1.1 XML descriptor as well as an iAS-specific
+EJB descriptor, this task will generate the stubs and skeletons required
+to deploy the EJB to iAS.  Since the XML descriptors can include multiple
+EJBs, this is a convenient way of specifying many EJBs in a single Ant
+task.
+<p>For each EJB specified, the task will locate the three classes that
+comprise the EJB in the destination directory.  If these class files
+cannot be located in the destination directory, the task will fail. The
+task will also attempt to locate the EJB stubs and skeletons in this directory.
+If found, the timestamps on the stubs and skeletons will be checked to
+ensure they are up to date. Only if these files cannot be found or if they
+are out of date will the iAS ejbc utility be called to generate new stubs
+and skeletons.
+<h3>
+Parameters:</h3>
+ 
+<table BORDER CELLSPACING=0 CELLPADDING=2 >
+<tr>
+<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>ejbdescriptor</td>
+
+<td VALIGN=TOP>Standard EJB 1.1 XML descriptor (typically titled "ejb-jar.xml").</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>iasdescriptor</td>
+
+<td VALIGN=TOP>iAS-specific EJB XML descriptor (typically titled "ias-ejb-jar.xml).</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>dest</td>
+
+<td VALIGN=TOP>The is the base directory where the RMI stubs and skeletons
+are written. In addition, the class files for each bean (home interface,
+remote interface, and EJB implementation) must be found in this directory.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>classpath</td>
+
+<td VALIGN=TOP>The classpath used when generating EJB stubs and skeletons.
+If omitted, the classpath specified when Ant was started will be used.
+Nested "classpath" elements may also be used.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>keepgenerated</td>
+
+<td VALIGN=TOP>Indicates whether or not the Java source files which are
+generated by ejbc will be saved or automatically deleted. If "yes", the
+source files will be retained. If omitted, it defaults to "no". </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>debug</td>
+
+<td>Indicates whether or not the ejbc utility should log additional debugging
+statements to the standard output. If "yes", the additional debugging statements
+will be generated.  If omitted, it defaults to "no". </td>
+
+<td ALIGN=CENTER VALIGN=TOP>
+<center>No</center>
+</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>iashome</td>
+
+<td>May be used to specify the "home" directory for this iAS installation.
+This is used to find the ejbc utility if it isn't included in the user's
+system path. If specified, it should refer to the "[install-location]/iplanet/ias6/ias"
+directory. If omitted, the ejbc utility must be on the user's system path. </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+</table>
+
+<h3>
+Examples</h3>
+
+<pre>&lt;iplanet-ejbc ejbdescriptor="ejb-jar.xml"
+              iasdescriptor="ias-ejb-jar.xml"
+              dest="${build.classesdir}" 
+              classpath="${ias.ejbc.cpath}" />
+
+&lt;iplanet-ejbc ejbdescriptor="ejb-jar.xml"
+              iasdescriptor="ias-ejb-jar.xml"
+              dest="${build.classesdir}" 
+              keepgenerated="yes"
+              debug="yes"
+              iashome="${ias.home}" >
+              &lt;classpath>
+                  &lt;pathelement path="." />
+                  &lt;pathelement path="${build.classpath}" />
+              &lt;/classpath>
+&lt;/iplanet-ejbc>
+
+</pre>
+
 <hr>
 <h2><a name="wlrun">wlrun</a></h2>
 <h3><b>Description:</b></h3>
@@ -854,6 +984,161 @@ This will create only one TOPLink-enabled ejb jar file - 'Address.jar'.</p>
     &lt;/ejbjar&gt;
 </pre>
 
+<a name="ejbjar_iplanet"></a>
+<h3>
+iPlanet Application Server (iAS) element</h3>
+The &lt;iplanet> nested element is used to build iAS-specific stubs and
+skeletons and construct a JAR file which may be deployed to the iPlanet
+Application Server 6.0.  The build process will always determine if
+the EJB stubs/skeletons and the EJB-JAR file are up to date, and it will
+do the minimum amount of work required.
+<p>Like the WebLogic element, a naming convention for the EJB descriptors
+is most commonly used to specify the name for the completed JAR file. 
+For example, if the EJB descriptor ejb/Account-ejb-jar.xml is found in
+the descriptor directory, the iplanet element will search for an iAS-specific
+EJB descriptor file named ejb/Account-ias-ejb-jar.xml (if it isn't found,
+the task will fail) and a JAR file named ejb/Account.jar will be written
+in the destination directory.  Note that when the EJB descriptors
+are added to the JAR file, they are automatically renamed META-INF/ejb-jar.xml
+and META-INF/ias-ejb-jar.xml.
+<p>Of course, this naming behavior can be modified by specifying attributes
+in the ejbjar task (for example, basejarname, basenameterminator, and flatdestdir)
+as well as the iplanet element (for example, suffix).  Refer to the
+appropriate documentation for more details.
+<h3>
+Parameters:</h3>
+
+<table BORDER CELLSPACING=0 CELLPADDING=2 >
+<tr>
+<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 JAR files will
+be written. Each JAR file is written in directories which correspond to
+their location within the "descriptordir" namespace.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>classpath</td>
+
+<td VALIGN=TOP>The classpath used when generating EJB stubs and skeletons. 
+If omitted, the classpath specified in the "ejbjar" parent task will be
+used.  If specified, the classpath elements will be prepended to the
+classpath specified in the parent "ejbjar" task. Note that nested "classpath"
+elements may also be used.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>keepgenerated</td>
+
+<td VALIGN=TOP>Indicates whether or not the Java source files which are
+generated by ejbc will be saved or automatically deleted. If "yes", the
+source files will be retained.  If omitted, it defaults to "no". </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>debug</td>
+
+<td>Indicates whether or not the ejbc utility should log additional debugging
+statements to the standard output. If "yes", the additional debugging statements
+will be generated.  If omitted, it defaults to "no". </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>iashome</td>
+
+<td>May be used to specify the "home" directory for this iAS installation.
+This is used to find the ejbc utility if it isn't included in the user's
+system path.  If specified, it should refer to the [install-location]/iplanet/ias6/ias
+directory.  If omitted, the ejbc utility must be on the user's system
+path. </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+
+<tr>
+<td VALIGN=TOP>suffix</td>
+
+<td>String value appended to the JAR filename when creating each JAR. 
+If omitted, it defaults to ".jar". </td>
+
+<td ALIGN=CENTER VALIGN=TOP>No</td>
+</tr>
+</table>
+
+<p>As noted above, the iplanet element supports additional &lt;classpath>
+nested elements.
+<h3>
+Examples</h3>
+This example demonstrates the typical use of the &lt;iplanet> nested element. 
+It will name each EJB-JAR using the "basename" prepended to each standard
+EJB descriptor.  For example, if the descriptor named "Account-ejb-jar.xml"
+is processed, the EJB-JAR will be named "Account.jar"
+<pre>    &lt;ejbjar srcdir="${build.classesdir}"
+            descriptordir="${src}" >
+            &lt;iplanet destdir="${assemble.ejbjar}"
+                     classpath="${ias.ejbc.cpath}" />
+            &lt;include name="**/*-ejb-jar.xml"/>
+            &lt;exclude name="**/*ias-*.xml"/>
+    &lt;/ejbjar></pre>
+This example demonstrates the use of a nested classpath element as well
+as some of the other optional attributes.
+<pre>    &lt;ejbjar srcdir="${build.classesdir}"
+            descriptordir="${src}" >
+            &lt;iplanet destdir="${assemble.ejbjar}"
+                     iashome="${ias.home}"
+                     debug="yes" 
+                     keepgenerated="yes" >
+                     &lt;classpath>
+                         &lt;pathelement path="." />
+                         &lt;pathelement path="${build.classpath}" />
+                     &lt;/classpath>
+            &lt;/iplanet>
+            &lt;include name="**/*-ejb-jar.xml"/>
+            &lt;exclude name="**/*ias-*.xml"/>
+    &lt;/ejbjar></pre>
+This example demonstrates the use of basejarname attribute.  In this
+case, the completed EJB-JAR will be named "HelloWorld.jar"  If multiple
+EJB descriptors might be found, care must be taken to ensure that the completed
+JAR files don't overwrite each other.
+<pre>    &lt;ejbjar srcdir="${build.classesdir}"
+            descriptordir="${src}"
+            basejarname="HelloWorld" >
+            &lt;iplanet destdir="${assemble.ejbjar}"
+                     classpath="${ias.ejbc.cpath}"/>
+            &lt;include name="**/*-ejb-jar.xml"/>
+            &lt;exclude name="**/*ias-*.xml"/>
+    &lt;/ejbjar></pre>
+This example demonstrates the use of the dtd nested element.  If the
+[iAS-install-directory]/APPS directory is included in the classpath, these
+local  DTDs will be automatically referenced even without the nested
+elements.
+<pre>    &lt;ejbjar srcdir="${build.classesdir}"
+            descriptordir="${src}" > 
+            &lt;iplanet destdir="${assemble.ejbjar}"            >
+                     classpath="${ias.ejbc.cpath}" />
+            &lt;include name="**/*-ejb-jar.xml"/>
+            &lt;exclude name="**/*ias-*.xml"/>
+            &lt;dtd publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
+                 location="${ias.home}/APPS/ejb-jar_1_1.dtd"/>
+            &lt;dtd publicId="-//Sun Microsystems, Inc.//DTD iAS Enterprise JavaBeans 1.0//EN"
+                 location="${ias.home}/APPS/IASEjb_jar_1_0.dtd"/>
+    &lt;/ejbjar></pre>
 
 </body>