<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="config.jdbc" 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 DataSources with 'dbm' service</title>
  </info>

  <para>This section describes how to configure the Datasources for connecting
  application to databases when the <emphasis role="bold">dbm</emphasis>
  service is used.</para>

  <section>
    <info>
      <title>Configuring DataSources</title>
    </info>

    <para>For both container-managed or bean-managed persistence, <xi:include
    href="../../variables.xml" xpointer="appserver" /> makes use of relational
    storage systems through the JDBC interface. JDBC connections are obtained
    from an object, the <classname>DataSource</classname>, provided at the
    application server level. The <classname>DataSource</classname> interface
    is defined in the JDBC standard extensions.</para>

    <para>A <classname>DataSource</classname> object identifies a database and
    a means to access it via JDBC (a JDBC driver). An application server may
    request access to several databases and thus provide the corresponding
    <classname>DataSource</classname> objects that will be registered in JNDI
    registry.</para>

    <para>This section explains how <classname>DataSource</classname> objects
    can be defined and configured in the <xi:include
    href="../../variables.xml" xpointer="appserver" /> server.</para>

    <para><xi:include href="../../variables.xml" xpointer="appserver" />
    provides a generic driver-wrapper that emulates the
    <classname>XADataSource</classname> 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>Neither the EJB specification nor the <xi:include
    href="../../variables.xml" xpointer="j2ee" /> specification describe how
    to define <classname>DataSource</classname> objects so that they are
    available to a <xi:include href="../../variables.xml" xpointer="j2ee" />
    platform. Therefore, this document, which describes how to define and
    configure DataSource objects, is specific to <xi:include
    href="../../variables.xml" xpointer="appserver" />. However, the way to
    use these <classname>DataSource</classname> objects in the Application
    Component methods is standard, that is, by using 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> of the <link
    xlink:href="ejb2_programmer_guide.html#ejb2.entity">Developing Entity Bean
    Guide</link>).</para>

    <para>A <classname>DataSource </classname>object should be defined in a
    file called &lt;DataSource name&gt;.properties (for example
    Oracle1.properties for an Oracle DataSource or Postgres.properties for an
    PostgreSQL DataSource.These files must be located in <filename
    class="directory">$JONAS_BASE/conf</filename> directory.</para>

    <para>In the <filename>jonas.properties</filename> file, to define a
    DataSource "Oracle1.properties" add the name "Oracle1" to the line
    <property>onas.service.dbm.datasources</property>, as follows:</para>

    <para><screen>jonas.service.dbm.datasources Oracle1, Sybase, PostgreSQL</screen></para>

    <para>The property file defining a <classname>DataSource </classname>may
    contain two types of information:</para>

    <itemizedlist>
      <listitem>
        <para>connection properties</para>
      </listitem>

      <listitem>
        <para>JDBC Connection Pool properties</para>
      </listitem>
    </itemizedlist>

    <section>
      <info>
        <title>connection properties</title>
      </info>

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

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

              <row>
                <entry><property>datasource.name</property></entry>

                <entry>JNDI name of the DataSource</entry>
              </row>

              <row>
                <entry><property>datasource.url</property></entry>

                <entry>The JDBC database URL :
                jdbc:&lt;database_vendor_subprotocol&gt;:...</entry>
              </row>

              <row>
                <entry><property>datasource.classname</property></entry>

                <entry>Name of the class implementing the JDBC driver</entry>
              </row>

              <row>
                <entry><property>datasource.username</property></entry>

                <entry>Database user name</entry>
              </row>

              <row>
                <entry><property>datasource.password</property></entry>

                <entry>Database user password</entry>
              </row>

              <row>
                <entry><property>datasource.isolationLevel</property></entry>

                <entry><para>Database isolation level for transactions.
                Possible values are:</para> <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> <para>The default depends on the database
                used.</para></entry>
              </row>

              <row>
                <entry><property>datasource.mapper</property></entry>

                <entry>JORM database mapper (for possible values see <link
                xlink:href="http://jorm.objectweb.org/doc/mappers.html">here)</link></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable></para>

      <note>
        <para>If this datasource is used as a persistence unit, the
        persistence configuration defined in the
        <filename>persistence.xml</filename> file must be coherent to those
        properties, such as the datasource name and the dialect.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Connection Pool properties</title>
      </info>

      <para>Each <classname>Datasource</classname> is implemented as a
      connection manager and manages a pool of JDBC connections.</para>

      <para>The pool can be configured via some additional properties
      described in the following table.</para>

      <para>All these settings have default values and are not required. All
      these attributes can be reconfigured when <xi:include
      href="../../variables.xml" xpointer="appserver" /> is running, with the
      console JonasAdmin.</para>

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

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

              <entry align="center">Default value</entry>
            </row>

            <row>
              <entry><property>jdbc.connchecklevel</property></entry>

              <entry><para>JDBC connection checking level:
              </para><itemizedlist>
                  <listitem>
                    <para>0 : no check</para>
                  </listitem>

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

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

              <entry>1</entry>
            </row>

            <row>
              <entry><property>jdbc.connteststmt</property></entry>

              <entry>test statement in case jdbc.connchecklevel = 2.</entry>

              <entry>select 1</entry>
            </row>

            <row>
              <entry><property>jdbc.connmaxage</property></entry>

              <entry>nb of minutes a connection can be kept in the pool. After
              this time, the connection will be closed, if minconpool limit
              has not been reached.</entry>

              <entry>1440 mn (= 1 day)</entry>
            </row>

            <row>
              <entry><property>jdbc.maxopentime</property></entry>

              <entry>Maximum time (in mn) a connection can be left busy. If
              the caller has not issued a close() during this time, the
              connection will be closed automatically.</entry>

              <entry>1440 mn (= 1 day)</entry>
            </row>

            <row>
              <entry><property>jdbc.minconpool</property></entry>

              <entry>Minimum number of connections in the pool. Setting a
              positive value here ensures that the pool size will not go below
              this limit during the datasource lifetime.</entry>

              <entry>0</entry>
            </row>

            <row>
              <entry><property>jdbc.maxconpool</property></entry>

              <entry>Maximum number of connections in the pool. Limiting the
              max pool size avoids errors from the database.</entry>

              <entry>no limit</entry>
            </row>

            <row>
              <entry><property>jdbc.samplingperiod</property></entry>

              <entry>Sampling period for JDBC monitoring. nb of seconds
              between 2 measures.</entry>

              <entry>60 sec</entry>
            </row>

            <row>
              <entry><property>jdbc.maxwaittime</property></entry>

              <entry>Maximum time (in seconds) to wait for a connection in
              case of shortage. This is valid only if maxconpool has been
              set.</entry>

              <entry>10 sec</entry>
            </row>

            <row>
              <entry><property>jdbc.maxwaiters</property></entry>

              <entry>Maximum of concurrent waiters for a JDBC Connection. This
              is valid only if maxconpool has been set.</entry>

              <entry>1000</entry>
            </row>

            <row>
              <entry><property>jdbc.pstmtmax</property></entry>

              <entry>Maximum number of prepared statements cached in a
              Connection. Setting this to a bigger value (120 for example)
              will lead to better performance, but will use more memory. The
              recommendation is to set this value to the number of different
              queries that are used the most often. This is to be tuned by
              administrators.</entry>

              <entry>12</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>When a user requests a jdbc connection, the <emphasis
      role="bold">dbm </emphasis>connection manager 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, the <emphasis role="bold">dbm</emphasis> connection manager
      creates a new jdbc connection (if <property>jdbc.maxconpool
      </property>is not reached).</para>

      <para>If it cannot create new connections, the user must wait (if
      <property>jdbc.maxwaiters</property> is not reached) until a connection
      is released. After a limited time
      (<property>jdbc.maxwaittime</property>), 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
      <property>jdbc.samplingperiod</property> 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 too long a time
      (<property>jdbc.connmaxage</property>), the pool will try to release it
      from the freelist. However, the <emphasis role="bold">dbm</emphasis>
      connection manager always tries to keep open at least the number of
      connections specified in <property>jdbc.minconpool</property>.</para>

      <para>When the user has forgotten to close a jdbc connection, the system
      can automatically close it, after <property>jdbc.maxopentime</property>
      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
      <property>jdbc.connchecklevel</property>. The maximum level is to try a
      dummy statement on the connection before returning it to the caller.
      This statement is configured in
      <property>jdbc.connteststmt</property></para>
    </section>

    <section>
      <info>
        <title>DataSource example:</title>
      </info>

      <para>Here is the template for an Oracle dataSource.properties file that
      can be found in $JONAS_ROOT/conf:</para>

      <screen>
###################### Oracle DataSource configuration example
#


#####
#  DataSource configuration
#
datasource.name  jdbc_1
datasource.url  jdbc:oracle:thin:@&lt;your-hostname&gt;:1521:&lt;your-db&gt;
datasource.classname oracle.jdbc.driver.OracleDriver
datasource.username &lt;your-username&gt;
datasource.password &lt;user-password&gt;
datasource.mapper rdb.oracle


#####
#  ConnectionManager configuration
#

#  JDBC connection checking level.
#     0 = no special checking
#     1 = check physical connection is still open before reusing it
#     2 = try every connection before reusing it
jdbc.connchecklevel 0

#  Max age for jdbc connections
#  nb of minutes a connection can be kept in the pool
jdbc.connmaxage 1440

# Maximum time (in mn) a connection can be left busy.
# If the caller has not issued a close() during this time, the connection
# will be closed automatically.
jdbc.maxopentime 60

#  Test statement
jdbc.connteststmt select * from dual

# JDBC Connection Pool size.
# Limiting the max pool size avoids errors from database.
jdbc.minconpool 10
jdbc.maxconpool 30

# Sampling period for JDBC monitoring :
# nb of seconds between 2 measures.
jdbc.samplingperiod 30

# Maximum time (in seconds) to wait for a connection in case of shortage.
# This may occur only when maxconpool is reached.
jdbc.maxwaittime 5

# Maximum of concurrent waiters for a JDBC Connection
# This may occur only when maxconpool is reached.
jdbc.maxwaiters 100
       </screen>
    </section>
  </section>
</section>
