org.postgresql.ds

Class PGPoolingDataSource

java.lang.Object

org.postgresql.ds.common.BaseDataSource

org.postgresql.ds.PGPoolingDataSource

All Implemented Interfaces:

Wrapper, Referenceable, CommonDataSource, DataSource

Direct Known Subclasses:

Jdbc3PoolingDataSource, PoolingDataSource

public class PGPoolingDataSource
extends BaseDataSource
implements DataSource

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.3 and higher.

Author:

Aaron Mulder (ammulder@chariotsolutions.com)

Field Summary

Fields

Modifier and Type	Field and Description
protected String	dataSourceName
protected static Map	dataSources

Constructor Summary

Constructors

Constructor and Description
PGPoolingDataSource()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addDataSource(String dataSourceName)
void	close() Closes this DataSource, and all the pooled connections, whether in use or not.
protected PGConnectionPoolDataSource	createConnectionPool() Creates the appropriate ConnectionPool to use for this DataSource.
Connection	getConnection() Gets a connection from the connection pool.
Connection	getConnection(String user, String password) Gets a non-pooled connection, unless the user and password are the same as the default values for this connection pool.
static PGPoolingDataSource	getDataSource(String name)
String	getDataSourceName() Gets the name of this DataSource.
String	getDescription() Gets a description of this DataSource.
int	getInitialConnections() Gets the number of connections that will be created when this DataSource is initialized.
int	getMaxConnections() Gets the maximum number of connections that the pool will allow.
Logger	getParentLogger() Return the parent Logger of all the Loggers used by this data source.
Reference	getReference() Adds custom properties for this DataSource to the properties defined in the superclass.
void	initialize() Initializes this DataSource.
protected boolean	isInitialized()
boolean	isWrapperFor(Class<?> iface) Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does.
protected void	removeStoredDataSource()
void	setDatabaseName(String databaseName) Ensures the DataSource properties are not changed after the DataSource has been used.
void	setDataSourceName(String dataSourceName) Sets the name of this DataSource.
void	setInitialConnections(int initialConnections) Sets the number of connections that will be created when this DataSource is initialized.
void	setMaxConnections(int maxConnections) Sets the maximum number of connections that the pool will allow.
void	setPassword(String password) Ensures the DataSource properties are not changed after the DataSource has been used.
void	setPortNumber(int portNumber) Ensures the DataSource properties are not changed after the DataSource has been used.
void	setServerName(String serverName) Ensures the DataSource properties are not changed after the DataSource has been used.
void	setUser(String user) Ensures the DataSource properties are not changed after the DataSource has been used.
<T> T	unwrap(Class<T> iface) Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy.

Methods inherited from class org.postgresql.ds.common.BaseDataSource

createReference, getAllowEncodingChanges, getApplicationName, getAssumeMinServerVersion, getBinaryTransfer, getBinaryTransferDisable, getBinaryTransferEnable, getCharset, getCompatible, getConnectTimeout, getCurrentSchema, getDatabaseName, getDefaultRowFetchSize, getDisableColumnSanitiser, getGssLib, getHostRecheckSeconds, getJaasApplicationName, getKerberosServerName, getLoadBalanceHosts, getLoginTimeout, getLoglevel, getLogLevel, getLogUnclosedConnections, getLogWriter, getPassword, getPortNumber, getPreparedStatementCacheQueries, getPreparedStatementCacheSizeMiB, getPrepareThreshold, getProperty, getProperty, getProtocolVersion, getReadOnly, getReceiveBufferSize, getSendBufferSize, getServerName, getSocketTimeout, getSsl, getSslCert, getSslfactory, getSslFactoryArg, getSslHostnameVerifier, getSslKey, getSslMode, getSslPassword, getSslPasswordCallback, getSslRootCert, getSspiServiceClass, getStringType, getTargetServerType, getTcpKeepAlive, getUnknownLength, getUrl, getUser, getUseSpNego, initializeFrom, isColumnSanitiserDisabled, readBaseObject, setAllowEncodingChanges, setApplicationName, setAssumeMinServerVersion, setBinaryTransfer, setBinaryTransferDisable, setBinaryTransferEnable, setCharset, setCompatible, setConnectTimeout, setCurrentSchema, setDefaultRowFetchSize, setDisableColumnSanitiser, setFromReference, setGssLib, setHostRecheckSeconds, setJaasApplicationName, setKerberosServerName, setLoadBalanceHosts, setLoginTimeout, setLoglevel, setLogLevel, setLogUnclosedConnections, setLogWriter, setPreparedStatementCacheQueries, setPreparedStatementCacheSizeMiB, setPrepareThreshold, setProperty, setProperty, setProtocolVersion, setReadOnly, setReceiveBufferSize, setSendBufferSize, setSocketTimeout, setSsl, setSslCert, setSslfactory, setSslFactoryArg, setSslHostnameVerifier, setSslKey, setSslMode, setSslPassword, setSslPasswordCallback, setSslRootCert, setSspiServiceClass, setStringType, setTargetServerType, setTcpKeepAlive, setUnknownLength, setUrl, setUseSpNego, writeBaseObject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.sql.CommonDataSource

getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter

Field Detail

dataSources

protected static Map dataSources

dataSourceName

protected String dataSourceName

Constructor Detail

PGPoolingDataSource

public PGPoolingDataSource()

Method Detail

getDataSource

public static PGPoolingDataSource getDataSource(String name)

getDescription

public String getDescription()

Gets a description of this DataSource.

Specified by:

getDescription in class BaseDataSource

Returns:

description of this DataSource-ish thing

setServerName

public void setServerName(String serverName)

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

Overrides:

setServerName in class BaseDataSource

Parameters:

serverName - name of the host the PostgreSQL database is running on

Throws:

IllegalStateException - The Server Name cannot be changed after the DataSource has been used.

setDatabaseName

public void setDatabaseName(String databaseName)

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

Overrides:

setDatabaseName in class BaseDataSource

Parameters:

databaseName - name of the PostgreSQL database

Throws:

IllegalStateException - The Database Name cannot be changed after the DataSource has been used.

setUser

public void setUser(String user)

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

Overrides:

setUser in class BaseDataSource

Parameters:

user - user to connect as by default

Throws:

IllegalStateException - The User cannot be changed after the DataSource has been used.

setPassword

public void setPassword(String password)

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

Overrides:

setPassword in class BaseDataSource

Parameters:

password - password to connect with by default

Throws:

IllegalStateException - The Password cannot be changed after the DataSource has been used.

setPortNumber

public void setPortNumber(int portNumber)

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

Overrides:

setPortNumber in class BaseDataSource

Parameters:

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

Throws:

IllegalStateException - The Port Number cannot be changed after the DataSource has been used.

getInitialConnections

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:

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

setInitialConnections

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 - number of initial connections

Throws:

IllegalStateException - The Initial Connections cannot be changed after the DataSource has been used.

getMaxConnections

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:

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

setMaxConnections

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 - The maximum number of pooled connection to allow, or 0 for no maximum.

Throws:

IllegalStateException - The Maximum Connections cannot be changed after the DataSource has been used.

getDataSourceName

public 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:

name of this DataSource

setDataSourceName

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 - datasource name

Throws:

IllegalStateException - The Data Source Name cannot be changed after the DataSource has been used.

IllegalArgumentException - Another PoolingDataSource with the same dataSourceName already exists.

initialize

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.

Throws:

SQLException - Occurs when the initialConnections is greater than zero, but the DataSource is not able to create enough physical connections.

isInitialized

protected boolean isInitialized()

createConnectionPool

protected PGConnectionPoolDataSource createConnectionPool()

Creates the appropriate ConnectionPool to use for this DataSource.

Returns:

appropriate ConnectionPool to use for this DataSource

getConnection

public Connection getConnection(String user,
                       String password)
                         throws SQLException

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

Specified by:

getConnection in interface DataSource

Overrides:

getConnection in class BaseDataSource

Parameters:

user - user

password - password

Returns:

A pooled connection.

Throws:

SQLException - Occurs when no pooled connection is available, and a new physical connection cannot be created.

getConnection

public Connection getConnection()
                         throws SQLException

Gets a connection from the connection pool.

Specified by:

getConnection in interface DataSource

Overrides:

getConnection in class BaseDataSource

Returns:

A pooled connection.

Throws:

SQLException - Occurs when no pooled connection is available, and a new physical connection cannot be created.

close

public void close()

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

removeStoredDataSource

protected void removeStoredDataSource()

addDataSource

protected void addDataSource(String dataSourceName)

getReference

public Reference getReference()
                       throws NamingException

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

Specified by:

getReference in interface Referenceable

Overrides:

getReference in class BaseDataSource

Returns:

The non-null Reference of this object.

Throws:

NamingException - If a naming exception was encountered while retrieving the reference.

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
                     throws SQLException

Description copied from interface: java.sql.Wrapper

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.

Specified by:

isWrapperFor in interface Wrapper

Parameters:

iface - a Class defining an interface.

Returns:

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

Throws:

SQLException - if an error occurs while determining whether this is a wrapper for an object with the given interface.

unwrap

public <T> T unwrap(Class<T> iface)
         throws SQLException

Description copied from interface: java.sql.Wrapper

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.

Specified by:

unwrap in interface Wrapper

Parameters:

iface - A Class defining an interface that the result must implement.

Returns:

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

Throws:

SQLException - If no object found that implements the interface

getParentLogger

public Logger getParentLogger()
                       throws SQLFeatureNotSupportedException

Description copied from interface: javax.sql.CommonDataSource

Return the parent Logger of all the Loggers used by this data source. This should be the Logger farthest from the root Logger that is still an ancestor of all of the Loggers used by this data source. Configuring this Logger will affect all of the log messages generated by the data source. In the worst case, this may be the root Logger.

Specified by:

getParentLogger in interface CommonDataSource

Returns:

the parent Logger for this data source

Throws:

SQLFeatureNotSupportedException - if the data source does not use java.util.logging.