101 Configuring an Internal Connection Pool

This chapter describes the various components that you must configure to use an internal connection pool.

This chapter includes the following sections:

Introduction to the Internal Connection Pool Configuration
Configuring Connection Pool Sizes
Configuring Properties
Configuring a Nontransactional Read Login
Configuring Connection Pool Connection Options
Configuring Exclusive Read Connections

Table 101-1 lists the configurable options for an internal connection pool.

101.1 Introduction to the Internal Connection Pool Configuration

When you are using server sessions, you can configure the default read connection pool and write connection pool. You can also configure the optional named connection pools and sequence connection pool you may have created (see Section 100.1, "Introduction to the Internal Connection Pool Creation").

Table 101-1 lists the configurable options for an internal connection pool.

Table 101-1 Configurable Options for Connection Pool

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Connection pool sizes (see Section 101.2, "Configuring Connection Pool Sizes")
Exclusive read connections (see Section 101.6, "Configuring Exclusive Read Connections")^Footref 1
Nontransactional read login (see Section 101.4, "Configuring a Nontransactional Read Login")^Foot 1
Properties (see Section 101.3, "Configuring Properties")
Connection pool connection options (see Section 101.5, "Configuring Connection Pool Connection Options")^Foot 2 ^Foot 3

^Footnote 1Read connection pools only.

^Footnote 2Not applicable to write connection pools.

^Footnote 3Applicable for sequence connection pools.

101.2 Configuring Connection Pool Sizes

By default, if using TopLink internal connection pooling, the TopLink write connection pool maintains a minimum of five connections and a maximum of ten. The read connection pool maintains a minimum and maximum of two connections.

Connection pool size can significantly influence the concurrency of your application and should be set to be large enough to handle your expected application load.

Tip:

To maintain compatibility with JDBC drivers that do not support many connections, the default number of connections is small. If your JDBC driver supports it, use a larger number of connections for reading and writing.

The smallest value you can enter is 0. Setting the maximum number of connections to 0 will make it impossible for TopLink to allocate any connections.

The minimum number of connections should always be less than or equal to the maximum number of connections.

If the maximum number of connections is in use, the next connection request will be blocked until a connection is available.

You can configure the connection pool size using Oracle JDeveloper TopLink Editor, TopLink Workbench (see Section 101.2.1, "How to Configure Connection Pool Size Using TopLink Workbench"), or Java (see Section 101.2.2, "How to Configure Connection Pool Size Using Java").

101.2.1 How to Configure Connection Pool Size Using TopLink Workbench

To specify the minimum and maximum number of connections in a TopLink internal connection pool, use this procedure:

Expand a server session to reveal its connection pools in the Navigator.
Select a connection pool in the Navigator. Its properties appear in the Editor.
Click the General tab. The General tab appears.

Figure 101-1 General Tab, Connection Count Options

Description of "Figure 101-1 General Tab, Connection Count Options"

Enter the desired minimum and maximum number of connections and press Enter or use the increment and decrement arrows.

101.2.2 How to Configure Connection Pool Size Using Java

Using Java, you can set the connection pool size by using the setMaxNumberOfConnections and setMinNumberOfConnection method.

Example 101-1 shows how to configure the connection pool size for a read connection.

Example 101-1 Configuring Connection Pool Size

ConnectionPool pool = new ConnectionPool();
pool.setName("read");
pool.setLogin(login);
pool.setMaxNumberOfConnections(50);
pool.setMinNumberOfConnections(50);
serverSession.setReadConnectionPool(pool);

101.3 Configuring Properties

For all connection pools, except write connection pools, you can specify arbitrary named values, called properties.

Some data sources require additional, driver-specific properties not supported in the ConnectionPool API. Add these properties to the ConnectionPool so that TopLink can pass them to the driver.

You can configure properties using Oracle JDeveloper TopLink Editor, TopLink Workbench (see Section 101.3.1, "How to Configure Properties Using TopLink Workbench"), or Java (see Section 101.3.2, "How to Configure Properties Using Java").

101.3.1 How to Configure Properties Using TopLink Workbench

To specify arbitrary named value pairs that TopLink associates with a ConnectionPool, use this procedure:

Expand a server session to reveal its connection pools in the Navigator.
Select a read, named, or sequence connection pool in the Navigator. Its properties appear in the Editor.
Click the Login tab. The Login tab appears.
Click the Properties subtab. The Properties subtab appears.

Figure 101-2 Login Tab, Properties Subtab

Description of "Figure 101-2 Login Tab, Properties Subtab"

Complete the Add Property dialog box.

Use the following information to add or edit a login property on the Add Property dialog box to add or edit a login property:

Option	Description
Name	The name by which TopLink retrieves the property value using the `DatasourceLogin` method `getProperty`.
Value	The value TopLink retrieves using the `DatasourceLogin` method `getProperty` passing in the corresponding property name. Using TopLink Workbench, you can set only character values which TopLink returns as `String` objects.

To add (or change) a new Name/Value property, click Add (or Edit).

To delete an existing property, select the Name/Value row and click Remove.

101.3.2 How to Configure Properties Using Java

Using Java, you can set any Object value using the DatasourceLogin method setProperty. To remove a property, use the DatasourceLogin method removeProperty.

101.4 Configuring a Nontransactional Read Login

When you use an external transaction controller (see Section 89.9, "Configuring the Server Platform"), establishing a connection requires not only the usual connection setup overhead, but also transactional overhead. If your application reads data only to display it and only infrequently modifies data, you can configure an internal read connection pool to use its own connection specification that does not use the external transaction controller. This may improve performance by reducing the time it takes to establish a new read connection.

You can configure the nontransactional read login using Oracle JDeveloper TopLink Editor, TopLink Workbench (see Section 101.4.1, "How to Configure Nontransactional Read Login Using TopLink Workbench"), or Java (see Section 101.4.2, "How to Configure Nontransactional Read Login Using Java").

101.4.1 How to Configure Nontransactional Read Login Using TopLink Workbench

To enable the configuration of nontransactional connection information for a TopLink read connection pool, use this procedure:

Expand a server session to reveal its connection pools in the Navigator.
Select a read connection pool in the Navigator. Its properties appear in the Editor.
Click the Login tab. The Login tab appears.
Click the Connection subtab. The Connection subtab appears.

Figure 101-3 Login Tab, Connection Subtab

Description of "Figure 101-3 Login Tab, Connection Subtab"

To enable a nontransactional read login, select the Use Non-Transactional Read Login option (see Section 96.1.1, "Externally Managed Transactional Data Sources"). Continue with Section 101.5, "Configuring Connection Pool Connection Options" to specify the connection information.

101.4.2 How to Configure Nontransactional Read Login Using Java

Use the getLogin method of your connection pool to obtain a DatabaseLogin, and then use the following DatabaseLogin methods to configure the nontransactional read login options:

useExternalTransactionController
setDriverClass
setDriverClassName
setDriverURLHeader

101.5 Configuring Connection Pool Connection Options

By default, connection pools use the login configuration specified for their session (see Section 98.3, "Configuring Database Login Connection Options" and Section 99.3, "Configuring EIS Connection Specification Options at the Session Level").

For read, named, and sequence connection pools, you can override the session login configuration on a per-connection pool basis.

To configure login configuration for a read connection pool, you must first enable it for a nontransactional read login (see Section 101.4, "Configuring a Nontransactional Read Login").

You can configure the connection pool connection options using Oracle JDeveloper TopLink Editor or TopLink Workbench (see Section 101.5.1, "How to Configure Connection Pool Connection Options Using TopLink Workbench").

101.5.1 How to Configure Connection Pool Connection Options Using TopLink Workbench

To configure connection information for a TopLink read, named, or sequence connection pool, use this procedure:

Expand a server session to reveal its connection pools in the Navigator.
Select a read, named, or sequence connection pool in the Navigator. Its properties appear in the Editor.
Click the Login tab. The Login tab appears.
Click the Connection subtab. The Connection subtab appears.

Figure 101-4 Login Tab, Connection Subtab, Relational Session Connection Pool Options

Description of "Figure 101-4 Login Tab, Connection Subtab, Relational Session Connection Pool Options"

Figure 101-5 Login Tab, Connection Subtab, EIS Session Connection Pool Options

Description of "Figure 101-5 Login Tab, Connection Subtab, EIS Session Connection Pool Options"
Ensure the Use Non-Transaction Read Login option is selected.

Use the following information to complete fields on the Connection subtab:

Field	Description
Database Driver^Foot 1	Specify the appropriate database driver: Driver Manager: Specify this option to configure the driver class and URL used to connect to the database. In this case, you must configure the Driver Class and Driver URL fields. J2EE Datasource: Specify this option to use a Java EE data source already configured on your target application server. In this case, you must configure the Datasource Name field. Note: If you select J2EE Datasource, you must use external connection pooling. You cannot use internal connection pools with this Database Driver option (for more information, see Section 97.4, "Configuring External Connection Pooling").
Driver Class^Footref 1	Configure this field when Database Driver is set to Driver Manager. Select from the menu of options. This menu includes all JDBC drivers in the TopLink application classpath.
URL^Footref 1	Configure this field when Database Driver is set to Driver Manager. Select from the menu of options relevant to the selected Driver Class and edit the URL to suit your data source.
Datasource Name^Footref 1	Configure this field when Database Driver is set to J2EE Datasource. Specify any valid JNDI name that identifies the Java EE data source preconfigured on your target application server (For example: `jdbc/EmployeeDB`). By convention, all such names should resolve to the JDBC subcontext (relative to the standard `java:comp/env` naming context that is the root of all provided resource factories).
Connection Specification Class^Foot 2	Specify the appropriate connection specification class for the selected Platform. Click Browse to choose from all the classes in the TopLink classpath. (For example: if Platform is `oracle.toplink.eis.aq.AQPlatform`, use `oracle.toplink.eis.aq.AQEISConnectionSpec`). For more information on platform configuration, see Section 99.2, "Configuring an EIS Data Source Platform at the Session Level".
Connection Factory URL^Footref 2	Specify the appropriate connection factory URL for the selected Connection Specification Class (For example: `jdbc:oracle:thin@:localhost:1521:orcl`).

^Footnote 1For sessions that contain a DatabaseLogin.

^Footnote 2For sessions that contain an EISLogin.

101.6 Configuring Exclusive Read Connections

An exclusive connection is one that TopLink allocates specifically to a given session and one that is never used by any other session.

Allowing concurrent reads on the same connection reduces the number of read connections required and reduces the risk of having to wait for an available connection. However, many JDBC drivers do not support concurrent reads.

If you are using internal connection pools (see Section 96.1.6.1, "Internal Connection Pools"), you can configure TopLink to acquire an exclusive connection from the read connection pool.

By default, TopLink acquires exclusive read connections.

If you are using external connection pools, read connections are always exclusive.

You can configure the connection pool size using Oracle JDeveloper TopLink Editor or TopLink Workbench (see Section 101.6.1, "How to Configure Exclusive Read Connections Using TopLink Workbench").

101.6.1 How to Configure Exclusive Read Connections Using TopLink Workbench

To configure a TopLink read connection pool to allocate exclusive connections, use this procedure:

Expand a server session to reveal its connection pools in the Navigator.
Select a read connection pool in the Navigator. Its properties appear in the Editor.
Click the Login tab. The Login tab appears.
Click the Connection subtab. The Connection subtab appears.

Figure 101-6 Login Tab, Connection Subtab, Exclusive Connections Option

Description of "Figure 101-6 Login Tab, Connection Subtab, Exclusive Connections Option"

Select the Exclusive Connections option to configure TopLink to acquire an exclusive connection from the read connection pool.

Deselect the Exclusive Connections option to configure TopLink to share read connections and allow concurrent reads. Before selecting this option, ensure that your JDBC driver supports concurrent reads.