WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

RDBMS Database Connection Pool

A connection pool is used to increase the performance of the services provided by the RDBMS access module.

The connection pool is specified by a configuration document with the following structure:

<config>
  <rdbms>
    <jdbcDriver>org.h2.Driver</jdbcDriver>
    <jdbcConnection>jdbc:h2:/home/tab/mydatabase</jdbcConnection>
    <poolSize>8</poolSize>
    <blockOnOverload>30000</blockOnOverload>
    < !-- Timeout query configuration -->
    <defaultQueryTimeout>5000</defaultQueryTimeout>
    <queryTimeoutMethod>SET | TIMER</queryTimeoutMethod>
    < !-- Connection test configuration -->
    <connectionTestQuery />
    <connectionTestOnAcquire>false</connectionTestOnAcquire>
    <connectionTestOnIdlePeriod>60000</connectionTestOnIdlePeriod>
    < !-- Additional tags are passed as properties to the JDBC driver -->
    <user>dba</user>
    <password>ILoveLinux</password>
  </rdbms>
</config>

Core Connection Information

The RDBMS Access module uses Java's JDBC technology to connect with relational database servers.

  • jdbcDriver specifies the Java class used to establish the database connection within JDBC. Each relational database requires a specific JDBC driver and in some cases there are multiple options. Please consult the relational database vendor's documentation for details. This class will be located using the classloaders from the request scope of the initiating request.
  • jdbcConnection is the connection string passed to JDBC and the specified jdbcDriver. This is vendor and maybe jdbcDriver specific; please consult the relational database vendor's documentation for details.
  • poolSize specifies a maximum number of connections that can be concurrently opened.
  • blockOnOverload by default if demands on the connections in the pool exceed the size an overload exception will be thrown. When the optional blockOnOverload tag is specified then when an overload situation occurs the connection pool will block until a connection becomes available. The value is a period in milliseconds after which if no connection is available the request for a connect will fail with an exception. A value of 0 will cause the pool to block indefinitely for a connection.

Connection Timeout Configuration

The connection with a relational database server is usually made across a network connection. The connection may be dropped due to a network failure and time-outs are used to detect abnormally long processing times. The connection pool uses one of two methods. The first calls the JDBC method Statement.setQueryTimeout(...). The second uses an internal timer based on java.util.TimerTask to monitor the request. This second method is useful for primitive database with no support for detecting query timeouts.

  • queryTimeoutMethod is optional and determines how query timeouts are detected. "SET" uses the JDBC method Statement.setQueryTimeout(long). "TIMER" uses a timer monitor. If this is not set the default "SET" method is used.
  • defaultQueryTimeout sets the timeout period in milliseconds.

Connection Availability Test Configuration

The connection pool provides the ability to test for connection liveness. A query may be specified that is used to test database connections to see if they are live. By default a connection.getMetaData().getTables(null,null,null,null) will be performed which could be slow. If an idle connection fails it's test it is silently dropped from the pool.

  • connectionTestQuery is optional and specifies a SQL query to use when testing for connection liveness.
  • connectionTestOnAcquire when set to true indicates to the connection pool that each connection is tested for liveness when it is acquired and before it is returned for use. If a connection has become dead, it is dropped and a new one is created before being returned.
  • connectionTestOnIdlePeriod is optional and specifies the period of time in milliseconds that the pool is idle before conducting a liveness tests. If this is not specified or is set to the value 0 (zero), then no testing during the idle period is performed