<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en"><info><title>ejbjar Ant Task</title></info>
  
    <section xml:id="description"><info><title>Description</title></info>
    <para>
      The 
      <code>
        &lt;jonas&gt;
      </code>
       nested element uses the 
      <code>
        GenIC
      </code>
      -specific tool to build JOnAS-specific stubs and skeletons and construct a JAR file which may be deployed to the JOnAS Application Server. The build process will always determine if the EJB stubs/skeletons and the EJB-JAR file are up to date, and it will perform the minimum amount of work required.
    </para>
    <para>
      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 
      <code>
        ejb/Account-ejb-jar.xml
      </code>
       is located in the descriptor directory, the 
      <code>
        &lt;jonas&gt;
      </code>
       element will search for a JOnAS-specific EJB descriptor file named 
      <code>
        ejb/Account-jonas-ejb-jar.xml
      </code>
      , and a JAR file named 
      <code>
        ejb/Account.jar
      </code>
       will be written in the destination directory. The 
      <code>
        &lt;jonas&gt;
      </code>
       element can also use the JOnAS naming convention. Using the same example, the EJB descriptor can also be named 
      <code>
        ejb/Account.xml
      </code>
       (no base name terminator here) in the descriptor directory. The 
      <code>
        &lt;jonas&gt;
      </code>
       element will then search for a JOnAS-specific EJB descriptor file called 
      <code>
        ejb/jonas-Account.xml
      </code>
      . This convention does not strictly follow the ejb-jar naming convention recommendation, but it is supported for backward compatibility with previous version of JOnAS.
    </para>
    <para>
      Note that when the EJB descriptors are added to the JAR file, they are automatically renamed 
      <code>
        META-INF/ejb-jar.xml
      </code>
       and 
      <code>
        META-INF/jonas-ejb-jar.xml
      </code>
      .
    </para>
    <para>
      Furthermore, this naming behaviour 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.
    </para>
    </section>
    <section><info><title>Parameters:</title></info>
      
      <informaltable>
        <tgroup cols="3">
          <thead>
            <row valign="top">
              <entry>
                Attribute
              </entry>
              <entry>
                Description
              </entry>
              <entry align="center">
                Required
              </entry>
            </row>
          </thead>
          <tbody>
            <row valign="top">
              <entry>
                destdir
              </entry>
              <entry>
                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 "
                <code>
                  descriptordir
                </code>
                "         namespace.
              </entry>
              <entry align="center">
                Yes
              </entry>
            </row>
            <row valign="top">
              <entry>
                jonasroot
              </entry>
              <entry>
                The root directory for JOnAS.
              </entry>
              <entry align="center">
                Yes
              </entry>
            </row>
            <row valign="top">
              <entry>
                jonasbase
              </entry>
              <entry>
                The base directory for JOnAS. If omitted, it defaults         to 
                <code>
                  jonasroot.
                </code>
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                classpath
              </entry>
              <entry>
                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         prefixed to the classpath specified in the parent "ejbjar" task. A         nested "classpath" elements can also be used. Note that the needed         JOnAS JAR files are automatically added to the classpath.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                keepgenerated
              </entry>
              <entry>
                <code>
                  true
                </code>
                 if the intermediate Java source         files generated by GenIC must not be deleted. If omitted, it defaults         to 
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                nofastrmic
              </entry>
              <entry>
                if 
                <code>
                  true
                </code>
                , the external RMIC compiler is used        by GenIC.  The default is 
                <code>
                  false
                </code>
                , which means the internal        fast RMIC compiler is used.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                nocompil
              </entry>
              <entry>
                <code>
                  true
                </code>
                 if the generated source files must         not be compiled via the java and rmi compilers. If omitted, it         defaults to 
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                novalidation
              </entry>
              <entry>
                <code>
                  true
                </code>
                 if the XML deployment descriptors         must be parsed without validation. If omitted, it defaults to         
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                javac
              </entry>
              <entry>
                Java compiler to use. If omitted, it defaults to the         value of 
                <code>
                  build.compiler
                </code>
                 property.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                javacopts
              </entry>
              <entry>
                Options to pass to the java compiler.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                protocols
              </entry>
              <entry>
                Comma-separated list of protocols (chosen within         jeremie, jrmp, iiop, cmi) for which stubs should be generated.         Default is 
                <code>
                  jrmp,jeremie
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                rmicopts
              </entry>
              <entry>
                Options to pass to the rmi compiler.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                verbose
              </entry>
              <entry>
                Indicates whether or not to use -verbose switch. If         omitted, it defaults to 
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                additionalargs
              </entry>
              <entry>
                Add additional args to GenIC.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                keepgeneric
              </entry>
              <entry>
                <code>
                  true
                </code>
                 if the generic JAR file used as         input to GenIC must be retained. If omitted, it defaults to         
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                suffix
              </entry>
              <entry>
                String value appended to the JAR filename when creating each JAR.         If omitted, it defaults to ".jar".
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                nogenic
              </entry>
              <entry>
                If this attribute is set to 
                <code>
                  true
                </code>
                , JOnAS's         GenIC will not be run on the EJB JAR. Use this if you prefer to run         GenIC at deployment time. If omitted, it defaults to         
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                jvmopts
              </entry>
              <entry>
                Additional args to pass to the GenIC JVM.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                invokecmd
              </entry>
              <entry>
                If this attribute is set to 
                <code>
                  true
                </code>
                , GenIC will         use the Javac sun class to avoid using 'javac' command line. This is         useful for users getting 'java.io.Exception CreateProcess' because of too         long command lines. Defaults to 
                <code>
                  false
                </code>
                .
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      <para>
        As noted above, the jonas element supports additional &lt;classpath&gt; nested elements.
      </para>
    </section>
    <section><info><title>Examples</title></info>
      
      <para>
        Note :
         To avoid 
        <code>
          java.lang.OutOfMemoryError
        </code>
        , the element 
        <code>
          jvmopts
        </code>
         can be used to change the default memory usage. 
      </para>
      <para>
        This example shows ejbjar being used to generate deployment jars using a JOnAS EJB container. This example requires the naming standard to be used for the deployment descriptors. Using this format creates a EJB JAR file for each variation of  '*-jar.xml' that is located in the deployment descriptor directory. 
      </para>
      <screen>
      &lt;ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}"&gt;
        &lt;jonas destdir="${deploymentjars.dir}"
               jonasroot="${jonas.root}"
               protocols="jrmp,iiop"/&gt;
        &lt;include name="**/*.xml"/&gt;
        &lt;exclude name="**/jonas-*.xml"/&gt;
        &lt;support dir="${build.classes}"&gt;
             &lt;include name="**/*.class"/&gt;
        &lt;/support&gt;
      &lt;/ejbjar&gt;      </screen>
      <para>
        This example shows ejbjar being used to generate a single deployment jar using a JOnAS EJB container. This example does require the deployment descriptors to use the naming standard. This creates only one ejb jar file - 'TheEJBJar.jar'.
      </para>
      <screen>
      &lt;ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}"
              basejarname="TheEJBJar"&gt;
        &lt;jonas destdir="${deploymentjars.dir}"
               jonasroot="${jonas.root}"
               suffix=".jar"
               protocols="${genic.protocols}"/&gt;
        &lt;include name="**/ejb-jar.xml"/&gt;
        &lt;exclude name="**/jonas-ejb-jar.xml"/&gt;
      &lt;/ejbjar&gt;      </screen>
    </section>
</section>