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

  <para>The <emphasis role="bold">dbm</emphasis> service (database manager
  service) allow access to one or more relational databases. It will create
  and use <classname>DataSource</classname> objects. Such a DataSource object
  must be configured according to the database that will be used for the
  persistence of a bean.</para>

  <para><caution>
      <para>the recommended way to access to databases is to use the <emphasis
      role="bold">resource</emphasis> service deploying JDBC resource
      adapter</para>
    </caution></para>

  <para>The <emphasis role="bold">dbm</emphasis> service 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. When it is necessary to use a JDBC2-XA-compliant
  driver access to the databases must be done via a JDBC resource adapter XA
  compliant (more information can be found in <xref
  linkend="config.ra" /></para>

  <para>Here is the part of <filename>jonas.properties</filename> related to
  <emphasis role="bold">dbm</emphasis> service:</para>

  <screen>###################### JOnAS DBM Database service configuration
#
#  Set the name of the implementation class of the dbm service
jonas.service.dbm.class    org.ow2.jonas.dbm.internal.JOnASDataBaseManagerService

#  Set the jonas DataSources. This enables the JOnAS server to load
#  the data dources, to load related jdbc drivers, and to register the data
#  sources into JNDI.
#  This property is set with a coma-separated list of Datasource properties
#  file names (without the '.properties' suffix).
#  Ex: Oracle1,InstantDB1 (while the Datasources properties file names are
#                          Oracle1.properties and InstantDB1.properties)
jonas.service.dbm.datasources    HSQL1</screen>

  <para>For the <emphasis role="bold">dbm</emphasis> service it is possible
  to:</para>

  <itemizedlist>
    <listitem>
      <para>set a list of datasource names via property
      <property>jonas.service.dbm.datasources</property>.</para>

      <para>for each name XX appearing in this list a
      <filename>XX.properties</filename> file must exist in <filename
      class="directory">$JONAS_BASE/conf</filename></para>
    </listitem>
  </itemizedlist>

  <para>Access to a particular database via <emphasis
  role="bold">dbm</emphasis> service is configured in datasource.properties
  files that must be located in <filename
  class="directory">$JONAS_BASE/conf.</filename></para>

  <section>
    <info>
      <title>Datasource.properties files</title>
    </info>

    <para>In the <xi:include href="../../variables.xml"
    xpointer="appserver" /> distribution several templates of
    datasource.properties files are provided one for
    <database>Oracle</database>, <database>PostgreSQL,</database>
    <database>Sybase</database>, <database>DB2</database>,
    <database>MySQL</database>, <database>HSQLDB,</database>
    <database>InterBase</database>, <database>FirebirdSQL</database>,
    <database>Mckoi SQL,</database> <database>InstantDB</database> )
    respectively in <emphasis>Oracle1.properties</emphasis>,
    <emphasis>PostgreSQL1.properties</emphasis> etc...</para>

    <para>A complete description of the datasource.properies file can be found
    in<xref linkend="config.jdbc" /></para>
  </section>
</section>
