<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Applications: DataSource</title><meta content="DocBook XSL Stylesheets V1.78.1" name="generator"><link rel="home" href="index.html" title="The PostgreSQL™ JDBC Interface"><link rel="up" href="datasource.html" title="Chapter 11. Connection Pools and Data Sources"><link rel="prev" href="ds-cpds.html" title="Application Servers: ConnectionPoolDataSource"><link rel="next" href="tomcat.html" title="Tomcat setup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Applications: <code class="classname">DataSource</code></th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ds-cpds.html">Prev</a> </td><th align="center" width="60%">Chapter 11. Connection Pools and Data Sources</th><td align="right" width="20%"> <a accesskey="n" href="tomcat.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ds-ds"></a>Applications: <code class="classname">DataSource</code></h2></div></div></div><p><span class="productname">PostgreSQL</span>™ includes two
implementations of <code class="literal">DataSource</code>
, as shown in <a class="xref" href="ds-ds.html#ds-ds-imp" title="Table 11.2. DataSource Implementations">Table 11.2, “<code class="classname">DataSource</code> Implementations”</a>. One that does
pooling and the other that does not.
The pooling implementation does not actually close connections
when the client calls the <code class="literal">close</code> method, but
instead returns the connections to a pool of available connections
for other clients to use. This avoids any overhead of repeatedly
opening and closing connections, and allows a large number of
clients to share a small number of database connections.</p><p>The pooling data-source implementation provided here is not
the most feature-rich in the world. Among other things,
connections are never closed until the pool itself is closed;
there is no way to shrink the pool. As well, connections
requested for users other than the default configured user are
not pooled. Its error handling sometimes cannot remove a broken
connection from the pool. In general it is not recommended to
use the <span class="productname">PostgreSQL</span>™ provided connection
pool. Check your application server or check out the excellent
<a class="ulink" href="http://commons.apache.org/dbcp/" target="_top">
jakarta commons DBCP</a> project.
</p><div class="table"><a name="ds-ds-imp"></a><p class="title"><b>Table 11.2. <code class="classname">DataSource</code> Implementations</b></p><div class="table-contents"><table summary="DataSource Implementations" border="1"><colgroup><col><col></colgroup><thead><tr><th>Pooling</th><th>Implementation Class</th></tr></thead><tbody><tr><td>No</td><td><code class="classname">org.postgresql.ds.PGSimpleDataSource</code></td></tr><tr><td>Yes</td><td><code class="classname">org.postgresql.ds.PGPoolingDataSource</code></td></tr></tbody></table></div></div><br class="table-break"><p>
Both implementations use the same configuration scheme.
<acronym class="acronym">JDBC</acronym> requires that a
<code class="literal">DataSource</code> be configured via JavaBean
properties, shown in <a class="xref" href="ds-ds.html#ds-ds-props" title="Table 11.3. DataSource Configuration Properties">Table 11.3, “<code class="classname">DataSource</code> Configuration Properties”</a>, so there
are get and set methods for each of these properties.
</p><div class="table"><a name="ds-ds-props"></a><p class="title"><b>Table 11.3. <code class="classname">DataSource</code> Configuration Properties</b></p><div class="table-contents"><table summary="DataSource Configuration Properties" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">serverName</code></td><td><span class="type">String</span></td><td><span class="productname">PostgreSQL</span>™ database server
host name</td></tr><tr><td><code class="literal">databaseName</code></td><td><span class="type">String</span></td><td><span class="productname">PostgreSQL</span>™ database name</td></tr><tr><td><code class="literal">portNumber</code></td><td><span class="type">int</span></td><td>TCP port which the
<span class="productname">PostgreSQL</span>™ database server is
listening on (or 0 to use the default port)</td></tr><tr><td><code class="literal">user</code></td><td><span class="type">String</span></td><td>User used to make database connections</td></tr><tr><td><code class="literal">password</code></td><td><span class="type">String</span></td><td>Password used to make database connections</td></tr><tr><td><code class="literal">ssl</code></td><td><span class="type">boolean</span></td><td>
If <code class="literal">true</code>, use SSL encrypted connections
(default <code class="literal">false</code>)
</td></tr><tr><td><code class="literal">sslfactory</code></td><td><span class="type">String</span></td><td>
Custom <code class="classname">javax.net.ssl.SSLSocketFactory</code>
class name (see <a class="xref" href="ssl-factory.html" title="Custom SSLSocketFactory">the section called “Custom SSLSocketFactory”</a>)
</td></tr></tbody></table></div></div><br class="table-break"><p>The pooling implementation requires some additional
configuration properties, which are shown in <a class="xref" href="ds-ds.html#ds-ds-xprops" title="Table 11.4. Additional Pooling DataSource Configuration Properties">Table 11.4, “Additional Pooling <code class="classname">DataSource</code> Configuration Properties”</a>.</p><div class="table"><a name="ds-ds-xprops"></a><p class="title"><b>Table 11.4. Additional Pooling <code class="classname">DataSource</code> Configuration Properties</b></p><div class="table-contents"><table summary="Additional Pooling DataSource Configuration Properties" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">dataSourceName</code></td><td><span class="type">String</span></td><td>Every pooling <code class="literal">DataSource</code> must have a
unique name.</td></tr><tr><td><code class="literal">initialConnections</code></td><td><span class="type">int</span></td><td>The number of database connections to be created
when the pool is initialized.</td></tr><tr><td><code class="literal">maxConnections</code></td><td><span class="type">int</span></td><td>The maximum number of open database connections to
allow. When more connections are requested, the caller
will hang until a connection is returned to the pool.</td></tr></tbody></table></div></div><br class="table-break"><p><a class="xref" href="ds-ds.html#ds-example" title="Example 11.1. DataSource Code Example">Example 11.1, “<code class="literal">DataSource</code> Code Example”</a> shows an example of typical application code using a
pooling <code class="literal">DataSource</code>.</p><div class="example"><a name="ds-example"></a><p class="title"><b>Example 11.1. <code class="literal">DataSource</code> Code Example</b></p><div class="example-contents"><p>
Code to initialize a pooling <code class="classname">DataSource</code> might look like this:
</p><pre class="programlisting">
PGPoolingDataSource source = new PGPoolingDataSource();
source.setDataSourceName("A Data Source");
source.setServerName("localhost");
source.setDatabaseName("test");
source.setUser("testuser");
source.setPassword("testpassword");
source.setMaxConnections(10);
</pre><p>
Then code to use a connection from the pool might look
like this. Note that it is critical that the connections
are eventually closed. Else the pool will <span class="quote">“<span class="quote">leak</span>”</span> connections and
will eventually lock all the clients out.
</p><pre class="programlisting">
Connection conn = null;
try {
conn = source.getConnection();
// use connection
} catch (SQLException e) {
// log error
} finally {
if (con != null) {
try { conn.close(); } catch (SQLException e) {}
}
}
</pre><p>
</p></div></div><br class="example-break"></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ds-cpds.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="datasource.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="tomcat.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Application Servers: <code class="classname">ConnectionPoolDataSource</code> </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Tomcat setup</td></tr></table></div></body></html>
