<?xml version="1.0" encoding="UTF-8"?>
<chapter id="tools">
  <title>Other tools</title>

  <section id="tools_rarinfo">
    <title>Resource adapter information tool</title>

    <para>
      The IronJacamar distribution features a resource adapter information tool, that can provide the important 
      information about the resource adapter and a sample deployment descriptor.
    </para>

    <para>
      The information about the resource adapter is generated using the following command:
    </para>
        
    <programlisting>
./rar-info.sh myeis.rar
    </programlisting>

    <para>
      where the report will be located in <code>myeis-report.txt</code>. The tool can take an optional
      <code>-classpath</code> parameter such that additional external dependencies can be resolved against
      the resource adapter.
    </para>

    <para>
      The report will contain information about

      <itemizedlist spacing="compact">
        <listitem>
          The name of the resource adapter
        </listitem>
        <listitem>
          The Java EE Connector Architecture specification version
        </listitem>
        <listitem>
          The type of the resource adapter
        </listitem>
        <listitem>
          If the resource adapter supports reauthentication
        </listitem>
        <listitem>
          If the resource adapter is compliant (see the validator tool)
        </listitem>
        <listitem>
          If the resource adapter contains native libraries
        </listitem>
        <listitem>
          The structure of the resource adapter archive
        </listitem>
        <listitem>
          Overview of the resource adapter class
        </listitem>
        <listitem>
          Overview of the managed connection factory classes
        </listitem>
        <listitem>
          The connectory factory and connection API if common client interface isn't used
        </listitem>
        <listitem>
          Overview of the admin object classes
        </listitem>
        <listitem>
          Overview of the activation specification classes
        </listitem>
        <listitem>
          Metadata included, including the <code>MANIFEST.MF</code> file
        </listitem>
        <listitem>
          A sample deployment descriptor
        </listitem>
      </itemizedlist>

    </para>

    <para>
      The tool (<code>rar-info.sh</code>) is located in the <code>doc/as/</code> directory of the
      distribution.
    </para>

  </section>

  <section id="tools_migration">
    <title>Migration tool</title>

    <para>
      The IronJacamar distribution features a migration tool, that can convert the deployment
      format used in JBoss Application Server prior to version 7, and JBoss Enterprise Application Platform
      versions prior to version 6.
    </para>

    <para>
      Since there are different formats (XSDs) to deploy datasources and a resource adapters the tool
      can convert to both these formats.
    </para>

    <para>
      The tool (<code>converter.sh</code>) is located in the <code>doc/as/</code> directory of the
      distribution.
    </para>

    <section id="tools_migration_resource_adapters">
      <title>Resource adapters</title>

      <para>
        A resource adapter deployment is converted using the following command:
      </para>
        
      <programlisting>
./converter.sh -ra old-ds.xml new-ra.xml
      </programlisting>

      <para>
        which will convert the file <code>old-ds.xml</code> to <code>new-ra.xml</code>. The content of
        <code>new-ra.xml</code> can then be copied into the <code>resource-adapters</code> subsystem
        in WildFly or used directly in the IronJacamar/Standalone distribution.
      </para>

      <note>
        Note that, the tool will do a best effort to convert all old attributes and elements to
        the new format. It will be necessary to make additional changes to the generated file.
        Please, consult this documentation for additional information.
      </note>

      <section id="tools_migration_resource_adapters_weblogic">
        <title>WebLogic converter</title>
        
        <para>
          The resource adapter converter tool can also convert the Oracle WebLogic <code>weblogic-ra.xml</code> files
          to the IronJacamar format.
        </para>

        <para>
          The following command line can be used:
        </para>

        <programlisting>
./converter.sh -ra --weblogic weblogic-ra.xml new-ra.xml
        </programlisting>

        <para>
          to get a best effort convertion of the Oracle WebLogic deployment file.
        </para>
      </section>
    </section>

    <section id="tools_migration_datasources">
      <title>Data sources</title>

      <para>
        A data source deployment is converted using the following command:
      </para>
        
      <programlisting>
./converter.sh -ds old-ds.xml new-ds.xml
      </programlisting>

      <para>
        which will convert the file <code>old-ds.xml</code> to <code>new-ds.xml</code>. The content of
        <code>new-ds.xml</code> can then be copied into the <code>datasources</code> subsystem
        in WildFly or used directly in the IronJacamar/Standalone distribution.
      </para>

      <note>
        Note that, the tool will do a best effort to convert all old attributes and elements to
        the new format. It will be necessary to make additional changes to the generated file.
        Please, consult this documentation for additional information.
      </note>
    </section>

  </section>

  <section id="tools_tracer">
    <title>Tracer tool</title>

    <para>
      Debugging Java EE Connector Architecture scenarios can be a complex task, as the interaction
      between the application and the resource adapter depends both on the implementation of the resource
      adapter but also on how it is configured.
    </para>

    <para>
      IronJacamar features a tracer tool that will help users to get an overview of the interactions
      performed between the application and resource adapter.
    </para>

    <para>
      The tracer produces machine readable codes at the <code>TRACE</code> logging category
    </para>
    <programlisting>
org.jboss.jca.core.tracer
    </programlisting>
    <para>
      which can then be processed with the <code>tracer-report</code> tool, located in <code>docs/as/</code>.
    </para>

    <para>
      The tool is executed with
    </para>
    <programlisting>
./tracer-report.sh logfile
    </programlisting>
    <para>
      where <code>logfile</code> contains the <code>TRACE</code> logging.
    </para>

    <para>
      The output are HTML reports that shows the interaction performed by all active resource adapters, and the
      applications using them.
    </para>

    <para>
      In addition, a UML sequence diagram is produced for valid interaction scenarios, which can be converted into
      an image using the <code>SDedit</code> application.
    </para>

    <para>
      For invalid interaction scenarios the tool will try and highlight the issue such that the collected log between the
      two timestamps identified can be investigated.
    </para>

  </section>


</chapter>
