| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant EJB Tasks</title> |
| |
| </head> |
| |
| <body> |
| |
| <h1>Ant EJB Tasks User Manual</h1> |
| <p>by</p> |
| <!-- Names are in alphabetical order, on last name --> |
| <ul> |
| <li>Tim Fennell (<a href="mailto:tfenne@rcn.com">tfenne@rcn.com</a>)</li> |
| <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li> |
| </ul> |
| |
| <p>Version 1.1 - 2000/07/18</p> |
| <hr> |
| <h2>Table of Contents</h2> |
| <ul> |
| <li><a href="#introduction">Introduction</a></li> |
| <li><a href="#ejbtasks">EJB Tasks</a></li> |
| </ul> |
| |
| <hr> |
| <h2><a name="introduction">Introduction</a></h2> |
| <p>Ant provides a number of optional tasks for developing |
| <a href="http://java.sun.com/products/ejb">Enterprise Java Beans (EJBs)</a>. |
| In general these tasks are specific to the particular vendor's EJB Server. At present the tasks support |
| <a href="http://www.bea.com">Weblogic</a> 4.5.1 and 5.1 EJB servers. Over time we expect further optional tasks |
| to support additional EJB Servers. |
| |
| <hr> |
| <h2><a name="ejbtasks">EJB Tasks</a></h2> |
| <table border="1" cellpadding="5"> |
| <tr><td>Task</td><td>Application Servers</td></tr> |
| <tr><td><a href="#ddcreator">ddcreator</a></td><td>Weblogic 4.5.1</td></tr> |
| <tr><td><a href="#ejbc">ejbc</a></td><td>Weblogic 4.5.1</td></tr> |
| <tr><td><a href="#wlrun">wlrun</a></td><td>Weblogic 4.5.1 and 5.1</td></tr> |
| <tr><td><a href="#wlstop">wlstop</a></td><td>Weblogic 4.5.1 and 5.1</td></tr> |
| <tr><td><a href="#ejbjar">ejbjar</a></td><td>Weblogic 5.1</td></tr> |
| </table> |
| |
| <hr> |
| <h2><a name="ddcreator">ddcreator</a></h2> |
| <h3><b>Description:</b></h3> |
| <p>ddcreator will compile a set of Weblogic text-based deployment descriptors into a serialized |
| EJB deployment descriptor. The selection of which of the text-based descriptors are to be compiled |
| is based on the standard Ant include and exclude selection mechanisms. |
| |
| |
| <h3>Parameters:</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <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">descriptors</td> |
| <td valign="top">This is the base directory from which descriptors are selected.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">dest</td> |
| <td valign="top">The directory where the serialised deployment descriptors will be written</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">This is the classpath to use to run the underlying weblogic ddcreator tool. |
| This must include the <code>weblogic.ejb.utils.DDCreator</code> class</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre><ddcreator descriptors="${dd.dir}" |
| dest="${gen.classes}" |
| classpath="${descriptorbuild.classpath}"> |
| <include name="*.txt" /> |
| </ddcreator></code> |
| </pre> |
| |
| <hr> |
| <h2><a name="ejbc">ejbc</a></h2> |
| <h3><b>Description:</b></h3> |
| <p>The ejbc task will run Weblogic's ejbc tool. This tool will take a serialised deployment descriptor, |
| examine the various EJB interfaces and bean classes and then generate the required support classes |
| necessary to deploy the bean in a Weblogic EJB container. This will include the RMI stubs and skeletons |
| as well as the classes which implement the bean's home and remote interfaces. |
| <p> |
| The ant task which runs this tool is able to compile several beans in a single operation. The beans to be |
| compiled are selected by including their serialised deployment descriptors. The standard ant |
| <code>include</code> and <code>exclude</code> constructs can be used to select the deployment descriptors |
| to be included. |
| <p> |
| Each descriptor is examined to determiune whether the generated classes are out of date and need to be |
| regenerated. The deployment descriptor is de-serialized to discover the home, remote and |
| implementation classes. The corresponding source files are determined and checked to see their |
| modification times. These times and the modification time of the serialised descriptor itself are |
| compared with the modification time of the generated classes. If the generated classes are not present |
| or are out of date, the ejbc tool is run to generate new versions. |
| <h3>Parameters:</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <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">descriptors</td> |
| <td valign="top">This is the base directory from which the serialised deployment descriptors are selected.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">dest</td> |
| <td valign="top">The base directory where the generated classes, RIM stubs and RMI skeletons are written</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">manifest</td> |
| <td valign="top">The name of a manifest file to be written. This manifest will contain an entry for each EJB processed</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">src</td> |
| <td valign="top">The base directory of the source tree containing the source files of the home interface, |
| remote interface and bean implementation classes.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">This classpath must include both the <code>weblogic.ejbc</code> class and the |
| classfiles of the bean, home interface, remote interface, etc of the bean being |
| processed.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| <h3>Examples</h3> |
| <pre><ejbc descriptors="${gen.classes}" |
| src="${src.dir}" |
| dest="${gen.classes}" |
| manifest="${build.manifest}" |
| classpath="${descriptorbuild.classpath}"> |
| <include name="*.ser" /> |
| </ejbc></code> |
| </pre> |
| |
| <hr> |
| <h2><a name="wlrun">wlrun</a></h2> |
| <h3><b>Description:</b></h3> |
| <p>The <code>wlrun</code> task is used to start a weblogic server. The task runs |
| a weblogic instance in a separate Java Virtual Machine. A number of parameters |
| are used to control the operation of the weblogic instance. Note that the task, |
| and hence ant, will not complete until the weblogic instance is stopped. |
| |
| <h3>Parameters:</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <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">home</td> |
| <td valign="top">The location of the weblogic home that is to be used. This is the location |
| where weblogic is installed.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">The classpath to be used with the Java Virtual Machine that runs the Weblogic |
| Server. This is typically set to the Weblogic boot classpath.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">wlclasspath</td> |
| <td valign="top">The weblogic classpath used by the Weblogic Server.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">properties</td> |
| <td valign="top">The name of the server's properties file within the weblogic home directory |
| used to control the weblogic instance.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">The name of the weblogic server within the weblogic home which is to be run. |
| This defaults to "myserver"</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">policy</td> |
| <td valign="top">The name of the security policy file within the weblogic home directory that |
| is to be used. If not specified, the default policy file <code>weblogic.policy</code> |
| is used.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">jvmargs</td> |
| <td valign="top">Additional argument string passed to the Java Virtual Machine used to run the |
| Weblogic instance.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">args</td> |
| <td valign="top">Additional argument string passed to the Weblogic instance.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| |
| <hr> |
| <h2><a name="wlstop">wlstop</a></h2> |
| <h3><b>Description:</b></h3> |
| <p>The <code>wlstop</code> task is used to stop a weblogic instance which is currently running. |
| To shut down an instance you must supply both a username and a password. These will be stored |
| in the clear in the build script used to stop the instance. For security reasons, this task is |
| therefore only appropriate in a development environment. |
| |
| <h3>Parameters:</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <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">classpath</td> |
| <td valign="top">The classpath to be used with the Java Virtual Machine that runs the Weblogic |
| Shutdown comment.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">user</td> |
| <td valign="top">The username of the account which will be used to shutdown the server</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">password</td> |
| <td valign="top">The password for the account specified in the user parameter.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">url</td> |
| <td valign="top">The URL which describes the port to which the server is listening for T3 connections. |
| For example, t3://localhost:7001</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">delay</td> |
| <td valign="top">The delay in seconds after which the server will stop. This defaults to an |
| immediate shutdown.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| </table> |
| |
| |
| <hr> |
| <h2><a name="ejbjar">ejbjar</a></h2> |
| <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. Nested elements provide support for vendor |
| specific deployment tools. Currently, a nested element is provided for building Weblogic 5.1 |
| session/entity beans using the weblogic.ejbc tool as well as a nested element for building |
| TOPLink for WebLogic 2.5.1-enabled entity beans.</p> |
| |
| <p>This task supports two approaches to creating ejb jar files. The first approach 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>. |
| The second approach does not require a naming convention. This approach uses a specified a jar name |
| for the resultant ejb jar. If the jar name is present, then no naming convention is required. If the |
| jar name is not specified, then the default naming convention is expected for the deployment descriptor |
| files. |
| |
| <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 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>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. 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"> |
| <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">descriptordir</td> |
| <td valign="top">The base directory under which to scan for EJB deployment descriptors. If this |
| attribute is not specified, then the deployment descriptors must be located in |
| the directory specified by the 'srcdir' attribute.</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">srcdir</td> |
| <td valign="top">The base directory containing the .class files that make up the bean. |
| Note that this can be the same as the descriptordir if all files are |
| in the same directory tree.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <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">basejarname</td> |
| <td valign="top">The base name that is used for the generated jar files. If this attribute is specified, the |
| generic jar file name will use this value as the prefix (followed by the value specified in |
| the 'genericjarsuffix' attibute) and the resultant ejb jar file (followed by any suffix specified |
| in the nested element).</td> |
| <td valign="top" align="center">No</td> |
| </tr> |
| <tr> |
| <td valign="top">basenameterminator</td> |
| <td valign="top">String value used to substring out a string from the name of each deployment descriptor found, |
| which is then used to locate related deployment descriptors (e.g. the WebLogic descriptors). |
| For example, a basename of '.' and a deployment descriptor called 'FooBean.ejb-jar.xml' would |
| result in a basename of 'FooBean' which would then be used to find FooBean.weblogic-ejb-jar.xml |
| and FooBean.weblogic-cmp-rdbms-jar.xml, as well as to create the filenames of the jar files as |
| FooBean-generic.jar and FooBean-wl.jar. This attribute is not used if the 'basejarname' attribute |
| is specified.</td> |
| <td valign="top" align="center">No, defaults to '-'.</td> |
| </tr> |
| <tr> |
| <td valign="top">genericjarsuffix</td> |
| <td valign="top">String value appended to the basename of the deployment descriptor to create the filename of the |
| 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"><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 '.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>TOPLink for Weblogic element</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <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 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 '.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 file used as input to ejbc is retained.</td> |
| <td valign="top" align="center">No, defaults to false</td> |
| </tr> |
| <tr> |
| <td valign="top">toplinkdescriptor</td> |
| <td valign="top">This specifes the name of the TOPLink deployment descriptor file contained in the |
| 'descriptordir' directory.</td> |
| <td valign="top" align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">toplinkdtd</td> |
| <td valign="top">This specifies the location of the TOPLink DTD file. This can be a file path or |
| a file URL. This attribute is not required, but using a local DTD is recommended.</td> |
| <td valign="top" align="center">No, defaults to dtd file at www.objectpeople.com.</td> |
| </tr> |
| </table> |
| |
| |
| <h3>Examples</h3> |
| This example shows ejbjar being used to generate deployment jars using a Weblogic EJB container. This example |
| requires the naming standard to be used for the deployment descriptors. Using this format will create a ejb |
| jar file for each variation of '*-ejb-jar.xml' that is found in the deployment descriptor directory. |
| <pre> |
| <ejbjar srcdir="${build.classes}" |
| descriptordir="${descriptor.dir}"> |
| <weblogic destdir="${deploymentjars.dir}" |
| classpath="${descriptorbuild.classpath}"/> |
| <include name="**/*-ejb-jar.xml"/> |
| <exclude name="**/*weblogic*.xml"/> |
| </ejbjar> |
| </pre> |
| |
| This example shows ejbjar being used to generate a single deployment jar using a Weblogic EJB container. This example |
| does not require the deployment descriptors to use the naming standard. This will create only one ejb jar file - |
| 'TheEJBJar.jar'. |
| <pre> |
| <ejbjar srcdir="${build.classes}" |
| descriptordir="${descriptor.dir}" |
| basejarname="TheEJBJar"> |
| <weblogic destdir="${deploymentjars.dir}" |
| classpath="${descriptorbuild.classpath}"/> |
| <include name="**/ejb-jar.xml"/> |
| <exclude name="**/weblogic*.xml"/> |
| </ejbjar> |
| </pre> |
| |
| This example shows ejbjar being used to generate deployment jars for a TOPLink-enabled entity bean using a |
| Weblogic EJB container. This example does not require the deployment descriptors to use the naming standard. |
| This will create only one TOPLink-enabled ejb jar file - 'Address.jar'. |
| <pre> |
| <ejbjar srcdir="${build.dir}" |
| destdir="${solant.ejb.dir}" |
| descriptordir="${descriptor.dir}" |
| basejarname="Address"> |
| <weblogictoplink destdir="${solant.ejb.dir}" |
| classpath="${java.class.path}" |
| keepgeneric="false" |
| toplinkdescriptor="Address.xml" |
| toplinkdtd="file:///dtdfiles/toplink-cmp_2_5_1.dtd" |
| suffix=".jar"/> |
| <include name="**/ejb-jar.xml"/> |
| <exclude name="**/weblogic-ejb-jar.xml"/> |
| </ejbjar> |
| </pre> |
| |
| </body> |
| |
| </html> |
| |
| |
