Top Description Fields Constructors Methods
org.postgresql.ds

public Class PGPoolingDataSource

extends BaseDataSource
implements DataSource
Class Inheritance
All Implemented Interfaces
javax.sql.DataSource, java.sql.Wrapper, javax.sql.CommonDataSource
Known Direct Subclasses
org.postgresql.jdbc2.optional.PoolingDataSource, org.postgresql.jdbc3.Jdbc3PoolingDataSource
Annotations
@Deprecated
Static Imports
org.postgresql.util.internal.Nullness.castNonNull

Deprecated

Since 42.0.0, instead of this class you should use a fully featured connection pool like HikariCP, vibur-dbcp, commons-dbcp, c3p0, etc.

DataSource which uses connection pooling. Don't use this if your server/middleware vendor provides a connection pooling implementation which interfaces with the PostgreSQL ConnectionPoolDataSource implementation! This class is provided as a convenience, but the JDBC Driver is really not supposed to handle the connection pooling algorithm. Instead, the server or middleware product is supposed to handle the mechanics of connection pooling, and use the PostgreSQL implementation of ConnectionPoolDataSource to provide the connections to pool.

If you're sure you want to use this, then you must set the properties dataSourceName, databaseName, user, and password (if required for the user). The settings for serverName, portNumber, initialConnections, and maxConnections are optional. Note that only connections for the default user will be pooled! Connections for other users will be normal non-pooled connections, and will not count against the maximum pool size limit.

If you put this DataSource in JNDI, and access it from different JVMs (or otherwise load this class from different ClassLoaders), you'll end up with one pool per ClassLoader or VM. This is another area where a server-specific implementation may provide advanced features, such as using a single pool across all VMs in a cluster.

This implementation supports JDK 1.5 and higher.

Author
Aaron Mulder ([email protected])

Field Summary

Modifier and TypeField and Description
private final Stack<PooledConnection>
private final ConnectionEventListener
connectionEventListener

Notified when a pooled connection is closed, or a fatal error occurs on a pooled connection.

protected @Nullable String
protected static ConcurrentMap<String, PGPoolingDataSource>
private int
private boolean
private boolean
private final ResourceLock
private final Condition
private int
private @Nullable PGConnectionPoolDataSource
private final Stack<PooledConnection>

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
protected void
addDataSource(String dataSourceName)

public void
close()

Closes this DataSource, and all the pooled connections, whether in use or not.

protected PGConnectionPoolDataSource

Returns:

appropriate ConnectionPool to use for this DataSource
createConnectionPool
()

Creates the appropriate ConnectionPool to use for this DataSource.

public Connection

Returns:

A pooled connection.
getConnection
(@Nullable String
the database user on whose behalf the connection is being made
user
,
@Nullable String
the user's password
password
)

Implements javax.sql.DataSource.getConnection.

Gets a non-pooled connection, unless the user and password are the same as the default values for this connection pool.

public Connection

Returns:

A pooled connection.
getConnection
()

Overrides org.postgresql.ds.common.BaseDataSource.getConnection.

Implements javax.sql.DataSource.getConnection.

Gets a connection from the connection pool.

public static @Nullable PGPoolingDataSource
getDataSource(String name)
References Deprecated PGPoolingDataSource is deprecated or references (maybe indirectly) at least one deprecated element.

public @Nullable String

Returns:

name of this DataSource
getDataSourceName
()

Gets the name of this DataSource.

public String
getDescription()

Implements abstract org.postgresql.ds.common.BaseDataSource.getDescription.

Gets a description of this DataSource.

public int

Returns:

number of connections that will be created when this DataSource is initialized
getInitialConnections
()

Gets the number of connections that will be created when this DataSource is initialized.

public int

Returns:

The maximum number of pooled connection allowed, or 0 for no maximum.
getMaxConnections
()

Gets the maximum number of connections that the pool will allow.

private Connection
getPooledConnection()

Gets a connection from the pool.

public Reference
getReference()

Overrides org.postgresql.ds.common.BaseDataSource.getReference.

Implements javax.naming.Referenceable.getReference.

Adds custom properties for this DataSource to the properties defined in the superclass.

public void
initialize()

Initializes this DataSource.

protected boolean
public boolean
isWrapperFor(Class<?>
a Class defining an interface.
iface
)

Implements java.sql.Wrapper.isWrapperFor.

Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does.

protected void
public void
setDatabaseName(@Nullable String databaseName)

Ensures the DataSource properties are not changed after the DataSource has been used.

public void
setDataSourceName(String
datasource name
dataSourceName
)

Sets the name of this DataSource.

public void
setInitialConnections(int
number of initial connections
initialConnections
)

Sets the number of connections that will be created when this DataSource is initialized.

public void
setMaxConnections(int
The maximum number of pooled connection to allow, or 0 for no maximum.
maxConnections
)

Sets the maximum number of connections that the pool will allow.

public void
setPassword(@Nullable String password)

Ensures the DataSource properties are not changed after the DataSource has been used.

public void
setPortNumber(int
port which the PostgreSQL server is listening on for TCP/IP
portNumber
)

Overrides org.postgresql.ds.common.BaseDataSource.setPortNumber.

Ensures the DataSource properties are not changed after the DataSource has been used.

public void
setServerName(String
name of the host the PostgreSQL database is running on
serverName
)

Overrides org.postgresql.ds.common.BaseDataSource.setServerName.

Ensures the DataSource properties are not changed after the DataSource has been used.

public void
setUser(@Nullable String user)

Ensures the DataSource properties are not changed after the DataSource has been used.

public <T> T
unwrap(Class<T>
A Class defining an interface that the result must implement.
iface
)

Implements java.sql.Wrapper.unwrap.

Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy.

Inherited from org.postgresql.ds.common.BaseDataSource:
createReferencegetAdaptiveFetchgetAdaptiveFetchMaximumgetAdaptiveFetchMinimumgetAllowEncodingChangesgetApplicationNamegetAssumeMinServerVersiongetAuthenticationPluginClassNamegetAutosavegetBinaryTransfergetBinaryTransferDisablegetBinaryTransferEnablegetCancelSignalTimeoutgetCleanupSavepointsgetConnectiongetConnectTimeoutgetCurrentSchemagetDatabaseMetadataCacheFieldsgetDatabaseMetadataCacheFieldsMiBgetDatabaseNamegetDefaultRowFetchSizegetDisableColumnSanitisergetEscapeSyntaxCallModegetGroupStartupParametersgetGssEncModegetGssLibgetGssResponseTimeoutgetHideUnprivilegedObjectsgetHostRecheckSecondsgetJaasApplicationNamegetJaasLogingetKerberosServerNamegetLoadBalanceHostsgetLocalSocketAddressgetLoggerFilegetLoggerLevelgetLoginTimeoutgetLogServerErrorDetailgetLogUnclosedConnectionsgetLogWritergetMaxResultBuffergetOptionsgetParentLoggergetPasswordgetPortNumbergetPortNumbersgetPreferQueryModegetPreparedStatementCacheQueriesgetPreparedStatementCacheSizeMiBgetPrepareThresholdgetPropertygetPropertygetProtocolVersiongetQuoteReturningIdentifiersgetReadOnlygetReadOnlyModegetReceiveBufferSizegetRecvBufferSizegetReplicationgetReWriteBatchedInsertsgetSendBufferSizegetServerNamegetServerNamesgetSocketFactorygetSocketFactoryArggetSocketTimeoutgetSslgetSslCertgetSslcertgetSslfactorygetSslFactoryArggetSslfactoryarggetSslHostnameVerifiergetSslhostnameverifiergetSslKeygetSslkeygetSslModegetSslmodegetSslPasswordgetSslpasswordgetSslPasswordCallbackgetSslpasswordcallbackgetSslResponseTimeoutgetSslRootCertgetSslrootcertgetSspiServiceClassgetStringTypegetTargetServerTypegetTcpKeepAlivegetTcpNoDelaygetUnknownLengthgetUrlgetURLgetUsergetUseSpNegogetXmlFactoryFactoryinitializeFromisAllowEncodingChangesisCleanupSavePointsisColumnSanitiserDisabledisDisableColumnSanitiserisLoadBalanceHostsisLogUnclosedConnectionsisReadOnlyisReWriteBatchedInsertsisSslisTcpKeepAlivereadBaseObjectsetAdaptiveFetchsetAdaptiveFetchMaximumsetAdaptiveFetchMinimumsetAllowEncodingChangessetApplicationNamesetAssumeMinServerVersionsetAuthenticationPluginClassNamesetAutosavesetBinaryTransfersetBinaryTransferDisablesetBinaryTransferEnablesetCancelSignalTimeoutsetCleanupSavepointssetCleanupSavePointssetConnectTimeoutsetCurrentSchemasetDatabaseMetadataCacheFieldssetDatabaseMetadataCacheFieldsMiBsetDatabaseNamesetDefaultRowFetchSizesetDisableColumnSanitisersetEscapeSyntaxCallModesetFromReferencesetGroupStartupParameterssetGssEncModesetGssLibsetGssResponseTimeoutsetHideUnprivilegedObjectssetHostRecheckSecondssetJaasApplicationNamesetJaasLoginsetKerberosServerNamesetLoadBalanceHostssetLocalSocketAddresssetLoggerFilesetLoggerLevelsetLoginTimeoutsetLogServerErrorDetailsetLogUnclosedConnectionssetLogWritersetMaxResultBuffersetOptionssetPasswordsetPortNumberssetPreferQueryModesetPreparedStatementCacheQueriessetPreparedStatementCacheSizeMiBsetPrepareThresholdsetPropertysetPropertysetProtocolVersionsetQuoteReturningIdentifierssetReadOnlysetReadOnlyModesetReceiveBufferSizesetRecvBufferSizesetReplicationsetReWriteBatchedInsertssetSendBufferSizesetServerNamessetSocketFactorysetSocketFactoryArgsetSocketTimeoutsetSslsetSslCertsetSslcertsetSslfactorysetSslFactoryArgsetSslfactoryargsetSslHostnameVerifiersetSslhostnameverifiersetSslKeysetSslkeysetSslModesetSslmodesetSslPasswordsetSslpasswordsetSslPasswordCallbacksetSslpasswordcallbacksetSslResponseTimeoutsetSslRootCertsetSslrootcertsetSspiServiceClasssetStringTypesetTargetServerTypesetTcpKeepAlivesetTcpNoDelaysetUnknownLengthsetUrlsetURLsetUsersetUseSpNegosetXmlFactoryFactorywriteBaseObject

Field Detail

availableback to summary
private final Stack<PooledConnection> available
connectionEventListenerback to summary
private final ConnectionEventListener connectionEventListener

Notified when a pooled connection is closed, or a fatal error occurs on a pooled connection. This is the only way connections are marked as unused.

dataSourceNameback to summary
protected @Nullable String dataSourceName
dataSourcesback to summary
protected static ConcurrentMap<String, PGPoolingDataSource> dataSources
initialConnectionsback to summary
private int initialConnections
initializedback to summary
private boolean initialized
isClosedback to summary
private boolean isClosed
lockback to summary
private final ResourceLock lock
lockConditionback to summary
private final Condition lockCondition
maxConnectionsback to summary
private int maxConnections
sourceback to summary
private @Nullable PGConnectionPoolDataSource source
usedback to summary
private final Stack<PooledConnection> used

Constructor Detail

PGPoolingDataSourceback to summary
public PGPoolingDataSource()

Method Detail

addDataSourceback to summary
protected void addDataSource(String dataSourceName)
closeback to summary
public void close()

Closes this DataSource, and all the pooled connections, whether in use or not.

createConnectionPoolback to summary
protected PGConnectionPoolDataSource createConnectionPool()

Creates the appropriate ConnectionPool to use for this DataSource.

Returns:PGConnectionPoolDataSource

appropriate ConnectionPool to use for this DataSource

getConnectionback to summary
public Connection getConnection(@Nullable String user, @Nullable String password) throws SQLException

Implements javax.sql.DataSource.getConnection.

Gets a non-pooled connection, unless the user and password are the same as the default values for this connection pool.

Parameters
user:@Nullable String

Doc from javax.sql.DataSource.getConnection.

the database user on whose behalf the connection is being made

password:@Nullable String

Doc from javax.sql.DataSource.getConnection.

the user's password

Returns:Connection

A pooled connection.

Annotations
@Override
Exceptions
SQLException:
Occurs when no pooled connection is available, and a new physical connection cannot be created.
getConnectionback to summary
public Connection getConnection() throws SQLException

Overrides org.postgresql.ds.common.BaseDataSource.getConnection.

Implements javax.sql.DataSource.getConnection.

Gets a connection from the connection pool.

Returns:Connection

A pooled connection.

Annotations
@Override
Exceptions
SQLException:
Occurs when no pooled connection is available, and a new physical connection cannot be created.
getDataSourceback to summary
public static @Nullable PGPoolingDataSource getDataSource(String name)

References Deprecated

PGPoolingDataSource is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

getDataSourceNameback to summary
public @Nullable String getDataSourceName()

Gets the name of this DataSource. This uniquely identifies the DataSource. You cannot use more than one DataSource in the same VM with the same name.

Returns:@Nullable String

name of this DataSource

getDescriptionback to summary
public String getDescription()

Implements abstract org.postgresql.ds.common.BaseDataSource.getDescription.

Gets a description of this DataSource.

Returns:String

Doc from org.postgresql.ds.common.BaseDataSource.getDescription.

description of this DataSource-ish thing

Annotations
@Override
getInitialConnectionsback to summary
public int getInitialConnections()

Gets the number of connections that will be created when this DataSource is initialized. If you do not call initialize explicitly, it will be initialized the first time a connection is drawn from it.

Returns:int

number of connections that will be created when this DataSource is initialized

getMaxConnectionsback to summary
public int getMaxConnections()

Gets the maximum number of connections that the pool will allow. If a request comes in and this many connections are in use, the request will block until a connection is available. Note that connections for a user other than the default user will not be pooled and don't count against this limit.

Returns:int

The maximum number of pooled connection allowed, or 0 for no maximum.

getPooledConnectionback to summary
private Connection getPooledConnection() throws SQLException

Gets a connection from the pool. Will get an available one if present, or create a new one if under the max limit. Will block if all used and a new one would exceed the max.

getReferenceback to summary
public Reference getReference() throws NamingException

Overrides org.postgresql.ds.common.BaseDataSource.getReference.

Implements javax.naming.Referenceable.getReference.

Adds custom properties for this DataSource to the properties defined in the superclass.

Returns:Reference

Doc from javax.naming.Referenceable.getReference.

The non-null Reference of this object.

Annotations
@Override
Exceptions
NamingException:

Doc from javax.naming.Referenceable.getReference.

If a naming exception was encountered while retrieving the reference.

initializeback to summary
public void initialize() throws SQLException

Initializes this DataSource. If the initialConnections is greater than zero, that number of connections will be created. After this method is called, the DataSource properties cannot be changed. If you do not call this explicitly, it will be called the first time you get a connection from the DataSource.

Exceptions
SQLException:
Occurs when the initialConnections is greater than zero, but the DataSource is not able to create enough physical connections.
isInitializedback to summary
protected boolean isInitialized()
isWrapperForback to summary
public boolean isWrapperFor(Class<?> iface) throws SQLException

Implements java.sql.Wrapper.isWrapperFor.

Doc from java.sql.Wrapper.isWrapperFor.

Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does. Returns false otherwise. If this implements the interface then return true, else if this is a wrapper then return the result of recursively calling isWrapperFor on the wrapped object. If this does not implement the interface and is not a wrapper, return false. This method should be implemented as a low-cost operation compared to unwrap so that callers can use this method to avoid expensive unwrap calls that may fail. If this method returns true then calling unwrap with the same argument should succeed.

Parameters
iface:Class<?>

a Class defining an interface.

Returns:boolean

true if this implements the interface or directly or indirectly wraps an object that does.

Annotations
@Override
Exceptions
SQLException:
if an error occurs while determining whether this is a wrapper for an object with the given interface.
removeStoredDataSourceback to summary
protected void removeStoredDataSource()
setDatabaseNameback to summary
public void setDatabaseName(@Nullable String databaseName)

Ensures the DataSource properties are not changed after the DataSource has been used.

Annotations
@Override
Exceptions
IllegalStateException:
The Database Name cannot be changed after the DataSource has been used.
setDataSourceNameback to summary
public void setDataSourceName(String dataSourceName)

Sets the name of this DataSource. This is required, and uniquely identifies the DataSource. You cannot create or use more than one DataSource in the same VM with the same name.

Parameters
dataSourceName:String

datasource name

Exceptions
IllegalStateException:
The Data Source Name cannot be changed after the DataSource has been used.
IllegalArgumentException:
Another PoolingDataSource with the same dataSourceName already exists.
setInitialConnectionsback to summary
public void setInitialConnections(int initialConnections)

Sets the number of connections that will be created when this DataSource is initialized. If you do not call initialize explicitly, it will be initialized the first time a connection is drawn from it.

Parameters
initialConnections:int

number of initial connections

Exceptions
IllegalStateException:
The Initial Connections cannot be changed after the DataSource has been used.
setMaxConnectionsback to summary
public void setMaxConnections(int maxConnections)

Sets the maximum number of connections that the pool will allow. If a request comes in and this many connections are in use, the request will block until a connection is available. Note that connections for a user other than the default user will not be pooled and don't count against this limit.

Parameters
maxConnections:int

The maximum number of pooled connection to allow, or 0 for no maximum.

Exceptions
IllegalStateException:
The Maximum Connections cannot be changed after the DataSource has been used.
setPasswordback to summary
public void setPassword(@Nullable String password)

Ensures the DataSource properties are not changed after the DataSource has been used.

Annotations
@Override
Exceptions
IllegalStateException:
The Password cannot be changed after the DataSource has been used.
setPortNumberback to summary
public void setPortNumber(int portNumber)

Overrides org.postgresql.ds.common.BaseDataSource.setPortNumber.

Ensures the DataSource properties are not changed after the DataSource has been used.

Parameters
portNumber:int

Doc from org.postgresql.ds.common.BaseDataSource.setPortNumber.

port which the PostgreSQL server is listening on for TCP/IP

Annotations
@Override
Exceptions
IllegalStateException:
The Port Number cannot be changed after the DataSource has been used.
setServerNameback to summary
public void setServerName(String serverName)

Overrides org.postgresql.ds.common.BaseDataSource.setServerName.

Ensures the DataSource properties are not changed after the DataSource has been used.

Parameters
serverName:String

Doc from org.postgresql.ds.common.BaseDataSource.setServerName.

name of the host the PostgreSQL database is running on

Annotations
@Override
Exceptions
IllegalStateException:
The Server Name cannot be changed after the DataSource has been used.
setUserback to summary
public void setUser(@Nullable String user)

Ensures the DataSource properties are not changed after the DataSource has been used.

Annotations
@Override
Exceptions
IllegalStateException:
The User cannot be changed after the DataSource has been used.
unwrapback to summary
public <T> T unwrap(Class<T> iface) throws SQLException

Implements java.sql.Wrapper.unwrap.

Doc from java.sql.Wrapper.unwrap.

Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy. If the receiver implements the interface then the result is the receiver or a proxy for the receiver. If the receiver is a wrapper and the wrapped object implements the interface then the result is the wrapped object or a proxy for the wrapped object. Otherwise return the the result of calling unwrap recursively on the wrapped object or a proxy for that result. If the receiver is not a wrapper and does not implement the interface, then an SQLException is thrown.

Parameters
<T>
the type of the class modeled by this Class object
iface:Class<T>

A Class defining an interface that the result must implement.

Returns:T

an object that implements the interface. May be a proxy for the actual implementing object.

Annotations
@Override
Exceptions
SQLException:
If no object found that implements the interface