<?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" xml:id="ra.jonas-ra"><info><title>Defining the JOnAS Connector Deployment Descriptor</title></info>

    <para>
      The
      jonas-ra.xml
       contains JOnAS specific information describing deployment information, logging, pooling, jdbc connections, and RAR config property values.
    </para>
    <section xml:id="connector.desc.depl"><info><title>Deployment Tags</title></info>

      <variablelist>
        <varlistentry>
          <term>jndiname (Required)</term>
          <listitem><para>Name the RAR will be registered as. This value will be used in the resource-ref section of an EJB.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>rarlink</term>
          <listitem><para>
            Jndiname of a base RAR file.
            Useful for deploying multiple connection factories without having to deploy the complete RAR file again.
            When this is used, the only entry in RAR is a META-INF/jonas-ra.xml.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>native-lib</term>
          <listitem><para>
            Directory where additional files in the RAR should be deployed.
          </para></listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section xml:id="connector.desc.log"><info><title>Logging Tags</title></info>

      <variablelist>
        <varlistentry>
          <term>log-enabled</term>
          <listitem><para>
            Determines if logging should be enabled for the RAR.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>log-topic</term>
          <listitem><para>
            Log topic to use for the PrintWriter logger, which allows a separate handler for each deployed RAR.
          </para></listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section xml:id="connector.desc.pool"><info><title>Pooling Tags</title></info>

      <variablelist>
        <varlistentry>
          <term>pool-init</term>
          <listitem><para>
            Initial size of the managed connection pool.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>pool-min</term>
          <listitem><para>
            Minimum size of the managed connection pool.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>pool-max</term>
          <listitem><para>
            Maximum size of the managed connection pool.  Value of -1         is unlimited.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>pool-max-age</term>
          <listitem><para>
            Maximum number of milliseconds to keep the managed         connection in the pool.  Value of 0 is an unlimited amount of       time.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>pstmt-max</term>
          <listitem><para>
            Maximum number of PreparedStatements per managed         connection in the pool. Only needed with the JDBC RA of JOnAS or         another database vendor's RAR. Value of 0 is unlimited and -1         disables the cache.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>pstmt-cache-policy</term>
          <listitem><para>
            Prepared statement cache policy. Possible values are List or Map.
          </para></listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section xml:id="connector.desc.jdbc"><info><title>JDBC Connection Tags</title></info>

      <note><para>Only valid with a Connection implementation of java.sql.Connection.</para></note>
      <variablelist>
        <varlistentry>
          <term>jdbc-check-level</term>
          <listitem><para>
            Level of checking that will be done for the jdbc         connection.  Values are 0 for no checking, 1 to validate that the         connection is not closed before returning it, and greater than 1 to         send the jdbc-test-statement.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>jdbc-test-statement</term>
          <listitem><para>
            Test SQL statement sent on the connection if         the jdbc-check-level is set accordingly.
          </para></listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section xml:id="connector.desc.prop"><info><title>Config Property Value Tags</title></info>

          <para>
            Each entry must correspond to the config-property specified in the
            ra.xml
             of the RAR file.  The default values specified in the
            ra.xml
             will         be loaded first and any values set in the
            jonas-ra.xml
             will         override the specified defaults.
          </para>
    </section>
    <section><info><title>Deployment Descriptor Examples</title></info>

      <para>
        The following portion of a
        jonas-ra.xml
         file shows the linking to a base RAR file named BaseRar. All properties from the base RAR will be inherited and any values given in this
        jonas-ra.xml
         will override the other values.
      </para>
      <screen>
  &lt;jonas-resource&gt;
    &lt;jndiname&gt;rar1&lt;/jndiname&gt;
    &lt;rarlink&gt;BaseRar&lt;/rarlink&gt;
    &lt;native-lib&gt;nativelib&lt;/native-lib&gt;
    &lt;log-enabled&gt;false&lt;/log-enabled&gt;
    &lt;log-topic&gt;com.xxx.rar1&lt;/log-topic&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;ip&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;www.xxx.com&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    .
    .
  &lt;/jonas-resource&gt;      </screen>
      <para>
        The following portion of a
        jonas-ra.xml
         file shows the configuration of a jdbc rar file.
      </para>
      <screen>
  &lt;jonas-resource&gt;
    &lt;jndiname&gt;jdbc1&lt;/jndiname&gt;
    &lt;rarlink&gt;&lt;/rarlink&gt;
    &lt;native-lib&gt;nativelib&lt;/native-lib&gt;
    &lt;log-enabled&gt;false&lt;/log-enabled&gt;
    &lt;log-topic&gt;com.xxx.jdbc1&lt;/log-topic&gt;
    &lt;pool-params&gt;
      &lt;pool-init&gt;0&lt;/pool-init&gt;
      &lt;pool-min&gt;0&lt;/pool-min&gt;
      &lt;pool-max&gt;100&lt;/pool-max&gt;
      &lt;pool-max-age&gt;0&lt;/pool-max-age&gt;
      &lt;pstmt-max&gt;20&lt;/pstmt-max&gt;
      &lt;pstmt-cache-policy&gt;Map&lt;/pstmt-cache-policy&gt;
    &lt;/pool-params&gt;
    &lt;jdbc-conn-params&gt;
      &lt;jdbc_check-level&gt;2&lt;/jdbc_check-level&gt;
      &lt;jdbc-test-statement&gt;select 1&lt;/jdbc-test-statement&gt;
    &lt;/jdbc-conn-params&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;url&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;jdbc:oracle:thin:@test:1521:DB1&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    .
    .
  &lt;/jonas-resource&gt;      </screen>
    </section>
  </section>
