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

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

      <para>The IronJacamar container features a validator which checks resource adapter archives
        against the Java Connector Architecture (JCA) specification.</para>

      <para>The validator is doing a static analysis of the resource adapter classes
        and checks them against the rules defined in the validator.</para>

      <para>The validator is used in the deployer chain of the JCA container, and is available 
        as a standalone tool, as an Apache Ant task and as a Apache Maven plugin too.</para>
   </section>

   <section id="validator_reports">
      <title>Reports</title>

      <para>The validator works by scanning the resource adapter in question and output
        a report which lists which rules have been violated.</para>

      <para>An example could be</para>

      <programlisting>
Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl
      </programlisting>

      <para>which means that <code>com.mycompany.myproject.ResourceAdapterImpl</code> is missing
        an <code>equals</code> and <code>hashCode</code> implementation.</para>

      <table frame="all">
        <title>Validator report</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">Key</entry>
              <entry align="left">Desciption</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><code>Severity</code></entry>
              <entry>
                Specifies the severity of the rule.
                <para>
                  <itemizedlist spacing="compact">
                    <listitem>
                      ERROR: Critical error which must be fixed in order for the
                      resource adapter to operate correctly.
                    </listitem>
                    <listitem>
                      WARN: Error which should be fixed in order for the
                      resource adapter to operate correctly.
                    </listitem>
                  </itemizedlist>
                </para>
              </entry>
            </row>
            <row>
              <entry><code>Section</code></entry>
              <entry>
                A reference to a section in the Java Connector Architecture specification
                where the requirement is defined.
              </entry>
            </row>
            <row>
              <entry><code>Descrption</code></entry>
              <entry>
                A short description of the rule.
              </entry>
            </row>
            <row>
              <entry><code>Code</code></entry>
              <entry>
                The class which triggered the rule.
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

   </section>

   <section id="validator_standalone">
      <title>Running the standalone validator</title>

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

      <programlisting>
cd doc/validator
./validator.sh &lt;file&gt;
      </programlisting>

      <para>The reports will be generated into the current directory under the name of 
        <code>&lt;file&gt;.log</code>.</para>

   </section>

   <section id="validator_ant">
      <title>Apache Ant integration</title>

      <para>The validator integrates with Apache Ant such that you can generate the reports directly from 
        your build environment before deploying the resoruce adapter into the IronJacamar container.</para>

      <para>First you have to define the <code>taskdef</code> for the task</para>

      <programlisting>
&lt;taskdef name="validator"
         classname="org.jboss.jca.validator.ant.ValidatorTask"
         classpathref="ironjacamar.lib.path.id"/&gt;
      </programlisting>

      <para>See the Apache Ant documentation for additional instructions on installation.</para>

      <section id="validator_ant_usage">
        <title>Usage</title>

        <programlisting>
&lt;validator rarFile="${myArchive.rar}" outputDir="${report.dir}"/&gt;
        </programlisting>

        <table frame="all">
          <title>Apache Ant: validator</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1"/>
            <colspec colname="c2" colwidth="5*"/>
            <thead>
              <row>
                <entry align="left">Key</entry>
                <entry align="left">Value</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>rarFile</code></entry>
                <entry>
                  The resource adapter file
                </entry>
              </row>
              <row>
                <entry><code>outputDir</code></entry>
                <entry>
                  The directory where the reports should be generated
                </entry>
              </row>
              <row>
                <entry><code>classpath</code></entry>
                <entry>
                  A classpath to resolve additional dependencies against
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
      </section>

   </section>

   <section id="validator_maven">
      <title>Apache Maven integration</title>

      <para>The validator integrates with Apache Maven such that you can generate the reports directly from 
        your build environment before deploying the resoruce adapter into the IronJacamar container.</para>

      <para>To be able to use the validator plugin in your Maven project, you will have to add the following plugin declaration
        in the pom.xml of your project:</para>
        <programlisting language="xml">
<![CDATA[
<build>
  <plugins>
    <plugin>
      <groupId>org.jboss.ironjacamar</groupId>
      <artifactId>ironjacamar-validator-maven</artifactId>
      <!-- The version of the plugin you want to use -->
      <version>1.2.0.Final</version>
      <executions>
        <execution>
          <goals>
            <goal>validate</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <!-- output directory-->
        <outputDir>.</outputDir>
        
        <!-- rar filename -->
        <rarFile>/path/to/myresourceadapter.rar</rarFile>
        
        <!--  optional classpath 
        <classpath>
          <param>classpath1</param>
          <param>classpath2</param>
        </classpath>
        -->
      </configuration>
    </plugin>
  </plugins>
</build>        
]]>
        </programlisting>
      <para>
        <note>By default, the validator-maven plugin is attached to the "package" phase of Maven.</note>
      </para>

      <para>See the Apache Maven documentation for additional instructions on installation.</para>

      <section id="validator_maven_usage">
        <title>Usage</title>

        <para>Once you have configured your project's pom.xml to include the validator-maven plugin, 
          as explained earlier, you can generate the report by running the package goal on your project.</para>

        <programlisting>
mvn clean package
        </programlisting>
        
        <table frame="all">
          <title>Apache Maven: validator</title>
          <tgroup cols="2" align="left" colsep="1" rowsep="1">
            <colspec colname="c1"/>
            <colspec colname="c2" colwidth="5*"/>
            <thead>
              <row>
                <entry align="left">Key</entry>
                <entry align="left">Value</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry><code>rarFile</code></entry>
                <entry>
                  The resource adapter file
                </entry>
              </row>
              <row>
                <entry><code>outputDir</code></entry>
                <entry>
                  The directory where the reports should be generated
                </entry>
              </row>
              <row>
                <entry><code>classpath</code></entry>
                <entry>
                  A classpath to resolve additional dependencies against
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </section>
      
   </section>

</chapter>
