Skip to main content
Jump to: navigation, search

Difference between revisions of "Configuring an Internal Connection Pool (ELUG)"

m (Introduction to the Internal Connection Pool Configuration)
m
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''
 +
 +
----
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Configuring an Internal Connection Pool (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Configuring an Internal Connection Pool (ELUG)|Related Topics]]</div>
  
  
==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 pools''' you may have created (see [[Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction to the Internal Connection Pool Creation|Introduction to the Internal Connection Pool Creation]]).
 
+
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 [[Creating%20an%20Internal%20Connection%20Pool%20(ELUG)#Introduction to the Internal Connection Pool Creation|Introduction to the Internal Connection Pool Creation]]).
+
 
+
This table lists the configurable options for an internal connection pool.
+
  
  
 
<span id="Table 97-1"></span>
 
<span id="Table 97-1"></span>
''''' Configurable Options for Connection Pool'''''
+
''''' Configurable Options for Connection Pools'''''
  
 
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Connection Pool" summary="This table lists the configurable options common to ConnectionPool and categorizes them as Basic and Advanced and indicates if the option can be configured with the Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 
{| class="RuleFormalMax" dir="ltr" title="Configurable Options for Connection Pool" summary="This table lists the configurable options common to ConnectionPool and categorizes them as Basic and Advanced and indicates if the option can be configured with the Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
Line 20: Line 19:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t2" headers="r1c1-t2" align="left" |
 
| id="r2c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Connection Pool Sizes|Connection pool sizes]])
+
[[#Configuring Connection Pool Sizes|Connection pool sizes]]
 
| headers="r2c1-t2 r1c2-t2" align="left" |
 
| headers="r2c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported.]]
 
[[Image:support.gif|Supported.]]
Line 27: Line 26:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t2" headers="r1c1-t2" align="left" |
 
| id="r3c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Exclusive Read Connections|Exclusive read connections]])
+
[[#Configuring Exclusive Read Connections|Exclusive read connections]] <sup> 1 </sup>
 
| headers="r3c1-t2 r1c2-t2" align="left" |
 
| headers="r3c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported.]]
 
[[Image:support.gif|Supported.]]
Line 34: Line 33:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t2" headers="r1c1-t2" align="left" |
 
| id="r4c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring a Nontransactional Read Login|Nontransactional read login]])<sup>Foot 1 </sup>
+
[[#Configuring a Nontransactional Read Login|Nontransactional read login]]<sup> 1 </sup>
 
| headers="r4c1-t2 r1c2-t2" align="left" |
 
| headers="r4c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported.]]
 
[[Image:support.gif|Supported.]]
Line 41: Line 40:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t2" headers="r1c1-t2" align="left" |
 
| id="r5c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Properties|Properties]])
+
[[#Configuring Properties|Properties]]
 
| headers="r5c1-t2 r1c2-t2" align="left" |
 
| headers="r5c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported.]]
 
[[Image:support.gif|Supported.]]
Line 48: Line 47:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t2" headers="r1c1-t2" align="left" |
 
| id="r6c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Connection Pool Connection Options|Connection pool connection options]]) <sup>Foot 2 </sup>
+
[[#Configuring Connection Pool Connection Options|Connection pool connection options]] <sup> 2, 3</sup>
 
| headers="r6c1-t2 r1c2-t2" align="left" |
 
| headers="r6c1-t2 r1c2-t2" align="left" |
 
[[Image:support.gif|Supported.]]
 
[[Image:support.gif|Supported.]]
Line 55: Line 54:
 
|}
 
|}
  
<sup>Footnote 1 </sup>Read connection pools only.<br><sup>Footnote 2 </sup>Not applicable to write connection pools.
+
<sup>1 </sup>Read connection pools only.<br>
 +
<sup>2 </sup>Not applicable to write connection pools.<br>
 +
<sup>2 </sup>Available for sequence connection pools.
 +
 
 +
 
  
 
==Configuring Connection Pool Sizes==
 
==Configuring Connection Pool Sizes==
Line 62: Line 65:
  
 
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.
 
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.
 
  
  
Line 69: Line 71:
 
'''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.
 
'''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.
 
|}
 
|}
 
  
  
Line 77: Line 78:
  
 
If the maximum number of connections is in use, the next connection request will be blocked until a connection is available.
 
If the maximum number of connections is in use, the next connection request will be blocked until a connection is available.
 
  
  
 
===How to Configure Connection Pool Size Using Workbench===
 
===How to Configure Connection Pool Size Using Workbench===
  
To specify the minimum and maximum number of connections in a EclipseLink internal connection pool, use this procedure:
+
To specify the minimum and maximum number of connections in an EclipseLink internal connection pool, use this procedure:
  
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
Line 90: Line 90:
 
Enter the desired minimum and maximum number of connections and press '''Enter''' or use the increment and decrement arrows.
 
Enter the desired minimum and maximum number of connections and press '''Enter''' or use the increment and decrement arrows.
  
'''See Also'''
+
For more information, see the following:
: [[#Configuring Connection Pool Sizes|Configuring Connection Pool Sizes]]
+
* [[#Configuring Connection Pool Sizes|Configuring Connection Pool Sizes]]
: [[Configuring%20a%20Session%20(ELUG)#Configuring Common Session Options|Configuring Common Session Options]]
+
* [[Configuring%20a%20Session%20(ELUG)#Configuring Common Session Options|Configuring Common Session Options]]
  
  
Line 101: Line 101:
  
 
Some data sources require additional, driver-specific properties not supported in the <tt>ConnectionPool</tt> API. Add these properties to the <tt>ConnectionPool</tt> so that EclipseLink can pass them to the driver.
 
Some data sources require additional, driver-specific properties not supported in the <tt>ConnectionPool</tt> API. Add these properties to the <tt>ConnectionPool</tt> so that EclipseLink can pass them to the driver.
 
  
  
Line 117: Line 116:
  
 
Use the following information to add or edit a login property on the Add Property dialog box to add or edit a login property:
 
Use the following information to add or edit a login property on the Add Property dialog box to add or edit a login property:
 
 
  
 
{| class="HRuleInformal" dir="ltr" title="This table identifies the fields on the Add Property dialog box." summary="This table identifies the fields on the Add Property dialog box." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table identifies the fields on the Add Property dialog box." summary="This table identifies the fields on the Add Property dialog box." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 132: Line 129:
 
The value EclipseLink retrieves using the <tt>DatasourceLogin</tt> method <tt>getProperty</tt> passing in the corresponding property name. Using Workbench, you can set only character values which EclipseLink returns as <tt>String</tt> objects.
 
The value EclipseLink retrieves using the <tt>DatasourceLogin</tt> method <tt>getProperty</tt> passing in the corresponding property name. Using Workbench, you can set only character values which EclipseLink returns as <tt>String</tt> objects.
 
|}
 
|}
 
  
  
Line 139: Line 135:
 
To delete an existing property, select the '''Name'''/'''Value''' row and click '''Remove'''.
 
To delete an existing property, select the '''Name'''/'''Value''' row and click '''Remove'''.
  
'''See Also'''
+
For more information, see [[#Configuring Properties|Configuring Properties]]
 
+
: [[#Configuring Properties|Configuring Properties]]
+
 
+
  
  
Line 154: Line 147:
  
 
When you use an external transaction controller (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|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.
 
When you use an external transaction controller (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|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.
 
  
  
 
===How to Configure Nontransactional Read Login Using Workbench===
 
===How to Configure Nontransactional Read Login Using Workbench===
  
To enable the configuration of nontransactional connection information for a EclipseLink read connection pool, use this procedure:
+
To enable the configuration of nontransactional connection information for an EclipseLink read connection pool, use this procedure:
  
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
Line 168: Line 160:
 
To enable a nontransactional read login, select the '''Use Non-Transactional Read Login''' option (see [[Introduction%20to%20Data%20Access%20(ELUG)#Externally Managed Transactional Data Sources|Externally Managed Transactional Data Sources]]). Continue with [[#Configuring Connection Pool Connection Options|Configuring Connection Pool Connection Options]] to specify the connection information.
 
To enable a nontransactional read login, select the '''Use Non-Transactional Read Login''' option (see [[Introduction%20to%20Data%20Access%20(ELUG)#Externally Managed Transactional Data Sources|Externally Managed Transactional Data Sources]]). Continue with [[#Configuring Connection Pool Connection Options|Configuring Connection Pool Connection Options]] to specify the connection information.
  
'''See Also'''
+
For more information, see [[#Configuring a Nontransactional Read Login|Configuring a Nontransactional Read Login]].
  
: [[#Configuring a Nontransactional Read Login|Configuring a Nontransactional Read Login]]
+
 
 +
===How to Configure Nontransactional Read Login Using Java===
 +
Use the <tt>getLogin</tt> method of your connection pool to obtain a <tt>DatabaseLogin</tt>, and then use the following <tt>DatabaseLogin</tt> methods to configure the nontransactional read login options:
 +
 
 +
* <tt>useExternalTransactionController</tt>
 +
* <tt>setDriverClass</tt>
 +
* <tt>setDriverClassName</tt>
 +
* <tt>setDriverURLHeader</tt>
  
  
Line 180: Line 179:
 
For read, named, and sequence connection pools, you can override the session login configuration on a per-connection pool basis.
 
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 [[#Configuring a Nontransactional Read Login|Configuring a Nontransactional Read Login]]).
+
To configure login configuration for a read connection pool, you must first enable it for [[#Configuring a Nontransactional Read Login| a nontransactional read login]]).
 
+
  
  
 
===How to Configure Connection Pool Connection Options Using Workbench===
 
===How to Configure Connection Pool Connection Options Using Workbench===
 
+
To configure connection information for an EclipseLink read, named, or sequence connection pool, use this procedure:
To configure connection information for a EclipseLink read, named, or sequence connection pool, use this procedure:
+
 
+
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
 
# 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.
 
# Select a read, named, or sequence connection pool in the '''Navigator'''. Its properties appear in the Editor.
Line 194: Line 190:
 
# Ensure the '''Use Non-Transaction Read Login''' option is selected.
 
# Ensure the '''Use Non-Transaction Read Login''' option is selected.
 
# Complete each field on the Connection tab.
 
# Complete each field on the Connection tab.
 +
  
 
Use the following information to complete fields on the Connection subtab:
 
Use the following information to complete fields on the Connection subtab:
 
 
  
 
{| class="HRuleInformal" dir="ltr" title="This table identifies the fields on the Connection tab." summary="This table identifies the fields on the Connection tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table identifies the fields on the Connection tab." summary="This table identifies the fields on the Connection tab." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 205: Line 200:
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r2c1-t5" headers="r1c1-t5" align="left" |
 
| id="r2c1-t5" headers="r1c1-t5" align="left" |
'''Database Driver'''<sup>Foot 1 </sup>
+
'''Database Driver'''<sup> 1 </sup>
 
| headers="r2c1-t5 r1c2-t5" align="left" |
 
| headers="r2c1-t5 r1c2-t5" align="left" |
 
Specify the appropriate database driver:
 
Specify the appropriate database driver:
 
* '''Driver Manager'''<nowiki>: Specify this option to configure the driver class and URL used to connect to the database. In this case, you must configure the </nowiki>'''Driver Class''' and '''Driver URL''' fields.
 
* '''Driver Manager'''<nowiki>: Specify this option to configure the driver class and URL used to connect to the database. In this case, you must configure the </nowiki>'''Driver Class''' and '''Driver URL''' fields.
* '''J2EE Datasource'''<nowiki>: Specify this option to use a Java EE data source already configured on your target application server. In this case, you must configure the </nowiki>'''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 [[Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring External Connection Pooling|Configuring External Connection Pooling]]).
+
* '''J2EE Datasource'''<nowiki>: Specify this option to use a Java EE data source already configured on your target application server. In this case, you must configure the </nowiki>'''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 [[Configuring%20a%20Data%20Source%20Login%20(ELUG)#Configuring External Connection Pooling|Configuring External Connection Pooling]]).
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r3c1-t5" headers="r1c1-t5" align="left" |
 
| id="r3c1-t5" headers="r1c1-t5" align="left" |
'''Driver Class'''[#sthref3274 <sup>Foot 1</sup>
+
'''Driver Class'''<sup> 1</sup>
 
| headers="r3c1-t5 r1c2-t5" align="left" | 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 EclipseLink application classpath.
 
| headers="r3c1-t5 r1c2-t5" align="left" | 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 EclipseLink application classpath.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t5" headers="r1c1-t5" align="left" |
 
| id="r4c1-t5" headers="r1c1-t5" align="left" |
'''URL'''[#sthref3275 <sup>Foot 1</sup>
+
'''URL'''<sup> 1</sup>
 
| headers="r4c1-t5 r1c2-t5" align="left" | 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.
 
| headers="r4c1-t5 r1c2-t5" align="left" | 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.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t5" headers="r1c1-t5" align="left" |
 
| id="r5c1-t5" headers="r1c1-t5" align="left" |
'''Datasource Name'''[#sthref3276 <sup>Foot 1</sup>
+
'''Datasource Name'''<sup> 1</sup>
 
| headers="r5c1-t5 r1c2-t5" align="left" |
 
| headers="r5c1-t5 r1c2-t5" align="left" |
 
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: <tt>jdbc/EmployeeDB</tt>). By convention, all such names should resolve to the JDBC subcontext (relative to the standard <tt>java:comp/env</tt> naming context that is the root of all provided resource factories).
 
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: <tt>jdbc/EmployeeDB</tt>). By convention, all such names should resolve to the JDBC subcontext (relative to the standard <tt>java:comp/env</tt> naming context that is the root of all provided resource factories).
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t5" headers="r1c1-t5" align="left" |
 
| id="r6c1-t5" headers="r1c1-t5" align="left" |
'''Connection Specification Class'''<sup>Foot 2 </sup>
+
'''Connection Specification Class'''<sup> 2 </sup>
 
| headers="r6c1-t5 r1c2-t5" align="left" |
 
| headers="r6c1-t5 r1c2-t5" align="left" |
 
Specify the appropriate connection specification class for the selected '''Platform'''. Click '''Browse''' to choose from all the classes in the EclipseLink classpath. (For example: if '''Platform''' is <tt>org.eclipse.persistence.eis.aq.AQPlatform</tt>, use <tt>org.eclipse.persistence.eis.aq.AQEISConnectionSpec</tt>). For more information on platform configuration, see [[Configuring%20an%20EIS%20Login%20(ELUG)#Configuring an EIS Data Source Platform at the Session Level|Configuring an EIS Data Source Platform at the Session Level]].
 
Specify the appropriate connection specification class for the selected '''Platform'''. Click '''Browse''' to choose from all the classes in the EclipseLink classpath. (For example: if '''Platform''' is <tt>org.eclipse.persistence.eis.aq.AQPlatform</tt>, use <tt>org.eclipse.persistence.eis.aq.AQEISConnectionSpec</tt>). For more information on platform configuration, see [[Configuring%20an%20EIS%20Login%20(ELUG)#Configuring an EIS Data Source Platform at the Session Level|Configuring an EIS Data Source Platform at the Session Level]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r7c1-t5" headers="r1c1-t5" align="left" |
 
| id="r7c1-t5" headers="r1c1-t5" align="left" |
'''Connection Factory URL'''<sup>Footref 2</sup>
+
'''Connection Factory URL'''<sup> 2</sup>
 
| headers="r7c1-t5 r1c2-t5" align="left" | Specify the appropriate connection factory URL for the selected '''Connection Specification Class''' (For example: <tt>jdbc:oracle:thin@:localhost:1521:orcl</tt>).
 
| headers="r7c1-t5 r1c2-t5" align="left" | Specify the appropriate connection factory URL for the selected '''Connection Specification Class''' (For example: <tt>jdbc:oracle:thin@:localhost:1521:orcl</tt>).
 
|}
 
|}
  
<sup>Footnote 1 </sup>For sessions that contain a <tt>DatabaseLogin</tt>.<br><sup>Footnote 2 </sup>For sessions that contain an <tt>EISLogin</tt>.
+
<sup>1 </sup>For sessions that contain a <tt>DatabaseLogin</tt>.<br>
 +
<sup>2 </sup>For sessions that contain an <tt>EISLogin</tt>.
 +
 
 +
For more information, see [[#Configuring Connection Pool Connection Options|Configuring Connection Pool Connection Options]]
 +
 
  
'''See Also'''
 
: [[#Configuring Connection Pool Connection Options|Configuring Connection Pool Connection Options]]
 
  
 
==Configuring Exclusive Read Connections==
 
==Configuring Exclusive Read Connections==
 
 
An exclusive connection is one that EclipseLink allocates specifically to a given session and one that is never used by any other session.
 
An exclusive connection is one that EclipseLink 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.
 
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 [[Introduction%20to%20Data%20Access%20(ELUG)#Internal Connection Pools|Internal Connection Pools]]), you can configure EclipseLink to acquire an exclusive connection from the read connection pool.
+
If you are using [[Introduction%20to%20Data%20Access%20(ELUG)#Internal Connection Pools|Internal Connection Pools]], you can configure EclipseLink to acquire an exclusive connection from the read connection pool.
  
 
By default, EclipseLink acquires exclusive read connections.
 
By default, EclipseLink acquires exclusive read connections.
  
 
If you are using external connection pools, read connections are always exclusive.
 
If you are using external connection pools, read connections are always exclusive.
 
  
  
 
===How to Configure Exclusive Read Connections Using Workbench===
 
===How to Configure Exclusive Read Connections Using Workbench===
 
+
To configure an EclipseLink read connection pool to allocate exclusive connections, use this procedure:
To configure a EclipseLink read connection pool to allocate exclusive connections, use this procedure:
+
 
+
 
# Expand a server session to reveal its connection pools in the '''Navigator'''.
 
# 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.
 
# Select a read connection pool in the '''Navigator'''. Its properties appear in the Editor.
Line 266: Line 261:
 
Deselect the '''Exclusive Connections''' option to configure EclipseLink to share read connections and allow concurrent reads. Before selecting this option, ensure that your JDBC driver supports concurrent reads.
 
Deselect the '''Exclusive Connections''' option to configure EclipseLink to share read connections and allow concurrent reads. Before selecting this option, ensure that your JDBC driver supports concurrent reads.
  
'''See Also'''
+
For more information, see [[#Configuring Exclusive Read Connections|Configuring Exclusive Read Connections]]
 
+
: [[#Configuring Exclusive Read Connections|Configuring Exclusive Read Connections]]
+
  
  
Line 277: Line 270:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Task]]
 
[[Category: Task]]

Latest revision as of 10:14, 23 July 2012

Elug draft icon.png For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/



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 pools you may have created (see Introduction to the Internal Connection Pool Creation).


Configurable Options for Connection Pools

Option to Configure Workbench Java

Connection pool sizes

Supported.

Supported.

Exclusive read connections 1

Supported.

Supported.

Nontransactional read login 1

Supported.

Supported.

Properties

Supported.

Supported.

Connection pool connection options 2, 3

Supported.

Supported.

1 Read connection pools only.
2 Not applicable to write connection pools.
2 Available for sequence connection pools.


Configuring Connection Pool Sizes

By default, if using EclipseLink internal connection pooling, the EclipseLink 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 EclipseLink 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.


How to Configure Connection Pool Size Using Workbench

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

  1. Expand a server session to reveal its connection pools in the Navigator.
  2. Select a connection pool in the Navigator. Its properties appear in the Editor.
  3. Click the General tab. The General tab appears.
    General Tab, Connection Count Options
    General Tab, Connection Count Options

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

For more information, see the following:


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 EclipseLink can pass them to the driver.


How to Configure Properties Using Workbench

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

  1. Expand a server session to reveal its connection pools in the Navigator.
  2. Select a read, named, or sequence connection pool in the Navigator. Its properties appear in the Editor.
  3. Click the Login tab. The Login tab appears.
  4. Click the Properties subtab. The Properties subtab appears.
    Login Tab, Properties Subtab
    Login Tab, Properties Subtab
  5. You can add, edit, or remove properties using Add Property dialog box that appears upon clicking Add, Edit or Remove.

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 EclipseLink retrieves the property value using the DatasourceLogin method getProperty.
Value

The value EclipseLink retrieves using the DatasourceLogin method getProperty passing in the corresponding property name. Using Workbench, you can set only character values which EclipseLink 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.

For more information, see Configuring Properties


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.


Configuring a Nontransactional Read Login

When you use an external transaction controller (see 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.


How to Configure Nontransactional Read Login Using Workbench

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

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

    Login Tab, Connection Subtab
    Login Tab, Connection Subtab

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

For more information, see Configuring a Nontransactional Read Login.


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


Configuring Connection Pool Connection Options

By default, connection pools use the login configuration specified for their session (see Configuring Database Login Connection Options and 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).


How to Configure Connection Pool Connection Options Using Workbench

To configure connection information for an EclipseLink read, named, or sequence connection pool, use this procedure:

  1. Expand a server session to reveal its connection pools in the Navigator.
  2. Select a read, named, or sequence connection pool in the Navigator. Its properties appear in the Editor.
  3. Click the Login tab. The Login tab appears.
  4. Click the Connection subtab. The Connection subtab appears.
    Login Tab, Connection Subtab, Relational Session Connection Pool Options
    Login Tab, Connection Subtab, Relational Session Connection Pool Options
    Login Tab, Connection Subtab, EIS Session Connection Pool Options
    Login Tab, Connection Subtab, EIS Session Connection Pool Options
  5. Ensure the Use Non-Transaction Read Login option is selected.
  6. Complete each field on the Connection tab.


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

Field Description

Database Driver 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 Configuring External Connection Pooling).

Driver Class 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 EclipseLink application classpath.

URL 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 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 2

Specify the appropriate connection specification class for the selected Platform. Click Browse to choose from all the classes in the EclipseLink classpath. (For example: if Platform is org.eclipse.persistence.eis.aq.AQPlatform, use org.eclipse.persistence.eis.aq.AQEISConnectionSpec). For more information on platform configuration, see Configuring an EIS Data Source Platform at the Session Level.

Connection Factory URL 2

Specify the appropriate connection factory URL for the selected Connection Specification Class (For example: jdbc:oracle:thin@:localhost:1521:orcl).

1 For sessions that contain a DatabaseLogin.
2 For sessions that contain an EISLogin.

For more information, see Configuring Connection Pool Connection Options


Configuring Exclusive Read Connections

An exclusive connection is one that EclipseLink 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, you can configure EclipseLink to acquire an exclusive connection from the read connection pool.

By default, EclipseLink acquires exclusive read connections.

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


How to Configure Exclusive Read Connections Using Workbench

To configure an EclipseLink read connection pool to allocate exclusive connections, use this procedure:

  1. Expand a server session to reveal its connection pools in the Navigator.
  2. Select a read connection pool in the Navigator. Its properties appear in the Editor.
  3. Click the Login tab. The Login tab appears.
  4. Click the Connection subtab. The Connection subtab appears.
    Login Tab, Connection Subtab, Exclusive Connections Option
    Login Tab, Connection Subtab, Exclusive Connections Option

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

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

For more information, see Configuring Exclusive Read Connections



Copyright Statement

Back to the top