Note: Documentation for Pivotal GemFire 7.0.x is now available at http://gemfire.docs.pivotal.io/index.html. Please refer to the Pivotal site for the latest and most up-to-date documentation on GemFire 7.0.x. The vFabric GemFire 7.0 documentation site will no longer be updated.

Configuring Database Connections Using JNDI

When using JTA transactions, you can configure database JNDI data sources in cache.xml. The DataSource object points to either a JDBC connection or, more commonly, a JDBC connection pool. The connection pool is usually preferred, because a program can use and reuse a connection as long as necessary and then free it for another thread to use.

The following are a list of Datasource connection types.
  • XAPooledDataSource. Pooled SQL connections.
  • ManagedDataSource. JNDI binding type for the J2EE Connector Architecture (J2CA). ManagedConnectionFactory. For information on the ManagedConnection interface, see: http://docs.oracle.com/javaee/6/api/javax/resource/spi/ManagedConnection.html.
  • PooledDataSource. Pooled SQL connections.
  • SimpleDataSource. Single SQL connection. No pooling of SQL connections is done. Connections are generated on the fly and cannot be reused.

The jndi-name attribute of the jndi-binding element is the key binding parameter. If the value of jndi-name is a DataSource, it is bound as java:/myDatabase, where myDatabase is the name you assign to your data source. If the data source cannot be bound to JNDI at runtime, GemFire logs a warning. For information on the DataSource interface, see: http://docs.oracle.com/javase/6/docs/api/javax/sql/DataSource.html

GemFire supports JDBC 2.0 and 3.0.

Note: Include any data source jar files in your CLASSPATH.

Example DataSource Configurations in cache.xml

The following sections show example cache.xml files configured for each of the DataSource connection types.

JNDI-Binding Properties Configuration Example

You specify the JNDI binding properties through the config-property tag, as shown in this example. To find what other properties you need to set, see the vendor documentation for your database. You can add as many config-property tags as required.
   <jndi-binding . . .
      <config-property>
       	<config-property-name>databaseName</config-property-name>
        <config-property-type>java.lang.String</config-property-type>
        <config-property-value>newDB</config-property-value>
      </config-property>
   </jndi-binding>
      

XAPooledDataSource Connection Example

The example shows a cache.xml file configured for a pool of XAPooledDataSource connections connected to the data resource newDB. The log-in and blocking timeouts are set lower than the defaults. The connection information, including user-name and password, is set in the cache.xml file, instead of waiting until connection time. The password is encrypted; for details, see Encrypting Passwords for Use in cache.xml.

<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC
"-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN" 
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache lock-lease="120" lock-timeout="60" search-timeout="300"> 
   <region name="root">
      <region-attributes scope="distributed-no-ack"	data-policy="cached" initial-capacity="16"
load-factor="0.75" concurrency-level="16" statistics-enabled="true">
	     . . .
   </region>
   <jndi-bindings>
      <jndi-binding type="XAPooledDataSource" jndi-name="newDB2trans" init-pool-size="20" 
max-pool-size="100" idle-timeout-seconds="20" blocking-timeout-seconds="5" 
login-timeout-seconds="10" xa-datasource-class="org.apache.derby.jdbc.EmbeddedXADataSource"
user-name="mitul" password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)">
       <config-property>
         <config-property-name>description</config-property-name>
         <config-property-type>java.lang.String</config-property-type>
         <config-property-value>pooled_transact</config-property-value>
       </config-property>
       <config-property>
         <config-property-name>databaseName</config-property-name>
         <config-property-type>java.lang.String</config-property-type>
         <config-property-value>newDB</config-property-value>
       </config-property>	 
       <config-property>
         <config-property-name>vendor_specific_property1</config-property-name>
         <config-property-type>type</config-property-type>
         <config-property-value>value</config-property-value>
       </config-property>				 
       . . .
      </jndi-binding>
	 </jndi-bindings>
</cache>

ManagedDataSource Connection Example

ManagedDataSource connections for the J2CA ManagedConnectionFactory are configured as shown in the example. This configuration is similar to XAPooledDataSource connections, except the type is ManagedDataSource, and you specify a managed-conn-factory-class instead of an xa-datasource-class.

<?xml version="1.0"?>
 <!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN" 
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache lock-lease="120" lock-timeout="60" search-timeout="300">
   <region name="root">
      <region-attributes scope="distributed-no-ack" data-policy="cached" initial-capacity="16"
load-factor="0.75" concurrency-level="16" statistics-enabled="true">
      . . .
     	</region>
      <jndi-bindings>
         <jndi-binding type="ManagedDataSource" jndi-name="DB3managed" 
init-pool-size="20" max-pool-size="100" idle-timeout-seconds="20" 
blocking-timeout-seconds="5" login-timeout-seconds="10"
managed-conn-factory-class="com.myvendor.connection.ConnFactory" user-name="mitul"  
password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)">
             <config-property>
                 <config-property-name>description</config-property-name>
                 <config-property-type>java.lang.String</config-property-type>
                 <config-property-value>pooled_transact</config-property-value>
             </config-property>
             <config-property>
                 <config-property-name>databaseName</config-property-name> 
                 <config-property-type>java.lang.String</config-property-type>
                 <config-property-value>newDB</config-property-value>
             </config-property>	
             <config-property>
                 <config-property-name>vendor_specific_property1</config-property-name>
                 <config-property-type>type</config-property-type>
            	    <config-property-value>value</config-property-value>
             </config-property>				 
             	. . .
          </jndi-binding>
      </jndi-bindings>
 </cache>
      

PooledDataSource and SimpleDataSource Example

Use the PooledDataSource and SimpleDataSource connections for operations executed outside of any transaction. This example shows a cache.xml file configured for a pool of PooledDataSource connections to the data resource newDB. For this non-transactional connection pool, the log-in and blocking timeouts are set higher than for the transactional connection pools in the two previous examples. The connection information, including user-name and password, is set in the cache.xml file, instead of waiting until connection time. The password is encrypted; for details, see Encrypting Passwords for Use in cache.xml.

<?xml version="1.0"?>
 <!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN" 
"http://www.gemstone.com/dtd/cache7_0.dtd">
    <cache lock-lease="120" lock-timeout="60" search-timeout="300">
       <region name="root">
         <region-attributes scope="distributed-no-ack" data-policy="cached" 
initial-capacity="16" load-factor="0.75" concurrency-level="16" statistics-enabled="true">
         	. . .
       </region>
       <jndi-bindings>
          <jndi-binding	type="PooledDataSource" jndi-name="newDB1" init-pool-size="2" 
max-pool-size="7" idle-timeout-seconds="20" blocking-timeout-seconds="20" 
login-timeout-seconds="30" 
conn-pooled-datasource-class="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource"
user-name="mitul"	password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)">
             <config-property>
                 <config-property-name>description</config-property-name>
                 <config-property-type>java.lang.String</config-property-type>
                 <config-property-value>pooled_nontransact</config-property-value>	
            	</config-property>
            	<config-property>
                 <config-property-name>databaseName</config-property-name>
                 <config-property-type>java.lang.String</config-property-type>
                 <config-property-value>newDB</config-property-value>
            	</config-property>				 
             <config-property>
                 <config-property-name>vendor_specific_property1</config-property-name>
        				     <config-property-type>value</config-property-type>
                 <config-property-value>value</config-property-value>
             </config-property>				 
              . . .
         </jndi-binding>
   	   </jndi-bindings>
</cache>
      

SimpleDataSource Connection Example

The example below shows a very basic configuration in the cache.xml file for a SimpleDataSource connection to the data resource oldDB. You only need to configure a few properties like a jndi-name for this connection pool, oldDB1, and the databaseName, oldDB. This password is in clear text.

A simple data source connection does not generally require vendor-specific property settings. If you need them, add config-property tags as shown in the earlier examples.

<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN" 
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache lock-lease="120" lock-timeout="60" search-timeout="300">
   <region name="root">
      <region-attributes scope="distributed-no-ack" data-policy="cached" initial-capacity="16"
load-factor="0.75" concurrency-level="16" statistics-enabled="true">
      	. . .
      </region-attributes>   
 	 </region>
   <jndi-bindings>
      	<jndi-binding	type="SimpleDataSource" jndi-name="oldDB1" 
jdbc-driver-class="org.apache.derby.jdbc.EmbeddedDriver" user-name="mitul" 
password="password" connection-url="jdbc:derby:newDB;create=true">
        . . .
       </jndi-binding>
   </jndi-bindings>
</cache>