<?xml version="1.0" encoding="UTF-8"?>
<chapter id="codegenerator">
   <title>Code generator</title>

   <section id="codegenerator_introduction">
      <title>Introduction</title>

      <para>The IronJacamar project includes a resource adapter code generator which can
        generate a complete code skeleton that will help developers get started with
        their development tasks.</para>

   </section>

   <section id="codegenerator_functionality">
      <title>Functionality</title>

      <para>The code generator will generate a resource adapter code skeleton based
        on the user input. The code generator supports</para>

      <itemizedlist spacing="compact">
        <listitem>
          Resource adapter using JCA 1.7 annotations
        </listitem>
        <listitem>
          Resource adapter using JCA 1.7 metadata
        </listitem>
        <listitem>
          Resource adapter using JCA 1.6 annotations
        </listitem>
        <listitem>
          Resource adapter using JCA 1.6 metadata
        </listitem>
        <listitem>
          Resource adapter using JCA 1.5
        </listitem>
        <listitem>
          Resource adapter using JCA 1.0
        </listitem>
        <listitem>
          Apache Ant build environment
        </listitem>
        <listitem>
          Apache Ant + Ivy build environment
        </listitem>
        <listitem>
          Gradle build environment
        </listitem>
        <listitem>
          Apache Maven build environment
        </listitem>
        <listitem>
          Test suite environment
        </listitem>
      </itemizedlist>

   </section>

   <section id="codegenerator_running">
      <title>Running the tool</title>

      <para>The code generator can be run on the command line by</para>

      <programlisting>
./codegenerator.sh
      </programlisting>

      <para>from the <code>doc/codegenerator</code> directory.</para>

      <para>The code generator supports the following arguments</para>

      <table frame="all">
        <title>Code generator arguments</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth="2*"/>
          <colspec colname="c2" colwidth="3*"/>
          <thead>
            <row>
              <entry align="left">Argument</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>-o</code></entry>
              <entry>
                Specifies the output directory for the code skeleton.
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>The developer must then answer various questions regarding the
        properties of the resource adapter.</para>

      <section id="codegenerator_input">
        <title>Developer Input</title>

        <para>This section describes the questions that are asked
          in order to generate the code.</para>
        
        <table frame="all">
          <title>Developer input</title>
          <tgroup cols="4" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="2*"/>
            <colspec colname="c2" colwidth="1*"/>
            <colspec colname="c3" colwidth="3*"/>
            <colspec colname="c4" colwidth="1*"/>
            <thead>
              <row>
                <entry align="left">Question</entry>
                <entry align="left">Spec</entry>
                <entry align="left">Desciption</entry>
                <entry align="left">Type</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  Profile version (1.7/1.6/1.5/1.0)
                </entry>
                <entry>All</entry>
                <entry>
                  Defines which Java EE Connector Architecture specification that
                  the resource adapter should target
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Type (O/Outbound/I/Inbound/B/Bidirectional)
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  Defines if the resource adapter should contain outbound communication., inbound communication
                  or both
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Package name
                </entry>
                <entry>All</entry>
                <entry>
                  The package name of the resource adapter
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Transaction support (N/NoTransaction/L/LocalTransaction/X/XATransaction)
                </entry>
                <entry>All</entry>
                <entry>
                  The transaction support level
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Reauthentication (Y/Yes/N/No)
                </entry>
                <entry>All</entry>
                <entry>
                  If the resource adapter supports reauthentication
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Use annotations (Y/Yes/N/No)
                </entry>
                <entry>JCA 1.6+</entry>
                <entry>
                  Should annotations be used for specifying the structure. If 'No' is selected a <code>META-INF/ra.xml</code>
                  is generated
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Include a ResourceAdapter (Y/Yes/N/No)
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  Should an instance of a resource adapter class be included in the archive
                </entry>
                <entry>Outbound</entry>
              </row>
              <row>
                <entry>
                  Resource adapter class name 
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The class name of the resource adapter
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Should the resource adapter class be Serializable (Y/Yes/N/No)
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  Should the resource adapter class be serializable
                </entry>
                <entry>Outbound</entry>
              </row>
              <row>
                <entry>
                  Managed connection factory class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the managed connection factory
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Managed connection class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the managed connection
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Connection interface class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the connection interface
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Connection implementation class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the connection implementation
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Connection factory interface class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the connection factory interface
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Connection factory implementation class name
                </entry>
                <entry>All</entry>
                <entry>
                  The class name of the connection factory implementation
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Resource adapter config properties
                </entry>
                <entry>All</entry>
                <entry>
                  Include a configuration properties in the resource adapter instance
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Managed connection factory config properties
                </entry>
                <entry>All</entry>
                <entry>
                  Include a configuration properties in the managed connection factory instance
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Use ResourceAdapterAssociation (Y/Yes/N/No)
                </entry>
                <entry>All</entry>
                <entry>
                  Associate the managed connection factory instance with the resource adapter instance
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Use CCI (Y/Yes/N/No)
                </entry>
                <entry>All</entry>
                <entry>
                  Use the Common Client Interface for the connection / connection factory in the 'Outbound' part
                  of the resource adapter
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  MessageListener interface name
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The name of the message listener interface for the activation
                </entry>
                <entry>Inbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  ActivationSpec class name
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The class name of the activation specification instance
                </entry>
                <entry>Inbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  ActivationSpec config properties
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  Include configuration properties in the activation specification instance
                </entry>
                <entry>Inbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Activation class name
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The class name of the activation instance
                </entry>
                <entry>Inbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Add methods to connection interface (Y/Yes/N/No) [N]:
                </entry>
                <entry>All</entry>
                <entry>
                  Use for add methods to connection interface
                </entry>
                <entry>Outbound or Bidirectional</entry>
              </row>
              <row>
                <entry>
                  Include an admin object (Y/Yes/N/No) 
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  Should an admin object be added to the project
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Use ResourceAdapterAssociation on admin object(Y/Yes/N/No)
                </entry>
                <entry>JCA 1.5</entry>
                <entry>
                  Associate the admin object instance with the resource adapter instance
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Admin object interface name
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The interface name of the admin object
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Admin object class name
                </entry>
                <entry>JCA 1.5+</entry>
                <entry>
                  The class name of the admin object
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Admin object config properties
                </entry>
                <entry>JCA 1.5</entry>
                <entry>
                  Include a configuration properties in the admin object instance
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Generate a MBean class (Y/Yes/N/No)
                </entry>
                <entry>All</entry>
                <entry>
                  Generate a MBean for the resource adapter
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Integrate EIS test server (Y/Yes/N/No)
                </entry>
                <entry>All</entry>
                <entry>
                  Should the IronJacamar test EIS server be integrated
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Use JBoss Logging (Y/Yes/N/No) [N]:
                </entry>
                <entry>All</entry>
                <entry>
                  Use JBoss Logging instead of Java Util Logging
                </entry>
                <entry></entry>
              </row>
              <row>
                <entry>
                  Build environment [A/Ant/I/Ant+Ivy/M/Maven/G/Gradle]
                </entry>
                <entry>All</entry>
                <entry>
                  Type of build environment
                </entry>
                <entry></entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
      </section>

   </section>

   <section id="codegenerator_code">
      <title>Generated code</title>

      <para>The generated code will consist of the classes making up the resource adapter
        and a test suite environment based on the embedded distribution.</para>

      <section id="codegenerator_ant">
        <title>Apache Ant build environment</title>
        <para>The following targets are supported in the Apache Ant build environment</para>

      <table frame="all">
        <title>Apache Ant build environment</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth="2*"/>
          <colspec colname="c2" colwidth="3*"/>
          <thead>
            <row>
              <entry align="left">Target</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>compile</code></entry>
              <entry>
                Compiles all the files
              </entry>
            </row>
            <row>
              <entry><code>rar</code></entry>
              <entry>
                Builds the resource adapter archive
              </entry>
            </row>
            <row>
              <entry><code>prepare-test</code></entry>
              <entry>
                Prepares the test environment
              </entry>
            </row>
            <row>
              <entry><code>test</code></entry>
              <entry>
                Executes the tests
              </entry>
            </row>
            <row>
              <entry><code>docs</code></entry>
              <entry>
                Generates the documentation
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </section>

      <section id="codegenerator_ant_ivy">
        <title>Apache Ant + Ivy build environment</title>
        <para>The following targets are supported in the Apache Ant + Ivy build environment</para>

      <table frame="all">
        <title>Apache Ant + Ivy build environment</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth="2*"/>
          <colspec colname="c2" colwidth="3*"/>
          <thead>
            <row>
              <entry align="left">Target</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>compile</code></entry>
              <entry>
                Compiles all the files
              </entry>
            </row>
            <row>
              <entry><code>rar</code></entry>
              <entry>
                Builds the resource adapter archive
              </entry>
            </row>
            <row>
              <entry><code>prepare-test</code></entry>
              <entry>
                Prepares the test environment
              </entry>
            </row>
            <row>
              <entry><code>test</code></entry>
              <entry>
                Executes the tests
              </entry>
            </row>
            <row>
              <entry><code>docs</code></entry>
              <entry>
                Generates the documentation
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </section>

      <section id="codegenerator_gradle">
        <title>Gradle build environment</title>
        <para>The Gradle build environment currently support the standard tasks such as</para>

      <table frame="all">
        <title>Gradle build environment</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth="2*"/>
          <colspec colname="c2" colwidth="3*"/>
          <thead>
            <row>
              <entry align="left">Target</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>compile</code></entry>
              <entry>
                Compiles all the files
              </entry>
            </row>
            <row>
              <entry><code>test</code></entry>
              <entry>
                Executes the tests
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </section>

      <section id="codegenerator_maven">
        <title>Apache Maven build environment</title>
        <para>The following targets are supported in the Apache Maven build environment</para>

      <table frame="all">
        <title>Apache Maven build environment</title>
        <tgroup cols="2" align="left" colsep="1" rowsep="1">
          <colspec colname="c1" colwidth="2*"/>
          <colspec colname="c2" colwidth="3*"/>
          <thead>
            <row>
              <entry align="left">Target</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>compile</code></entry>
              <entry>
                Compiles all the files
              </entry>
            </row>
            <row>
              <entry><code>test</code></entry>
              <entry>
                Executes the tests
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      </section>
   </section>

</chapter>
