<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="config.ra" xml:lang="en"
         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">
  <info>
    <title>Configuring JDBC Resource Adapters</title>
  </info>

  <para>Connection of an J2EE application to databases is done through JDBC
  Resource Adapters (JDBC RA).</para>

  <para>Such Resource Adapters are deployed via the <emphasis
  role="bold">resource</emphasis> service as seen in <xref
  linkend="services.resource.config" />.</para>

  <para>For both container-managed or bean-managed persistence, the JDBC
  Resource Adapter makes use of relational storage systems through the JDBC
  interface.</para>

  <para>JDBC connections are obtained from a JDBC RA.</para>

  <para>The JDBC RA implements the J2EE Connector Specification using the
  DataSource interface as defined in the <link
  xlink:href="http://java.sun.com/javase/technologies/database/index.jsp">JDBC</link>
  standard extensions.</para>

  <para>An JDBC RA is configured to identify a database and a means to access
  it via a JDBC driver. Multiple JDBC RAs can be deployed either via the
  j<filename>onas.properties </filename>file or included in the <filename
  class="directory">autoload</filename> directory of the <emphasis
  role="bold">resource</emphasis> service.</para>

  <para>The following section explains how JDBC RARs can be defined and
  configured in the JOnAS server.</para>

  <para>To support distributed transactions, the JDBC RA requires the use of
  at least a JDBC2-XA-compliant driver. Such drivers implementing the
  XADataSource interface are not always available for all relational
  databases. The JDBC RA provides a generic driver-wrapper that emulates the
  XADataSource interface on a regular JDBC driver. It is important to note
  that this driver-wrapper does not ensure a real two-phase commit for
  distributed database transactions.</para>

  <para></para>

  <section>
    <info>
      <title>Generic JDBC Resource Adapters</title>
    </info>

    <para>The generic JDBC RAs of JOnAS provide implementations of the
    <classname>java.sql.Driver</classname>,
    <classname>javax.sql.DataSource</classname>,
    <classname>javax.sql.</classname><classname>ConnectionPoolDataSource</classname>,
    and <classname>javax.sql.XADataSource</classname> interfaces. They are
    located in the <filename
    class="directory">$JONAS_ROOT/rars/autoload</filename> directory and thus
    are deployed automatically.They consist of base (or generic) RAs
    facilitating the build of the user JDBC RAs.</para>

    <para>Depending on the relational database management server and the
    available interface in the used JDBC-compliant driver, the user JDBC RA is
    linked (through the RAR link feature) to a generic RA (for example, the
    Driver's one). In this case, the user RA contains only a jonas-ra.xml file
    with some specific parameters, such as the connection url, the
    user/password, or the JDBC-Driver class.</para>

    <para><informaltable>
        <tgroup cols="3">
          <tbody>
            <row>
              <entry align="center">Resource adapter provided with
              JOnAS</entry>

              <entry align="center">description</entry>

              <entry align="center">jndi name</entry>
            </row>

            <row>
              <entry align="center">rars/autoload/JOnAS_jdbcDS.rar</entry>

              <entry>Generic JDBC RA that implements the
              <classname>DataSource</classname> interface</entry>

              <entry align="center">JOnASJDBC_DS</entry>
            </row>

            <row>
              <entry align="center">rars/autoload/JOnAS_jdbcDM.rar</entry>

              <entry>Generic JDBC RA that implements the
              <classname>Driver</classname> interface</entry>

              <entry align="center">JOnASJDBC_DM</entry>
            </row>

            <row>
              <entry align="center">rars/autoload/JOnAS_jdbcCP.rar</entry>

              <entry>Generic JDBC RA that implements the
              <classname>ConnectionPoolDataSource</classname>
              interface</entry>

              <entry align="center">JOnASJDBC_CP</entry>
            </row>

            <row>
              <entry align="center">rars/autoload/JOnAS_jdbcXA.rar</entry>

              <entry>Generic resource adapter that implements the
              <classname>XADataSource</classname> interface</entry>

              <entry align="center">JOnASJDBC_XA</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable></para>
  </section>

  <section>
    <info>
      <title>Specific JDBC Resource Adapter</title>
    </info>

    <para>The remainder of this section, which describes how to define and
    configure JDBC RAs, is specific to JOnAS. However, the way to use these
    JDBC RAs in the Application Component methods is standard, i.e., via the
    resource manager connection factory references (refer to the example in
    the section <link xlink:href="ejb2_programmer_guide.html#ejb2.bmp">Writing
    Database Access Operations</link>.</para>

    <para>An RAR file must be deployed as explained in <xref
    linkend="services.resource.config" />.</para>

    <para>Usually a resource Adapter contains in its <filename
    class="extension">rar</filename> file all the classes needed to access to
    the external resource. In the case of a specific JDBC RA it contains only
    a JOnAS specific deployment descriptor <filename>jonas-ra.xml</filename>
    that tell what sort of generic resource adapter to use and information
    related to the specific database used. The <filename
    class="extension">jar</filename> file of the actual JDBC driver mut be
    copied in the right place to be seen by the JOnAS classloader : <filename
    class="directory">$JONAS_BASE/lib/ext.</filename></para>

    <para>Changing the configuration of the RA requires extracting and editing
    the deployment descriptor and updating the archive file. There are several
    possible ways to do this:</para>

    <itemizedlist>
      <listitem>
        <para>With the RAConfig command (refer to the <link
        xlink:href="command_guide.html">JOnAS Commands Reference Guide</link>
        for a complete description of the command).</para>
      </listitem>

      <listitem>
        <para>Through the jonasAdmin console (refer to Administration guide
        for a complete description). In the jonasAdmin's tree, the Resource
        Adapter Module node (under the deployment node) contains a configure
        tab that allows editing of both the ra.xml file and the jonas-ra.xml
        file of the undeployed RA.</para>
      </listitem>
    </itemizedlist>

    <section>
      <info>
        <title>Defining the JOnAS Connector Deployment Descriptor:
        jonas-ra.xml</title>
      </info>

      <para>The <filename>jonas-ra.xml</filename> contains JOnAS specific
      information describing deployment information, logging, pooling, jdbc
      connections, and RAR config property values:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Deployment Tags</emphasis>:</para>

          <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry align="center">property name</entry>

                  <entry align="center">description</entry>

                  <entry align="center">possible values</entry>
                </row>

                <row>
                  <entry>jndiname</entry>

                  <entry>name the RAR will be registered as. This property is
                  required. This value will be used in the
                  <property>resource-ref</property> section of an <xi:include
                  href="../variables.xml" xpointer="element(j2ee)" />
                  composant.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>Anyname (for example jdbc_1)</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>rarlink</entry>

                  <entry>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
                  <filename>META-INF/jonas-ra.xml</filename></entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>JONASJDBC_DM</para>
                      </listitem>

                      <listitem>
                        <para>JONASJDBC_DS</para>
                      </listitem>

                      <listitem>
                        <para>JONASJDBC_CP</para>
                      </listitem>

                      <listitem>
                        <para>JONASJDBC_XA</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>native-lib</entry>

                  <entry>defines the path where native libraries can be
                  found.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>Any string for a path</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>

        <listitem>
          <para><emphasis>Logging Tags</emphasis>:</para>

          <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry align="center">property name</entry>

                  <entry align="center">description</entry>

                  <entry>possible values</entry>
                </row>

                <row>
                  <entry>log-enabled</entry>

                  <entry>determines if logging should be enabled for the
                  RAR.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>False (default value)</para>
                      </listitem>

                      <listitem>
                        <para>True</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>log-topic:</entry>

                  <entry>defines the log topic that will be used to write log
                  messages for this rar file.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>Any topic name</para>
                      </listitem>

                      <listitem>
                        <para><property>Default value is
                        org.objectweb.jonas.jca</property></para>
                      </listitem>
                    </itemizedlist></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>

        <listitem>
          <para><emphasis>Pooling Tags</emphasis></para>

          <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry align="center">property name</entry>

                  <entry align="center">description</entry>

                  <entry align="center">possible values</entry>
                </row>

                <row>
                  <entry>pool-init</entry>

                  <entry>Initial size of the managed connection pool</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 (default value)</para>
                      </listitem>

                      <listitem>
                        <para>n</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-min</entry>

                  <entry>Minimum size of the managed connection pool.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 (default value)</para>
                      </listitem>

                      <listitem>
                        <para>n</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-max</entry>

                  <entry>Maximum size of the managed connection pool.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>n</para>
                      </listitem>

                      <listitem>
                        <para>-1 = unlimited (default value)</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-max-age-minutes</entry>

                  <entry>Maximum number of minutes to keep the managed
                  connection in the pool.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 = an unlimited amount of time.</para>
                      </listitem>

                      <listitem>
                        <para>n in minutes</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pstmt-max</entry>

                  <entry>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.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 = unlimited</para>
                      </listitem>

                      <listitem>
                        <para>n (default value = 10)</para>
                      </listitem>

                      <listitem>
                        <para>-1 = cache disabled</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pstmt-cache-policy</entry>

                  <entry>Prepared statement cache policy.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>List (default value) : array based implementation of the cache</para>
                      </listitem>

                      <listitem>
                        <para>Map : map based implementation of the cache</para>
                      </listitem>

                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-max-opentime</entry>

                  <entry>Identifies the maximum number of minutes that a
                  managed connection can be left busy.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 = an unlimited amount of time (default
                        value).</para>
                      </listitem>

                      <listitem>
                        <para>n in minutes</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-max-waiters:</entry>

                  <entry>identifies the maximum number of waiters for a
                  managed connection. Default value is 0.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 (default value)</para>
                      </listitem>

                      <listitem>
                        <para>n</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-max-waittime</entry>

                  <entry>identifies the maximum number of seconds that a
                  waiter will wait for a managed connection. Default value is
                  0.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 (default value)</para>
                      </listitem>

                      <listitem>
                        <para>n in seconds</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>pool-sampling-period:</entry>

                  <entry>identifies the number of seconds that will occur
                  between statistics samplings of the pool. Default is 30
                  seconds.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>n in seconds (default value = 30s)</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>

        <listitem>
          <para><emphasis>JDBC Connection Tags</emphasis>:<note>
              <para>Only valid for Connection implementation of
              java.sql.Connection.</para>
            </note></para>

          <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry align="center">property name</entry>

                  <entry align="center">description</entry>

                  <entry align="center">possible values</entry>
                </row>

                <row>
                  <entry>jdbc-check-level</entry>

                  <entry>Level of checking that will be done for the jdbc
                  connection.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>0 : no check (default value)</para>
                      </listitem>

                      <listitem>
                        <para>1: check connection still open</para>
                      </listitem>

                      <listitem>
                        <para>2 : send the test statement before reusing a
                        connection from the pool</para>
                      </listitem>

                      <listitem>
                        <para>3: (keep-alive feature) send the test statement
                        on each connection every pool-sampling-period</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>jdbc-test-statement</entry>

                  <entry>Test SQL statement sent on the connection if the
                  jdbc-check-level is greater than 1.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>A SQL statement</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>

        <listitem>
          <para><emphasis>Config Property Value Tags:</emphasis></para>

          <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. These tags differs dependiing
          on the generic JDBC RA used</para>

          <informaltable>
            <tgroup cols="3">
              <tbody>
                <row>
                  <entry align="center">property name</entry>

                  <entry align="center">description</entry>

                  <entry align="center">possible values</entry>
                </row>

                <row>
                  <entry>dsClass</entry>

                  <entry>Name of the class implementing
                  <classname>java.sql.Driver</classname>,
                  <classname>javax.sql.DataSource</classname>,
                  <classname>javax.sql.</classname><classname>ConnectionPoolDataSource</classname>,
                  or <classname>javax.sql.XADataSource</classname> interfaces
                  in the JDBC driver.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any classname representing a JDBC driver
                        (example:org.postgresql.Driver)</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>URL</entry>

                  <entry>Database url of the form
                  jdbc:&lt;database_vendor_subprotocol&gt;. This property may
                  be used only for JDBC RA that implements the Driver
                  (JDBC_DM)</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>Any url valid for a database provider
                        (example:jdbc:postgresql://localhost:5432/mydb)</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>user</entry>

                  <entry>Database user name</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any name</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>password:</entry>

                  <entry>Database password</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any string</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>loginTimeout</entry>

                  <entry>Maximum time in seconds that the driver will wait
                  while attempting to connect to a database.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>no value = 0 (default value)</para>
                      </listitem>

                      <listitem>
                        <para>n in seconds</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>isolationLevel</entry>

                  <entry>Level of transaction isolation</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>none</para>
                      </listitem>

                      <listitem>
                        <para>serializable</para>
                      </listitem>

                      <listitem>
                        <para>read_committed</para>
                      </listitem>

                      <listitem>
                        <para>read_uncommitted</para>
                      </listitem>

                      <listitem>
                        <para>repeatable_read</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>mapperName</entry>

                  <entry>Name of the JORM mapper</entry>

                  <entry>The possible values can be found in the <link
                  xlink:href="http://jorm.objectweb.org/doc/mappers.html">List
                  of available mappers in JORM documentation</link>.</entry>
                </row>

                <row>
                  <entry>databaseName</entry>

                  <entry>Name of the database</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any name</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>description:</entry>

                  <entry>Informal description</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any String</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>portNumber</entry>

                  <entry>Port Number of the database server</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>a number</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>serverName</entry>

                  <entry>Name of the database server.</entry>

                  <entry><itemizedlist>
                      <listitem>
                        <para>any name</para>
                      </listitem>
                    </itemizedlist></entry>
                </row>

                <row>
                  <entry>dbSpecificMethods</entry>

                  <entry>allow flexibility to call setter methods on the
                  <property>dsClass</property> as required by the database
                  provider</entry>

                  <entry>see below the particular syntax</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>

        <listitem>
          <para>dbSpecificMethods a specific property:</para>

          <para>The <xi:include href="../variables.xml"
          xpointer="element(appserver)" /> JDBC Resource Adapter is built as a
          generic connector to any database provider. The limitation of this
          is that each database provider may have different requirements about
          the methods needed to configure the <classname>dataSource
          </classname>class. This <property>dbSpecificMethods</property>
          property was added to allow flexibility to call setter methods on
          the <property>dsClass</property> as required by the database
          provider. The specific information about what additional methods
          should be used is documented by the database provider. The format of
          the value specified is:</para>

          <para>[:&lt;del_char&gt;]&lt;method&gt;=&lt;value&gt;::&lt;value_type&gt;:&lt;method&gt;=&lt;value&gt;::&lt;value_type&gt;....with:</para>

          <informaltable>
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry>:</entry>

                  <entry>optional starting value that denotes using the next
                  character as the delimiter instead of the default
                  ':'</entry>
                </row>

                <row>
                  <entry>&lt;del_char&gt;</entry>

                  <entry>delimiter character to use</entry>
                </row>

                <row>
                  <entry>&lt;method&gt;</entry>

                  <entry>method to call followed by an = sign</entry>
                </row>

                <row>
                  <entry>&lt;value&gt;</entry>

                  <entry>the parameter value to pass to the method being
                  called, followed by 2 delimiter characters.If a Properties
                  object is being passed, then the format of this value must
                  be (name=val, name=val, ...);</entry>
                </row>

                <row>
                  <entry>&lt;value_type&gt;</entry>

                  <entry><para>the parameter type used to construct the
                  reflection call, followed by the delimiter character if
                  additional methods are being called<itemizedlist>
                      <listitem>
                        <para>Boolean or bool</para>
                      </listitem>

                      <listitem>
                        <para>Byte or byte</para>
                      </listitem>

                      <listitem>
                        <para>Character or char</para>
                      </listitem>

                      <listitem>
                        <para>Double or double</para>
                      </listitem>

                      <listitem>
                        <para>Float or float</para>
                      </listitem>

                      <listitem>
                        <para>Integer or int</para>
                      </listitem>

                      <listitem>
                        <para>Long or long</para>
                      </listitem>

                      <listitem>
                        <para>Properties or java.util.Properties</para>
                      </listitem>

                      <listitem>
                        <para>Short or short</para>
                      </listitem>

                      <listitem>
                        <para>String</para>
                      </listitem>
                    </itemizedlist></para></entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </listitem>
      </itemizedlist>

      <para></para>

      <note>
        <para>If this <acronym>JDBC</acronym> resource is used as a
        persistence unit, the persistence configuration defined in the
        <filename>persistence.xml</filename> file must be coherent to this
        <filename>jonas-ra.xml</filename> description, such as the datasource
        name and the dialect.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Understanding pooling tags:</title>
      </info>

      <para>At JDBC RA deployment time, if <emphasis
      role="bold">pool-init</emphasis> is not null <emphasis
      role="bold">pool-init</emphasis> JDBC connection are created.</para>

      <para>When a user requests a jdbc connection, the JDBC RA first checks
      to see if a connection is already open for its transaction. If not, it
      tries to get a free connection from the free list. If there are no more
      connections available, it creates a new jdbc connection (if <emphasis
      role="bold">pool-max</emphasis> is not reached).</para>

      <para>If it cannot create new connections, the user must wait (if
      <emphasis role="bold">pool-max-waiters</emphasis> is not reached) until
      a connection is released. After a limited time (<emphasis
      role="bold">pool-max-waittime</emphasis>), the <function>getConnection
      </function>returns an exception.</para>

      <para>When the user calls <function>close()</function> on its
      connection, it is put back in the free list.</para>

      <para>Many statistics are computed (every <emphasis
      role="bold">pool-sampling-period </emphasis>seconds) and can be viewed
      by JonasAdmin. This is useful for tuning these parameters and for seeing
      the server load at any time</para>

      <para>When a connection has been open for a time too long (<emphasis
      role="bold">pool-max-age</emphasis>), the pool will try to release it
      from the freelist. However, the JDBC RA always tries to keep open at
      least the number of connections specified in <emphasis
      role="bold">pool-min</emphasis>.</para>

      <para>When the user has forgotten to close a jdbc connection, the system
      can automatically close it, after <emphasis
      role="bold">pool-max-opentime</emphasis> minutes. Note that if the user
      tries to use this connection later, thinking it is still open, it will
      return an exception (socket closed).</para>

      <para>When a connection is reused from the freelist, it is possible to
      verify that it is still valid. This is configured in <emphasis
      role="bold">jdbc-check-level</emphasis> . For levels &gt;1 it tries a
      dummy statement on the connection before returning it to the caller.
      This statement is configured in <emphasis
      role="bold">jdbc-test-statement</emphasis>.</para>

      <note>
        <para>this previous description is not only true for JDBC RAs but also
        for all types of resource adapters, except <emphasis
        role="bold">jdbc-check-level</emphasis> and <emphasis
        role="bold">jdbc-test-statement</emphasis> which are specifics for
        JDBC.</para>
      </note>
    </section>
  </section>

  <section>
    <info>
      <title>Examples of Specific JDBC Resource Adapter</title>
    </info>

    <para></para>

    <section>
      <info>
        <title>Oracle JDBC resource adapter (Driver)</title>
      </info>

      <para>An RAR for Oracle named as <literal>jdbc_1</literal> in JNDI and
      using the Oracle thin Driver JDBC driver, should be described in a file
      (called <filename>for example Oracle1_DM.rar)</filename>, with the
      following properties configured in the jonas-ra.xml file:</para>

      <para></para>

      <screen>&lt;?xml version = "1.0" encoding = "UTF-8"?&gt;
&lt;jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" &gt;
  &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
  &lt;rarlink&gt;JOnASJDBC_DM&lt;/rarlink&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;user&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;scott&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;password&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;tiger&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;loginTimeout&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&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:@malte:1521:ORA1&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;dsClass&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;oracle.jdbc.driver.OracleDriver&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;mapperName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;rdb.oracle&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
&lt;/jonas-connector&gt;
</screen>

      <para>In this example, "malte" is the hostname of the server running the
      database Oracle, 1521 is the SQL*Net V2 port number on this server, and
      ORA1 is the ORACLE_SID. This example makes use of the Oracle "Thin" JDBC
      driver. For an application server running on the same host as the Oracle
      DBMS, you can use the Oracle OCI JDBC driver.</para>
    </section>

    <section>
      <info>
        <title>PostgreSQL JDBC resource adapter (Driver)</title>
      </info>

      <para>To create a PostgreSQL RAR configured as jdbc_3 in JNDI, it should
      be described in a file (called for examplePostgreSQL3_DM.rar), with the
      following properties configured in the jonas-ra.xml file:</para>

      <screen>&lt;?xml version = "1.0" encoding = "UTF-8"?&gt;
&lt;jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" &gt;
  &lt;jndi-name&gt;jdbc_3&lt;/jndi-name&gt;
  &lt;rarlink&gt;JOnASJDBC_DM&lt;/rarlink&gt;
&lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;user&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;password&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;loginTimeout&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&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:postgresql:/malte:5432/db_jonas&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;dsClass&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;org.postgresql.Driver&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;mapperName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;rdb.postgres&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
&lt;/jonas-connector&gt;

</screen>

      <para></para>
    </section>

    <section>
      <info>
        <title>Oracle JDBC resource adapter (XADataSource)</title>
      </info>

      <para>An RAR for Oracle configured as jdbc_4 in JNDI and using the
      Oracle <classname>XADataSource</classname> interface of the JDBC driver
      thin in order to use a JDBC2-XA-compliant driver.It may be described in
      a file (called for example Oracle1_XA.rar), with the following
      properties configured in the jonas-ra.xml file:</para>

      <para><screen>&lt;?xml version = "1.0" encoding = "UTF-8"?&gt;
&lt;jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" &gt;
  &lt;jndi-name&gt;jdbc_4&lt;/jndi-name&gt;
  &lt;rarlink&gt;JOnASJDBC_XA&lt;/rarlink&gt;
   &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;user&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
   &lt;/jonas-config-property&gt;
   &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;password&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
   &lt;/jonas-config-property&gt;
   &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;databaseName&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;dbjonas&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;portNumber&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;1521&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;serverName&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;wallis&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;dbSpecificMethods&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;:#setDriverType=thin##String&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
    &lt;jonas-config-property&gt;
      &lt;jonas-config-property-name&gt;dsClass&lt;/jonas-config-property-name&gt;
      &lt;jonas-config-property-value&gt;oracle.jdbc.xa.client.OracleXADataSource&lt;/jonas-config-property-value&gt;
    &lt;/jonas-config-property&gt;
&lt;/jonas-connector&gt;</screen></para>
    </section>
  </section>

  <section>
    <info>
      <title>Tracing SQL Requests through P6Spy</title>
    </info>

    <para>The <link xlink:href="http://www.p6spy.com/">P6Spy</link> tool
    provides an easy way to trace the SQL requests sent to the
    database.</para>

    <para>To enable this tracing feature, perform the following configuration
    steps:</para>

    <itemizedlist>
      <listitem>
        <para>Install the p6spy.jar<footnote>
            <para>The <link xlink:href="http://www.p6spy.com/">P6Spy</link>
            tool was integrated into previous versions of <xi:include
            href="../variables.xml" xpointer="appserver" /> but now it must be
            explicitly downloaded from <link
            xlink:href="http://www.p6spy.com/download.html">
            here</link></para>
          </footnote> into $JONAS_BASE/lib/ext.</para>
      </listitem>

      <listitem>
        <para>Update the appropriate RAR file's
        <filename>jonas-ra.xml</filename> file by setting the
        <property>dsClass</property> property to
        <classname>com.p6spy.engine.spy.P6SpyDriver</classname></para>
      </listitem>

      <listitem>
        <para>Set the <property>realdriver </property>property in the
        <filename>spy.properties</filename> file (located in <filename
        class="directory">$JONAS_BASE/conf)</filename> to the jdbc driver of
        your actual database.</para>
      </listitem>

      <listitem>
        <para>Verify that logger.org.objectweb.jonas.jdbc.sql.level is set to
        DEBUG in $JONAS_BASE/conf/trace.properties.</para>

        <informalexample>
          <para>Example jonas-ra.xml content:</para>

          <screen>&lt;?xml version = "1.0" encoding = "UTF-8"?&gt;
&lt;jonas-connector xmlns="http://www.objectweb.org/jonas/ns"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.objectweb.org/jonas/ns
 http://www.objectweb.org/jonas/ns/jonas-connector_4_2.xsd" &gt;
  &lt;jndi-name&gt;jdbc_3&lt;/jndi-name&gt;
  &lt;rarlink&gt;JOnASJDBC_DM&lt;/rarlink&gt;
  &lt;native-lib&gt;&lt;/native-lib&gt;
  &lt;log-enabled&gt;true&lt;/log-enabled&gt;
  &lt;log-topic&gt;org.objectweb.jonas.jdbc.DMPostgres&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;10&lt;/pstmt-max&gt;
  &lt;/pool-params&gt;

 &lt;jdbc-conn-params&gt;
    &lt;jdbc-check-level&gt;0&lt;/jdbc-check-level&gt;
    &lt;jdbc-test-statement&gt;&lt;/jdbc-test-statement&gt;
  &lt;/jdbc-conn-params&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;user&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;password&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;jonas&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;loginTimeout&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&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:postgresql://your_host:port/your_db&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;dsClass&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;<classname>com.p6spy.engine.spy.P6SpyDriver</classname>&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;mapperName&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;rdb.postgres&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
  &lt;jonas-config-property&gt;
    &lt;jonas-config-property-name&gt;logTopic&lt;/jonas-config-property-name&gt;
    &lt;jonas-config-property-value&gt;org.objectweb.jonas.jdbc.DMPostgres&lt;/jonas-config-property-value&gt;
  &lt;/jonas-config-property&gt;
&lt;/jonas-connector&gt;</screen>

          <para>In <filename>$JONAS_BASE/conf/spy.properties</filename>
          file:</para>

          <screen>realdriver=org.postgresql.Driver</screen>

          <para>In
          <filename>$JONAS_BASE/conf/trace.properties</filename>:</para>

          <screen>logger.org.objectweb.jonas.jdbc.sql.level  DEBUG</screen>
        </informalexample>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>Migration from dbm service to the JDBC RA</title>
    </info>

    <para>The migration of a <filename>Database.properties</filename> file to
    a similar Resource Adapter can be accomplished through the execution of
    the following RAConfig tool command. Refer to the <link
    xlink:href="command_guide.html#commands.raconfig">JOnAS Commands Reference
    Guide</link> for a complete description of RAConfig command.</para>

    <screen>RAConfig -dm -p MySQL1 $JONAS_ROOT/rars/autoload/JOnAS_jdbcDM MySQL_dm</screen>

    <para>Generates a <filename>MySQL_dm.rar</filename> file linked to
    <filename>JOnAS_jdbcDM.rar</filename>, the <filename>jonas-ra.xml
    </filename>file inserted is created with values coming from the
    <filename>ra.xml</filename> file of the
    <filename>JOnAS_jdbcDM.rar</filename> and values from the
    <filename>MySQL1.properties</filename> file</para>

    <para>The j<filename>onas-ra.xml </filename>created by the previous
    command can be updated further, if desired. Once the additional properties
    have been configured, update the <filename>MySQL_dm.rar </filename>file
    using the following command:</para>

    <para><screen>RAConfig -path .  MySQL_dm.rar <co xml:id="raconfigextract" />

RAConfig -u jonas-ra.xml MySQL_dm.rar <co xml:id="raconfigupdate" /></screen><calloutlist>
        <callout arearefs="raconfigextract">
          <para>Extraction of <filename>jonas-ra.xml </filename>of
          <filename>MySQL_dm.rar</filename> in the working directory</para>
        </callout>

        <callout arearefs="raconfigupdate">
          <para>update <filename>MySQL_dm.rar</filename> with
          <filename>jonas-ra.xml</filename></para>
        </callout>
      </calloutlist></para>
  </section>
</section>
