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 for JBoss 5 is the HypersonicDB data source. Here’s the hsqldb-ds.xml that ships 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.
In order to be able to use a Datasource, you need to install a JDBC Driver. For JBoss AS 7/WildFly users check this tutorial: How to configure a Datasource with JBoss / WildFly . Of you are using JBoss AS 4/5 it’s enough to drop the JDBC Driver in the lib folder of the application server.
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.
Configuring your datasource to connect to Oracle RAC
Oracle RAC allows multiple computers to run the Oracle RDBMS software simultaneously while accessing a single database thus providing a clustered database.
In order to benefit from Oracle RAC features like fault tolerance and load balancing all you have to do is configuring the connection url with the list of Oracle hosts which belongs to the cluster.
In this example we are configuring our datasource to connect to a RAC made up of host1 and host2:
<connection-url>jdbc:oracle:thin:@(description=(address_list=(load_balance=on)(failover=on)(address=(protocol=tcp)(host=host1)(port=1521))(address=(protocol=tcp)(host=host2)(port=1521)))(connect_data=(service_name=xxxxsid)(failover_mode=(type=select)(method=basic)))) </connection-url>
Where to put Datasources if JBoss is clustered ?
If you are running a Cluster of JBoss AS 5 servers, position the file -ds.xml in the JBOSS_HOME\server\all\farm\ directory, it will be replicated on all members of the cluster.
Monitoring your Connection Pool (JBoss AS 5)
Datasource relevant MBeans
Each datasource translates into several MBeans that you can interact with in the JMX Console. All the datasource-related objects are in the jboss.jca domain. You can find them by searching through the JMX Console page, or by using jboss.jca:* as the query filter.
Supposing you want to monitor your OracleDS datasource from the previous example: you could use a more specific filter, such as jboss.jca:name=OracleDS,*, to see only the OracleDS entries. In either case, four MBeans will be related to the OracleDS datasource:
-
name=OracleDS ,service=DataSourceBinding
-
name=OracleDS ,service=LocalTxCM
-
name=OracleDS ,service=ManagedConnectionFactory
-
name=OracleDS ,service=ManagedConnectionPool
While each plays a critical role in providing the datasource functionality in JBoss, you are most likely to need to interact with the connection pool. Click the connection pool MBean to expose the management attributes and operations.
In our datasource file we’ve been using specified a minimum connection pool size of 2 and a maximum pool size of 10. You’ll see those values reflected in the MinSize and MaxSize attributes. You can change the values in the running server by adjusting the values and clicking Apply Changes.
Setting the values here affects the connection pool only in memory. To change the configuration permanently, update the datasource file. Try setting the pool sizes there. When you save the file, JBoss will redeploy the datasource and the new pool sizes will be displayed when you reload the page.
You might occasionally want to adjust the pool size to account for usage; you are more likely to be curious how much of the connection pool is being used. The ConnectionCount attribute shows how many connections are currently open to the database.
However, open connections are not necessarily in use by application code. The InUseConnectionCount attribute shows how many of the open connections are in use. Viewing the statistic from the other direction, AvailableConnectionCount shows how much room is left in the pool.
Finally, the MBean has several statistics that track connection pool usage over the pool’s lifetime. ConnectionCreatedCount and Connection-DestroyedCount keep running totals of the number of connections created and destroyed by the pool. If IdleTimeout is greater than 0, connections will eventually timeout, be destroyed, and be replaced by fresh connections. This will cause the created and destroyed counts to rise constantly. The MaxConnectionsInUseCount attribute keeps track of the highest number of connections in use at a time.
If you notice anything awkward in the connection pool, or you just want to reset the statistics, you can flush the connection pool using the flush operation on the MBean. This will cause a new connection pool to be created, abandoning the previous connection pool.
A Graph is worth 100 words
or so ! if you read our recent Recipes (and we really appreciate that you are a faithful visitor !) then you know that JBoss Web Console is able to show you graphically the value of many MBeans attribute (those who have a numeric value).
So look for the MBean “name=OracleDS ,service=ManagedConnectionPool”, there you can choose to add a graph to any of the attributes: in this picture you can see a sample graph of the JMX Attribute Connection Count
