ConfigDataSources

DataSource configuration

Link to original documentation: http://docs.jboss.org/jbossas/jboss4guide/r2/html/ch7.chapt.htmlch7.jcads.fig

 

 

DataSources are defined inside a element.

 

  • <no-tx-datasource> - a DataSource that does not take part in JTA transactions using a java.sql.Driver

  • <local-tx-datasource> - a DataSource that does not support two phase commit using a java.sql.Driver

  • <xa-tx-datasource> - a DataSource that does support two phase commit using a javax.sql.XADataSource

 

Parameters specific for java.sql.Driver usage

 

  • <connection-url> - the JDBC driver connection url string

  • <driver-class> - the JDBC driver class implementing java.sql.Driver

  • <connection-property> - used to configure the connections retrieved from the java.sql.Driver, e.g.

   <connection-property name="char.encoding">UTF-8</connection-property>

 

Parameters specific for javax.sql.XADataSource usage

 

  • <xa-datasource-class> - the class implementing the XADataSource

  • <xa-datasource-property> - properties used to configure the XADataSource e.g.

    <xa-datasource-property name="IfxWAITTIME">10</xa-datasource-property>
    <xa-datasource-property name="IfxIFXHOST">myhost.mydomain.com</xa-datasource-property>
    <xa-datasource-property name="PortNumber">1557</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mydb</xa-datasource-property>
    <xa-datasource-property name="ServerName">myserver</xa-datasource-property>
  • <isSameRM-override-value> - set to false to fix problems with Oracle

  • <track-connection-by-tx/> - set to fix problems with Oracle

  • <no-tx-separate-pools/> - set to fix problems with Oracle

 

Common DataSource parameters

 

  • <jndi-name> - the JNDI name under which the DataSource should be bound.

  • <use-java-context> - A boolean indicating if the jndi-name should be prefixed with java: which causes the DataSource to only be accessible from within the jboss server vm. The default is true.

  • <user-name> - the user name used when creating the connection (not used when security is configured)

  • <password> - the password used when creating the connection (not used when security is configured)

  • <transaction-isolation> - the default transaction isolation of the connection (unspecified means use the default provided by the database):

    • TRANSACTION_READ_UNCOMMITTED

    • TRANSACTION_READ_COMMITTED

    • TRANSACTION_REPEATABLE_READ

    • TRANSACTION_SERIALIZABLE

    • TRANSACTION_NONE

 

  • <new-connection-sql> - an sql statement that is executed against each new connection. This can be used to set the connection schema, etc.

  • <check-valid-connection-sql> - an sql statement that is executed before it is checked out from the pool to make sure it is still valid. If the sql fails, the connection is closed and new ones created.

  • <valid-connection-checker-class-name> - a class that can check whether a connection is valid using a vendor specific mechanism

  • <exception-sorter-class-name> - a class that looks at vendor specific message to determine whether sql errors are fatal

  • <track-statements> - (a) whether to monitor for unclosed Statements and ResultSets and issue warnings when the user forgets to close them (default false)

  • <prepared-statement-cache-size> - 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.

  • <share-prepared-statements> - (b) with prepared statement cache enabled whether two requests in the same transaction should return the same statement (from jboss-4.0.2 - default false).

  • <set-tx-query-timeout> - whether to enable query timeout based on the length of time remaining until the transaction times out (default false - NOTE: This was ported to 4.0.x until 4.0.3)

  • <query-timeout> - a static configuration of the maximum of seconds before a query times out (since 4.0.3)

  • <metadata/typemapping> - a pointer to the type mapping in conf/standardjbosscmp.xml (from JBoss4)

 

(a) From 3.2.6 track-statements has a new option

<track-statements>nowarn</track-statements

which closes Statements and ResultSets without a warning. It is also the new default value.

 

 

(b) The purpose is to workaround questionable driver behavior where the driver applies auto-commit semantics to local transactions.

   Connection c = dataSource.getConnection(); // auto-commit == false
   PreparedStatement ps1 = c.prepareStatement(...);
   ResultSet rs1 = ps1.executeQuery();
   PreparedStatement ps2 = c.prepareStatement(...);
   ResultSet rs2 = ps2.executeQuery();

Assuming the prepared statements are the same. For some drivers, ps2.executeQuery() will automatically close rs1 so we actually need two real prepared statements behind the scenes. This should only be for the auto-commit semantic where re-running the query starts a new transaction automatically. For drivers that follow the spec, you can set it to true to share the same real prepared statement.

 

 

Set up upecific DataSources

 

 

Generic Datasource Sample

 

<datasources>
  <local-tx-datasource>
    <jndi-name>GenericDS</jndi-name>
    <connection-url>[jdbc: url for use with Driver class]</connection-url>
    <driver-class>[fully qualified class name of java.sql.Driver implementation]</driver-class>
    <user-name>x</user-name>
    <password>y</password>
    <!-- you can include connection properties that will get passed in 
     the DriverManager.getConnection(props) call-->
    <!-- look at your Driver docs to see what these might be -->
    <connection-property name="char.encoding">UTF-8</connection-property>
    <transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>

    <!--pooling parameters-->
    <min-pool-size>5</min-pool-size>
    <max-pool-size>100</max-pool-size>
    <blocking-timeout-millis>5000</blocking-timeout-millis>
    <idle-timeout-minutes>15</idle-timeout-minutes>
    <!-- sql to call when connection is created
    <new-connection-sql>some arbitrary sql</new-connection-sql>
    -->

    <!-- sql to call on an existing pooled connection when it is obtained from pool 
    <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
    -->

    <set-tx-query-timeout></set-tx-query-timeout>
    <query-timeout>300</query-timeout> <!-- maximum of 5 minutes for queries -->

    <!-- pooling criteria.  USE AT MOST ONE-->
    <!--  If you don't use JAAS login modules or explicit login 
     getConnection(usr,pw) but rely on user/pw specified above, 
     don't specify anything here -->

    <!-- If you supply the usr/pw from a JAAS login module -->
    <security-domain>MyRealm</security-domain>

    <!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
    <application-managed-security></application-managed-security>

    <!--Anonymous depends elements are copied verbatim into the ConnectionManager mbean config-->
    <depends>myapp.service:service=DoSomethingService</depends>

  </local-tx-datasource>

  <!-- you can include regular mbean configurations like this one -->
  <mbean code="org.jboss.tm.XidFactory" 
      name="jboss:service=XidFactory">
    <attribute name="Pad">true</attribute>
  </mbean>


  <!-- Here's an xa example -->
  <xa-datasource>
    <jndi-name>GenericXADS</jndi-name>
    <xa-datasource-class>[fully qualified name of class implementing javax.sql.XADataSource goes here]</xa-datasource-class>
    <xa-datasource-property name="SomeProperty">SomePropertyValue</xa-datasource-property>
    <xa-datasource-property name="SomeOtherProperty">SomeOtherValue</xa-datasource-property>

    <user-name>x</user-name>
    <password>y</password>
    <transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>



    <!--pooling parameters-->
    <min-pool-size>5</min-pool-size>
    <max-pool-size>100</max-pool-size>
    <blocking-timeout-millis>5000</blocking-timeout-millis>
    <idle-timeout-minutes>15</idle-timeout-minutes>
        <!-- sql to call when connection is created
        <new-connection-sql>some arbitrary sql</new-connection-sql>
        -->

        <!-- sql to call on an existing pooled connection when it is obtained from pool 
        <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
        -->


    <!-- pooling criteria.  USE AT MOST ONE-->
    <!--  If you don't use JAAS login modules or explicit login 
     getConnection(usr,pw) but rely on user/pw specified above, 
     don't specify anything here -->

    <!-- If you supply the usr/pw from a JAAS login module -->
    <security-domain></security-domain>

    <!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
    <application-managed-security></application-managed-security>

  </xa-datasource>

</datasources>

 

Configuring a DataSource for remote usage

As of jboss-4.0.0 there is support for accessing a DataSource from a remote client. The one change that is neccessary for the client to be able to lookup the DataSource from jndi is to specify use-java-context=false as shown here:

 

<datasources>
  <local-tx-datasource>
    <jndi-name>GenericDS</jndi-name>
    <use-java-context>false</use-java-context>
    <connection-url>...</connection-url>
...

 

This results in the DataSource being bound under the jndi name "GenericDS" instead of the default of "java:/GenericDS" which restricts the lookup to the same vm as the jboss server.