<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="Kernel.DataSourceProvider">
  <title>The data source provider</title>

    <para>The <emphasis>DataSourceProvider</emphasis> is a service used to
    give access to a data source in an uniform manner in order to be able to
    support data sources that are managed by the application server.</para>

      <table>
        <title>List methods</title>

        <tgroup cols="2">
          <tbody>
            <row>
              <entry>getDataSource(String dataSourceName)</entry>

              <entry>Tries to get the data source from a JNDI lookup. If it
              can be found and the data source is defined as managed, the
              service will wrap the original <emphasis>DataSource</emphasis>
              instance in a new <emphasis>DataSource</emphasis> instance that
              is aware of its <emphasis>managed</emphasis> state otherwise it
              will return the original <emphasis>DataSource</emphasis>
              instance.</entry>
            </row>

            <row>
              <entry>isManaged(String dataSourceName)</entry>

              <entry>Indicates whether or not the given data source is
              managed.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

  <section id="Kernel.DataSourceProvider.Configuration">
    <title>Configuration</title>

    <para>The configuration of the <emphasis>DataSourceProvider</emphasis>
    should be defined only if you use managed data sources since by default
    all the data sources are considered as not managed. See below the default
    configuration</para>

    <programlisting>&lt;configuration&gt;
....  
   &lt;component&gt;
      &lt;key&gt;org.exoplatform.services.jdbc.DataSourceProvider&lt;/key&gt;
      &lt;type&gt;org.exoplatform.services.jdbc.impl.DataSourceProviderImpl&lt;/type&gt;
      &lt;init-params&gt;
         &lt;!--  Indicates that the data source needs to check if a tx is active
              to decide if the provided connection needs to be managed or not.
              If it is set to false, the data source will provide only
              managed connections if the data source itself is managed.  --&gt;
         &lt;!--value-param&gt;
            &lt;name&gt;check-tx-active&lt;/name&gt;
            &lt;value&gt;true&lt;/value&gt;
         &lt;/value-param--&gt;
         &lt;!-- Indicates that all the data sources are managed 
              If set to true the parameter never-managed and 
              managed-data-sources will be ignored --&gt;
         &lt;!--value-param&gt;
            &lt;name&gt;always-managed&lt;/name&gt;
            &lt;value&gt;true&lt;/value&gt;
         &lt;/value-param--&gt;
         &lt;!-- Indicates the list of all the data sources that are 
              managed, each value tag can contain a list of
              data source names separated by a comma, in the
              example below we will register ds-foo1, ds-foo2 
              and ds-foo3 as managed data source. If always-managed
              and/or never-managed is set true this parameter is ignored --&gt;
         &lt;!--values-param&gt;
            &lt;name&gt;managed-data-sources&lt;/name&gt;
            &lt;value&gt;ds-foo1, ds-foo2&lt;/value&gt;
            &lt;value&gt;ds-foo3&lt;/value&gt;
         &lt;/values-param--&gt;
      &lt;/init-params&gt;
   &lt;/component&gt;  
...
&lt;/configuration&gt;</programlisting>

    <table>
      <title>Fields description</title>

      <tgroup cols="2">
        <tbody>
          <row>
            <entry><emphasis>check-tx-active</emphasis></entry>

            <entry>This parameter indicates that the data source needs to
            check if a transaction is active to decide if the provided
            connection needs to be managed or not. If it is set to
            <emphasis>false</emphasis>, the data source will provide only
            managed connections if the data source itself is managed. By
            default, this parameter is set to <emphasis>true</emphasis>. If
            this parameter is set to <emphasis>true</emphasis>, it will need
            the <emphasis>TransactionService</emphasis> to work propertly, so
            please ensure that the <emphasis>TransactionService</emphasis> is
            defined in your configuration.</entry>
          </row>

          <row>
            <entry><emphasis>always-managed</emphasis></entry>

            <entry>This parameter indicates that all the data sources are
            managed. If set to <emphasis>true</emphasis> the parameter
            <emphasis>never-managed</emphasis> and
            <emphasis>managed-data-sources</emphasis> will be ignored, so it
            will consider all the data sources as managed. By default, this
            parameter is set to <emphasis>false</emphasis>.</entry>
          </row>

          <row>
            <entry><emphasis>managed-data-sources</emphasis></entry>

            <entry>This parameter indicates the list of all the data sources
            that are managed, each value tag can contain a list of data source
            names separated by a comma. If <emphasis>always-managed</emphasis>
            and/or <emphasis>never-managed</emphasis> is set
            <emphasis>true</emphasis> this parameter is ignored.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>
</section>
