<?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>genic Ant Task</title></info>
  
    <section><info><title>Why is there a new task?</title></info>
      
      <para>
        Previous versions of the JOnAS EjbJar Ant task have some limitations, especially when you are developing webservices.
      </para>
      <para>
        In previous versions of JOnAS, jonas-ejb-jar constructed the JAR for you, using information gathered from the ejb-jar.xml and from the classes themselves (dependencies using BCEL). But if you have a Session Bean exposed as a webservice, you want to have more files in your archive (
        <code>
          webservices.xml
        </code>
        , 
        <code>
          JAX-RPC mapping file
        </code>
        , 
        <code>
          WSDL
        </code>
         + imported 
        <code>
          WSDL definitions
        </code>
         + imported 
        <code>
          XML Schema
        </code>
        ).
      </para>
      <para>
        The older task did not package these files inside the archive, and therefore, when GenIC loaded the descriptors, some dependencies were missing, causing GenIC to throw an exception.
      </para>
      <para>
        The solution is to let the developer create the JAR file, so that the exact content of the file can be controlled.
      </para>
      <para>
        The file should have at least the following content: 
      </para>
      <itemizedlist>
        <listitem><para>
          META-INF/ejb-jar.xml
        </para></listitem>
        <listitem><para>
          META-INF/jonas-ejb-jar.xml
        </para></listitem>
        <listitem><para>
          **/*.class
        </para></listitem>
      </itemizedlist>
      <para>
        Notice that webservices files are optional. 
      </para>
    </section>
    <section><info><title>Task Attributes</title></info>
      
      <para>
        The 
        <code>
          genic
        </code>
         task supports most attributes of the 
        <code>
          jonas-ejb-jar
        </code>
         task.
      </para>
      <para>
        Differences:
      </para>
      <itemizedlist>
        <listitem><para>
          Removed 
          <code>
            destdir
          </code>
          : JAR files are directly modified
        </para></listitem>
        <listitem><para>
          Removed 
          <code>
            classpath
          </code>
          : classpath is now set as inner element
        </para></listitem>
        <listitem><para>
          Removed 
          <code>
            novalidation
          </code>
          : validation attribute is used now
        </para></listitem>
        <listitem><para>
          Removed 
          <code>
            keepgeneric
          </code>
          : not meaningful (input JAR is already specific)
        </para></listitem>
        <listitem><para>
          Removed 
          <code>
            suffix
          </code>
          : not meaningful (no JAR generated)
        </para></listitem>
        <listitem><para>
          Removed 
          <code>
            nogenic
          </code>
          : not meaningful (we want to run GenIC)
        </para></listitem>
      </itemizedlist>
      <informaltable>
        <tgroup cols="3">
          <thead>
            <row valign="top">
              <entry>
                Attribute
              </entry>
              <entry>
                Description
              </entry>
              <entry>
                Required
              </entry>
            </row>
          </thead>
          <tbody>
            <row valign="top">
              <entry>
                jonasroot
              </entry>
              <entry>
                The root directory for JOnAS.
              </entry>
              <entry align="center">
                Yes (Can be read from ${jonas.root} property if not set)
              </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>
                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>
                validation
              </entry>
              <entry>
                <code>
                  true
                </code>
                 if the XML deployment descriptors         must be parsed with validation. If omitted, it defaults to         
                <code>
                  true
                </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 from         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 arguments to GenIC.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                jvmopts
              </entry>
              <entry>
                Additional arguments to pass to the GenIC JVM.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                jvmdebug
              </entry>
              <entry>
                Indicates whether you want to debug the forked JVM; it        defaults to 
                <code>
                  false
                </code>
                . The JVM will be suspended and waiting         a connection on port 12345.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row>
              <entry valign="top">
                invokecmd
              </entry>
              <entry valign="top">
                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" valign="top">
                No
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      <informaltable>
        <tgroup cols="3">
          <thead>
            <row valign="top">
              <entry>
                Nested Element
              </entry>
              <entry>
                Description
              </entry>
              <entry>
                Required
              </entry>
            </row>
          </thead>
          <tbody>
            <row valign="top">
              <entry>
                classpath
              </entry>
              <entry>
                The additional classpath entries used when generating EJB stubs and         skeletons.
              </entry>
              <entry align="center">
                No
              </entry>
            </row>
            <row valign="top">
              <entry>
                fileset
              </entry>
              <entry>
                Points out the ejb-jars that will be processed by GenIC.        Note that you can add as many filesets as you want (useful if        your JARs are in different directories).
              </entry>
              <entry align="center">
                Yes (at least 1)
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section><info><title>Example:</title></info>
      
      <orderedlist>
        <listitem><para>
          First, define this new task: 
          <screen>
&lt;taskdef name="genic"
    classname="org.objectweb.jonas.ant.GenICTask"
    classpath="${jonas.root}/lib/common/ow_jonas_ant.jar" /&gt;
          </screen>
        </para></listitem>
        <listitem><para>
          Then use it:  
          <orderedlist>
            <listitem><para>
              Create the JAR file : 
              <screen>

&lt;jar destfile="${temp.ejbjars.dir}/my-ejbjar.jar"&gt;
    &lt;metainf dir="${etc.dir}/META-INF" /&gt;

    &lt;fileset dir="${classes.dir}"&gt;
        &lt;include name="org/objectweb/jonas/myejbjar/*.class" /&gt;
    &lt;/fileset&gt;
&lt;/jar&gt;
              </screen>
            </para></listitem>
            <listitem><para>
              Process this JAR with the GenIC task : 
              <screen>

&lt;genic keepgenerated="true"
       protocols="${protocols.names}"&gt;

    &lt;fileset dir="${temp.dir}"&gt;
        &lt;include name="ejbjars/my-ejbjar.jar" /&gt;
    &lt;/fileset&gt;
&lt;/genic&gt;
              </screen>
            </para></listitem>
          </orderedlist>
        </para></listitem>
      </orderedlist>
    </section>
  </section>