DataSource versus Driver Connections

NuoDB supplies a DataSource class that encompasses the DriverManager#getConnection() method. The advantage of using the DataSource class is that it hides many complexities associated with managing NuoDB connections, such as dealing with NuoDB broker redundancy and reconnecting to the NuoDB database if a transaction process terminates. The DataSource class can be used for connection pooling (on by default) and/or statement caching (off by default). Internally, the DataSource class maintains a pool of connections for you and ensures that each thread in a multi-threaded application gets its own connection. This is very important due to the distributed nature of the NuoDB architecture.

The following code shows how to use the DataSource class outside of an application server that is running the NuoDB JDBC driver:

Properties p = new Properties();
p.setProperty(DataSource.PROP_URL, "jdbc:com.nuodb://localhost/database");
p.setProperty(DataSource.PROP_USERNAME, "user");
p.setProperty(DataSource.PROP_PASSWORD, "password");
DataSource ds = new DataSource(p);
con = ds.getConnection();
....

The DataSource class takes a Properties object specifying properties for the pool in general and connection properties for the connections in the pool. The following connection properties are supported:

Property Description Default
username The connection username to be passed to the NuoDB JDBC driver to establish a connection, unless DataSource#getConnection(username,password) is used.  
password The connection password to be passed to the JDBC driver to establish a connection, unless DataSource#getConnection(username,password) is used.  
defaultSchema The default schema of connections created by this pool.  
defaultReadOnly The default read-only state of connections created by this pool. If not set, then readOnly is determined by the Protocol.IsReadOnly which retireves the default value of false from the server.  
defaultAutoCommit The default auto-commit state of connections created by this pool. If not set, the default is the NuoDB JDBC driver default (If not set, then the setAutoCommit() method will not be called.)  
initialSize The initial number of connections that are created when the pool is started. 10
maxActive The maximum number of active connections that can be allocated from this pool at the same time. If set to 0, there is no limit. 100
maxIdle The maximum number of connections that should be kept in the pool at all times. Min(maxActive,100)
minIdle The minimum number of established connections that should be kept in the pool at all times. Min(initialSize,10)
maxWait The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. 30000
maxAge Time in milliseconds to keep this connection. When a connection is returned to the pool, the pool will check to see if the current time less the time when the connection was created has reached maxAge, and if so, it closes the connection rather than returning it to the pool. A value of 0 means that connections will be left open and no age check will be done. 300000
testOnReturn The indication of whether objects will be validated before being returned to the pool. If set to true, the validationQuery property must be set to a non-null string or no test will occur. In order to have a more efficient validation, see validationInterval. false
testOnBorrow The indication of whether objects will be validated before being borrowed the pool. If the object fails to validate, it will be dropped from the pool and we will attempt to borrow another. If testOnBorrow is set to true, the validationQuery property must be set to a non-null string or no test will occur. In order to have a more efficient validation, see validationInterval. false
testWhileIdle The indication of whether objects will be validated by the idle object evictor. If the object fails to validate, it will be dropped from the pool. If testWhileIdle is set to true, the validationQuery property must be set to a non-null string or no test will occur. In order to have a more efficient validation, see validationInterval. false
validationQuery The SQL query that will be used to validate connections from this pool. If specified, this query does not have to return any data, it just can't throw a SQLException. See testOnReturn, testOnBorrow and testWhileIdle. An example value is SELECT 1 FROM DUAL. null
validationInterval To avoid excess validation, only run validation at most at this frequency, given in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. See testOnReturn, testOnBorrow and testWhileIdle. 30000
timeBetweenEvictionRunsMillis The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connections. 5000
url The URL of the NuoDB broker, optionally followed by the URLs of the secondary broker(s) that will be contacted in case the primary one is unreachable. The URLs must be separated by the character defined by the url-delimiter property (by default, '|').  
url-delimiter The delimiter used to separate the URLs of the brokers in the value of the url property.

|

Alternatively, the following code shows how to use a DataSource from within an application server.

DataSource ds = (DataSource)initContext.lookup("jdbc/nuoDB");         
Connection con = ds.getConnection();           
Statement stmt = con.createStatement()

See Connection Pooling Example for more details about this. The DataSource API is documented at Java DataSource API Reference.