Page 1 of 2
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.
