Datasource configuration in JBoss?

A Datasource is a Java Naming and Directory Interface (JNDI) object used to obtain a connection from a connection pool to a database. In order to create a DataSource (so that you can use JDBC connectivity) you need to create a file ending with -ds.xml under the "deploy" directory of your server.

The default Datasource file

The default data source configured with JBoss 4.0 is the HypersonicDB data source.
Here's the hsqldb-ds.xml that is shipped with jboss :

<?xml version="1.0" encoding="UTF-8"?>

<datasources>
    <local-tx-datasource>

        <jndi-name>DefaultDS</jndi-name>

        <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}hypersonic${/}localDB
        </connection-url>

        <driver-class>org.hsqldb.jdbcDriver</driver-class>

        <user-name>sa</user-name>
        <password></password>

        <min-pool-size>5</min-pool-size>
        <max-pool-size>20</max-pool-size>

        <idle-timeout-minutes>0</idle-timeout-minutes>

        <track-statements />

        <security-domain>HsqlDbRealm</security-domain>

        <prepared-statement-cache-size>32</prepared-statement-cache-size>

        <metadata>
            <type-mapping>Hypersonic SQL</type-mapping>
        </metadata>

        <depends>jboss:service=Hypersonic,database=localDB</depends>

    </local-tx-datasource>

    <mbean code="org.jboss.jdbc.HypersonicDatabase" name="jboss:service=Hypersonic,database=localDB">
        <attribute name="Database">localDB</attribute>
        <attribute name="InProcessMode">true</attribute>
    </mbean>

</datasources>

As you can see from this file, JDBC connectivity uses Connection pools to dispatch Connections. The initial size and the max size of the Connection pool can be configured with <min-pool-size> and <max-pool-size>.

With <idle-timeout-minutes> you can indicate the maximum time a connection may be idle before being closed and returned to the pool. If not specified it's 15 minutes.

<track-statements/> is a debugging feature: it checks that all statements are closed when the connection is returned to the pool: remember to disable it in production environment.

 <security-domain> tells to use the security domain defined in conf/login-config.xml : in our case:

<application-policy name="HsqlDbRealm">
    <authentication>
        <login-module
            code="org.jboss.resource.security.ConfiguredIdentityLoginModule"
            flag="required">
            <module-option name="principal">sa</module-option>
            <module-option name="userName">sa</module-option>
            <module-option name="password"></module-option>
            <module-option name="managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=DefaultDS
            </module-option>
        </login-module>
    </authentication>
</application-policy>

<prepared-statement-cache-size> is the number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a LRU cache. The default is 0 (zero), meaning no cache.

Enterprise datasources

I) Local Datasource

This is a sample Oracle local datasource configuration: a local DataSource is one that does not support two phase commit using a java.sql.Driver.

<datasources>
    <local-tx-datasource>
        <jndi-name>OracleDS</jndi-name>
        <connection-url>jdbc:oracle:thin:@youroraclehost:1521:yoursid</connection-url>

        <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
        <user-name>x</user-name>
        <password>y</password>

        <min-pool-size>5</min-pool-size>
        <max-pool-size>100</max-pool-size>
        <query-timeout>60</query-timeout>
        <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
        </exception-sorter-class-name>

        <metadata>
            <type-mapping>Oracle9i</type-mapping>
        </metadata>
    </local-tx-datasource>

</datasources>




Notice the <query-timeout> tag which configures the maximum of seconds before a query times out ( avaliable since Jboss 4.0.3). The <exception-sorter-class-name> is used to Check the Oracle error codes and messages for fatal errors.

Remember: In order to use an Oracle datasource you need to put the jdbc driver in jBoss's server's lib directory.

II) XA Datasource

This is a sample XA Datasource: XA DataSources support two phase commit using a  javax.sql.XADataSource

<datasources>
    <xa-datasource>
        <jndi-name>XAOracleDS</jndi-name>
        <track-connection-by-tx></track-connection-by-tx>
        <isSameRM-override-value>false</isSameRM-override-value>
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource
        </xa-datasource-class>
        <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc
        </xa-datasource-property>
        <xa-datasource-property name="User">scott
        </xa-datasource-property>
        <xa-datasource-property name="Password">tiger
        </xa-datasource-property>

        <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
        </exception-sorter-class-name>

        <no-tx-separate-pools></no-tx-separate-pools>


        <metadata>
            <type-mapping>Oracle9i</type-mapping>
        </metadata>
    </xa-datasource>

    <mbean
        code="org.jboss.resource.adapter.jdbc.vendor.OracleXAExceptionFormatter"
        name="jboss.jca:service=OracleXAExceptionFormatter">
        <depends optional-attribute-name="TransactionManagerService">jboss:service=TransactionManager
        </depends>
    </mbean>

</datasources>

Notice the <isSameRM-override-value>  set to false to fix problems with Oracle. The element <track-connection-by-tx/>  can be omitted on JBoss 5 where it's enabled by default.
At last, the  <no-tx-separate-pools> means that Oracles XA datasource cannot reuse a connection outside a transaction once enlisted in a global transaction and vice-versa.