DataSource Configuration

This section covers how to configure datasources and JDBC drivers in Fabric3.

DataSources can either be runtime- or application-scoped. Runtime-scoped DataSources are defined as part of the runtime system configuration and remain for the duration of the runtime instance. Application-scoped DataSources are defined as part of a composite and are activated when the composite is deployed and de-activated when it is undeployed.

Runtime DataSource Configuration

To configure runtime data sources, include the appropriate JDBC drivers in the runtime extensions/datasource directory, creating it if needed. Next, you will need to update the runtime systemConfig.xml, adding a <datasource> entry. The following demonstrates how to configure a connection pool using the non-XA MySQL driver:

<datasources>
   <datasource name="LoanApplicationDS" driver="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/bigbank" username="bigbank" password="bigbank">
      <minPoolSize>5</minPoolSize>
      <maxPoolSize>10</maxPoolSize>
   </datasource>
</datasources>

The following sub-elements can be set under the <datasource> element:

  • type - the data source type: either "non_xa" (default) or "xa"
  • aliases - a comma-separated list of aliases which the datasource can be referenced by
  • minPoolSize - the minimum number of connections to keep active in the connection pool
  • maxPoolSize - the maximum number of connections to create in the connection pool
  • poolSize - used to set the minimum and maximum pool size to a single value
  • connectionTimeout -t he maximum amount of time in seconds the pool will block waiting for a connection to become available in the pool when it is empty
  • loginTimeout – the maximum time in seconds that the data source will wait while attempting to connect to a database.
  • maintenanceInterval – the time in seconds between maintenance periods
  • maxIdle - the time in seconds before a pooled connection can be reclaimed
  • reap - the time in seconds the connection pool will allow a connection to be borrowed before claiming it back
  • query - the datasource test query

If a data source is an XA datasource, driver-specific properties can be configured by using sub-elements of <datasource> in the format:
<property_name>property_value</property_name>

Application DataSource Configuration

Application data sources can be configured in a composite using the Fabric3 <datasources> element, as shown in the following:

<composite xmlns:f3="urn:fabric3.org"..>
   <f3:datasources>
      <datasource name="MessageDS" driver="org.h2.jdbcx.JdbcDataSource" type="xa">
         <URL>jdbc:h2:mem:MessageDS;DB_CLOSE_DELAY=-1</URL>
         <minPoolSize>5</minPoolSize>
         <maxPoolSize>10</maxPoolSize>
      </datasource>
   </f3:datasources>
</composite>

The data source will be activated when the composite is deployed and removed when the composite is undeployed. The same sub-elements as used in runtime data source configuration can be used.

Note that it is sometimes useful to configure a datasource so that it can be referenced with multiple aliases. For example, an application may contain multiple JPA persistence units which refer to individual datasources. As an optimization, a single datasource can be configured for all of the individual datasource references, allowing JPA/Hibernate operations to be performed using a single XA transactional resource. The following is an example of how to configure a datasource with aliases:

<composite xmlns:f3-other="urn:fabric3.org"..>
   <f3-other:datasources>
      <datasource name="MessageDS" aliases="MessageDSAlias1,MessageDSAlias2" driver="org.h2.jdbcx.JdbcDataSource" type="xa">
         <URL>jdbc:h2:mem:MessageDS;DB_CLOSE_DELAY=-1</URL>
         <minPoolSize>5</minPoolSize>
         <maxPoolSize>10</maxPoolSize>
      </datasource>
   </f3-other:datasources>
</composite>

Managing DataSources

DataSource properties and statistics are available via the Management Resource Framework and JMX. See Management for details.

Enabling DataSources

The DataSource extension is included with all transactional extensions, including JPA/Hibernate and JMS.