blob: f6f0c9010c3bfc760927a6fed2b5f62285bbd6c0 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>About Connection Pools | EclipseLink 3.0.x Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:39:53Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="About Connection Pools" />
<meta name="relnum" content="3.0" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="data_access005.htm" title="Previous" type="text/html" />
<link rel="next" href="data_access007.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:mdbgdwjv8zu', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><div class="booktitle">Understanding EclipseLink,
<b>3.0</b><br /></font></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="data_access005.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="data_access007.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CHDBGIHH" name="CHDBGIHH"></a><a id="OTLCG00007" name="OTLCG00007"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">About Connection Pools</font></h1>
<p>A <strong>connection pool</strong> is a service that creates and maintains a shared collection (pool) of data source connections on behalf of one or more clients. The connection pool provides a connection to a process on request, and returns the connection to the pool when the process is finished using it. When it is returned to the pool, the connection is available for other processes. Because establishing a connection to a data source can be time-consuming, reusing such connections in a connection pool can improve performance.</p>
<p>EclipseLink uses connection pools to manage and share the connections used by server and client sessions. This feature reduces the number of connections required and allows your application to support many clients.</p>
<p>You can configure your session to use internal connection pools provided by EclipseLink or external connection pools provided by a JDBC driver or Jakarta EE container.</p>
<p>You can use connection pools in your EclipseLink application for a variety of purposes, such as reading, writing, sequencing, and other application-specific functions.</p>
<p>This section describes the following types of connection pools:</p>
<ul>
<li>
<p><a href="#CHDHEIJE">Internal Connection Pools</a></p>
</li>
<li>
<p><a href="#CHDCAIEJ">External Connection Pools</a></p>
</li>
<li>
<p><a href="#CHDJGAJE">Default (Write) and Read Connection Pools</a></p>
</li>
<li>
<p><a href="#CHDEFJHH">Sequence Connection Pools</a></p>
</li>
<li>
<p><a href="#CHDDGHGA">Application-Specific Connection Pools</a></p>
</li>
</ul>
<a id="CHDHEIJE" name="CHDHEIJE"></a><a id="OTLCG93611" name="OTLCG93611"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Internal Connection Pools</font></h2>
<p>For non-Jakarta EE applications, you typically use <em>internal</em> connection pools. By default, EclipseLink sessions use internal connection pools.</p>
<p>Using internal connection pools, you can configure the default (write) and read connection pools. You can also create additional connection pools for object identity, or any other purpose.</p>
<p>Internal connection pools allow you to optimize the creation of read connections for applications that read data only to display it and only infrequently modify data. This also allow you to use Workbench to configure the default (write) and read connection pools and to create additional connection pools for object identity or any other purpose.</p>
</div>
<!-- class="sect2" -->
<a id="CHDCAIEJ" name="CHDCAIEJ"></a><a id="OTLCG93612" name="OTLCG93612"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">External Connection Pools</font></h2>
<p>For Jakarta EE applications, you typically use <em>external</em> connection pools. An external connection pool is a collection of reusable connections to a single data source provided by a JDBC driver or Jakarta EE container.</p>
<p>If you are using an external transaction controller (JTA), you must use external connection pools to integrate with the JTA.</p>
<p>Using external connection pools, you can use Java to configure the default (write) and read connection pools and create additional connection pools for object identity, or any other purpose.</p>
<p>External connection pools enable your EclipseLink application to do the following:</p>
<ul>
<li>
<p>Integrate into a Jakarta EE-enabled system.</p>
</li>
<li>
<p>Integrate with JTA transactions (JTA transactions require a JTA-enabled data source).</p>
</li>
<li>
<p>Leverage a shared connection pool in which multiple applications use the same data source.</p>
</li>
<li>
<p>Use a data source configured and managed directly on the server.</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="CHDJGAJE" name="CHDJGAJE"></a><a id="OTLCG93613" name="OTLCG93613"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Default (Write) and Read Connection Pools</font></h2>
<p>A server session provides a read connection pool and a write connection pool. These could be different pools, or if you use external connection pooling, the same connection pool.</p>
<p>All read queries use connections from the read connection pool and all queries that write changes to the data source use connections from the write connection pool. You can configure attributes of the default (write) and read connection pools.</p>
<p>Whenever a new connection is established, EclipseLink uses the connection configuration you specify in your session's <code>DatasourceLogin</code>. Alternatively, when you use an external transaction controller, you can define a separate connection configuration for a read connection pool to avoid the additional overhead, if appropriate.</p>
<p>Use the <code>connection-pool.read</code> property to configure a read connection pool for non-transaction read queries. By default, EclipseLink does not use a separate read connection pool; the default pool is used for read queries. For more information, see <code>connection-pool.read</code> in <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDEFJHH" name="CHDEFJHH"></a><a id="OTLCG93614" name="OTLCG93614"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Sequence Connection Pools</font></h2>
<p>An essential part of maintaining object identity is sequencing&ndash;managing the assignment of unique values to distinguish one instance from another. For more information, see <a href="cache002.htm#CHEFCFEG">About Cache Type and Size</a>.</p>
<p>Sequencing involves reading and writing a special sequence resource maintained by your data source.</p>
<p>By default, EclipseLink includes sequence operations in a separate transaction. This avoids complications during the write transaction, which may lead to deadlocks over the sequence resource. However, when using an external transaction controller (such as a JTA data source or connection pool), EclipseLink cannot use a different transaction for sequencing. Use a sequence connection pool to configure a non-JTA transaction pool for sequencing. This is required only for table sequencing&ndash;not native sequencing.</p>
<p>In each server session, you can create one connection pool, called a sequence connection pool, that EclipseLink uses exclusively for sequencing. With a sequence connection pool, EclipseLink satisfies a request for a new object identifier outside of the transaction from which the request originates. This allows EclipseLink to immediately commit an update to the sequence resource, which avoids deadlocks.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p><font face="arial, helvetica, sans-serif"><strong><strong>Note</strong>:</strong></font></p>
<p>If you use a sequence connection pool and the original transaction fails, the sequence operation does not roll back.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<p>You should use a sequence connection pool, if the following applies:</p>
<ul>
<li>
<p>You use table sequencing (that is, non-native sequencing).</p>
</li>
<li>
<p>You use external transaction controller (JTA).</p>
</li>
</ul>
<p>You should not use a sequence connection pool, if the following applies:</p>
<ul>
<li>
<p>You do not use sequencing, or use the data source's native sequencing.</p>
</li>
<li>
<p>You have configured the sequence table to avoid deadlocks.</p>
</li>
<li>
<p>You use non-JTA data sources.</p>
</li>
</ul>
<p>You can configure a sequence connection pool with the <code>eclipselink.connection-pool.sequence</code> persistence unit property. This property allows the connection pool to allocate generated IDs, and is required only for <code>TABLE</code> sequencing. By default, EclipseLink does not use a separate sequence connection pool; the default pool is used for sequencing. For more information, see <code>connection-pool.sequence</code> in <em>Jakarta Persistence API (JPA) Extensions Reference for EclipseLink</em>.</p>
</div>
<!-- class="sect2" -->
<a id="CHDDGHGA" name="CHDDGHGA"></a><a id="OTLCG93615" name="OTLCG93615"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Application-Specific Connection Pools</font></h2>
<p>When you use internal EclipseLink connection pools in a session, you can create one or more connection pools that you can use for any application purpose. These are called named connection pools, as you can give them any name you want and use them for any purpose.</p>
<p>Typically, use these named connection pools to provide pools of different security levels. For example, the "default" connection pool may only allow access to specific tables but the "admin" connection pool may allow access to all tables.</p>
</div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="data_access005.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="data_access007.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2012 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>