com.ibm.as400.access
Class AS400JDBCManagedConnectionPoolDataSource

java.lang.Object
  extended by com.ibm.as400.access.AS400JDBCManagedDataSource
      extended by com.ibm.as400.access.AS400JDBCManagedConnectionPoolDataSource
All Implemented Interfaces:
Serializable, Cloneable, Wrapper, Referenceable, CommonDataSource, ConnectionPoolDataSource, DataSource

public class AS400JDBCManagedConnectionPoolDataSource
extends AS400JDBCManagedDataSource
implements ConnectionPoolDataSource, Referenceable, Serializable

This implementation of javax.sql.ConnectionPoolDataSource can be used in conjunction with AS400JDBCManagedDataSource to produce PooledConnection objects (AS400JDBCPooledConnection) that are managed by the Toolbox's built-in connection pooling manager.

A ConnectionPoolDataSource is a factory for PooledConnection objects. An object that implements the ConnectionPoolDataSource interface will typically be registered with a naming service that is based on the Java Naming and Directory Interface (JNDI).

The operations on a ConnectionPoolDataSource class are completely internal to a driver implementation; the ConnectionPoolDataSource interface is not part of the API typically used by Java application programmers. Driver vendors use it in their implementation of connection pooling. Application programmers specify a DataSource class in their code to get a connection. However, since users/database administrators must register the corresponding ConnectionPoolDataSource with JNDI, the class needs to be public. Users must be able to call the different getters/setters to set up their connection pooling environment when they register the ConnectionPoolDataSource. Drivers then provide DataSource classes that implement javax.sql.DataSource, and the user will use this data source in their code.

Design note: This class extends AS400JDBCManagedDataSource, solely in order to exploit shared implementation. This class should not be used as a "kind of" AS400JDBCManagedDataSource.

Caution: To avoid the pitfalls of "double-managed" pools, do not use this class in conjunction with a separate connection pool manager, such as that available in WebSphere. When a separate pool manager is provided, use AS400JDBCConnectionPoolDataSource instead.

See Also:
AS400JDBCDataSource, AS400JDBCConnectionPoolDataSource, AS400JDBCXADataSource, Serialized Form

Field Summary
 
Fields inherited from class com.ibm.as400.access.AS400JDBCManagedDataSource
MAX_STORAGE_LIMIT, SERVER_TRACE_DEBUG_SERVER_JOB, SERVER_TRACE_SAVE_SERVER_JOBLOG, SERVER_TRACE_SAVE_SQL_INFORMATION, SERVER_TRACE_START_DATABASE_MONITOR, SERVER_TRACE_TRACE_SERVER_JOB
 
Constructor Summary
AS400JDBCManagedConnectionPoolDataSource()
          Constructs a default AS400JDBCManagedConnectionPoolDataSource object.
AS400JDBCManagedConnectionPoolDataSource(String serverName)
          Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified serverName.
AS400JDBCManagedConnectionPoolDataSource(String serverName, String user, String password)
          Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified signon information.
AS400JDBCManagedConnectionPoolDataSource(String serverName, String user, String password, String keyRingName, String keyRingPassword)
          Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified signon information to use for SSL communications with the IBM i system.
 
Method Summary
 boolean checkPoolHealth(boolean logStatistics)
          Deprecated. Use checkPoolHealth() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.
 void closePool()
          Deprecated. Use closePool() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.
 Connection getConnection()
          Deprecated. Use getConnection() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.
 Connection getConnection(String user, String password)
          Deprecated. Use getConnection() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.
 int getInitialPoolSize()
          Returns the number of physical connections the connection pool should contain when it is created.
 int getMaxIdleTime()
          Returns the amount of time (in seconds) after which an available pooled physical connection is considered "stale" and should be closed.
 int getMaxLifetime()
          Returns the maximum amount of time (in seconds) after which a physical connection is considered to be expired and should be closed.
 int getMaxPoolSize()
          Returns the maximum number of physical connections that the connection pool contains.
 int getMinPoolSize()
          Returns the minimum number of physical connections that the connection pool contains.
 PooledConnection getPooledConnection()
          Returns a pooled connection that is connected to the IBM i system.
 PooledConnection getPooledConnection(String user, String password)
          Returns a pooled connection that is connected to the IBM i system.
 int getPropertyCycle()
          Returns the interval (in seconds) between runs of the connection pool's maintenance thread.
 Reference getReference()
          Returns a Reference object for the data source object.
 boolean isEnforceMaxPoolSize()
          Indicates whether pool size restriction should be strictly enforced.
 boolean isPretestConnections()
          Indicates whether connections are pretested before being allocated to a requester.
 boolean isReuseConnections()
          Indicates whether connections are re-used after being returned to the connection pool.
 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.
 void setEnforceMaxPoolSize(boolean enforce)
          Sets whether pool size restriction should be strictly enforced.
 void setInitialPoolSize(int initialPoolSize)
          Sets the number of connections that the connection pool contains when it is created.
 void setMaxIdleTime(int maxIdleTime)
          Sets the maximum amount of time (in seconds) that a pooled connection in this pool is allowed to remain idle before it is automatically closed.
 void setMaxLifetime(int maxLifetime)
          Sets the maximum amount of time (in seconds) after which an in-use physical connection is considered to be expired and should be closed.
 void setMaxPoolSize(int maxPoolSize)
          Sets the maximum number of connections that the connection pool contains.
 void setMinPoolSize(int minPoolSize)
          Sets the minimum number of connections that the connection pool contains.
 void setPretestConnections(boolean pretest)
          Sets whether connections are pretested before being allocated to requesters.
 void setPropertyCycle(int propertyCycle)
          Sets the interval (in seconds) between runs of the connection pool's maintenance thread.
 void setReuseConnections(boolean reuse)
          Sets whether connections may be re-used after being returned to the connection pool.
<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 com.ibm.as400.access.AS400JDBCManagedDataSource
clone, getAccess, getBehaviorOverride, getBidiStringType, getBlockCriteria, getBlockSize, getConcurrentAccessResolution, getCursorSensitivity, getDatabaseName, getDataSourceName, getDateFormat, getDateSeparator, getDecfloatRoundingMode, getDecimalSeparator, getDescription, getDriver, getErrors, getIgnoreWarnings, getLibraries, getLobThreshold, getLoginTimeout, getLogWriter, getMaximumBlockedInputRows, getMaximumPrecision, getMaximumScale, getMetadataSource, getMetaDataSource, getMinimumDivideScale, getNaming, getPackage, getPackageCcsid, getPackageCCSID, getPackageCriteria, getPackageError, getPackageLibrary, getProxyServer, getQaqqinilib, getQaqqiniLibrary, getQueryOptimizeGoal, getQueryStorageLimit, getReceiveBufferSize, getRemarks, getSecondaryUrl, getSecondaryURL, getSendBufferSize, getServerName, getServerTrace, getServerTraceCategories, getSocketTimeout, getSoLinger, getSort, getSortLanguage, getSortTable, getSortWeight, getSoTimeout, getTimeFormat, getTimeSeparator, getToolboxTrace, getToolboxTraceCategory, getTransactionIsolation, getTranslateHex, getUser, getValidWrappedList, getXALooselyCoupledSupport, invalidate, isAutoCommit, isAutocommitException, isBidiImplicitReordering, isBidiNumericOrdering, isBigDecimal, isCursorHold, isDataCompression, isDataTruncation, isExtendedDynamic, isExtendedMetadata, isExtendedMetaData, isFullOpen, isHoldInputLocators, isHoldStatements, isJvm16Synchronize, isKeepAlive, isLazyClose, isPackageAdd, isPackageCache, isPackageClear, isPrefetch, isPrompt, isRollbackCursorHold, isSavePasswordWhenSerialized, isSecure, isSecureCurrentUser, isTcpNoDelay, isThreadUsed, isTrace, isTranslateBinary, isTranslateBoolean, isTrueAutocommit, isTrueAutoCommit, setAccess, setAutoCommit, setAutocommitException, setBehaviorOverride, setBidiImplicitReordering, setBidiNumericOrdering, setBidiStringType, setBigDecimal, setBlockCriteria, setBlockSize, setConcurrentAccessResolution, setCursorHold, setCursorSensitivity, setDatabaseName, setDataCompression, setDataSourceName, setDataTruncation, setDateFormat, setDateSeparator, setDecfloatRoundingMode, setDecimalSeparator, setDescription, setDriver, setErrors, setExtendedDynamic, setExtendedMetadata, setExtendedMetaData, setFullOpen, setHoldInputLocators, setHoldStatements, setIgnoreWarnings, setJvm16Synchronize, setKeepAlive, setLazyClose, setLibraries, setLobThreshold, setLoginTimeout, setLogWriter, setMaximumBlockedInputRows, setMaximumPrecision, setMaximumScale, setMetadataSource, setMetaDataSource, setMinimumDivideScale, setNaming, setPackage, setPackageAdd, setPackageCache, setPackageCcsid, setPackageCCSID, setPackageClear, setPackageCriteria, setPackageError, setPackageLibrary, setPassword, setPrefetch, setPrompt, setProperties, setProperties, setProxyServer, setQaqqinilib, setQaqqiniLibrary, setQueryOptimizeGoal, setQueryStorageLimit, setReceiveBufferSize, setRemarks, setRollbackCursorHold, setSavePasswordWhenSerialized, setSecondaryUrl, setSecondaryURL, setSecure, setSecureCurrentUser, setSendBufferSize, setServerName, setServerTrace, setServerTraceCategories, setSocketTimeout, setSoLinger, setSort, setSortLanguage, setSortTable, setSortWeight, setSoTimeout, setTcpNoDelay, setThreadUsed, setTimeFormat, setTimeSeparator, setToolboxTrace, setToolboxTraceCategory, setTrace, setTransactionIsolation, setTranslateBinary, setTranslateBoolean, setTranslateHex, setTrueAutocommit, setTrueAutoCommit, setUser, setXALooselyCoupledSupport, toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.sql.CommonDataSource
getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter
 
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
 

Constructor Detail

AS400JDBCManagedConnectionPoolDataSource

public AS400JDBCManagedConnectionPoolDataSource()
Constructs a default AS400JDBCManagedConnectionPoolDataSource object.


AS400JDBCManagedConnectionPoolDataSource

public AS400JDBCManagedConnectionPoolDataSource(String serverName)
Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified serverName.

Parameters:
serverName - The IBM i system name.

AS400JDBCManagedConnectionPoolDataSource

public AS400JDBCManagedConnectionPoolDataSource(String serverName,
                                                String user,
                                                String password)
Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified signon information.

Parameters:
serverName - The IBM i system name.
user - The user id.
password - The password.

AS400JDBCManagedConnectionPoolDataSource

public AS400JDBCManagedConnectionPoolDataSource(String serverName,
                                                String user,
                                                String password,
                                                String keyRingName,
                                                String keyRingPassword)
Constructs an AS400JDBCManagedConnectionPoolDataSource with the specified signon information to use for SSL communications with the IBM i system.

Parameters:
serverName - The IBM i system name.
user - The user id.
password - The password.
keyRingName - The key ring class name to be used for SSL communications with the system.
keyRingPassword - The password for the key ring class to be used for SSL communications with the system.
Method Detail

checkPoolHealth

public boolean checkPoolHealth(boolean logStatistics)
Deprecated. Use checkPoolHealth() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.

Prints a warning and calls the superclass's method. Users are discouraged from calling this method.

Overrides:
checkPoolHealth in class AS400JDBCManagedDataSource
Parameters:
logStatistics - If true, additional information is logged.
Returns:
true if connection pool exists and appears healthy; false otherwise.

closePool

public void closePool()
Deprecated. Use closePool() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.

Prints a warning and calls the superclass's method. Users are discouraged from calling this method.

Overrides:
closePool in class AS400JDBCManagedDataSource

getConnection

public Connection getConnection()
                         throws SQLException
Deprecated. Use getConnection() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.

Prints a warning and calls the superclass's method. Users are discouraged from calling this method.

Specified by:
getConnection in interface DataSource
Overrides:
getConnection in class AS400JDBCManagedDataSource
Returns:
The connection.
Throws:
SQLException - If a database error occurs.
See Also:
AS400JDBCManagedDataSource.setDataSourceName(java.lang.String)

getConnection

public Connection getConnection(String user,
                                String password)
                         throws SQLException
Deprecated. Use getConnection() instead. Refer to the class overview for a discussion of the intended role of this class, and the relationship between this class and its superclass.

Prints a warning and calls the superclass's method. Users are discouraged from calling this method.

Specified by:
getConnection in interface DataSource
Overrides:
getConnection in class AS400JDBCManagedDataSource
Parameters:
user - The database user.
password - The database password.
Returns:
The connection
Throws:
SQLException - If a database error occurs.
See Also:
AS400JDBCManagedDataSource.setDataSourceName(java.lang.String)

getInitialPoolSize

public int getInitialPoolSize()
Returns the number of physical connections the connection pool should contain when it is created.

Returns:
The initial number of pooled connections. The default value is 5.

getMaxIdleTime

public int getMaxIdleTime()
Returns the amount of time (in seconds) after which an available pooled physical connection is considered "stale" and should be closed. A value of 0 indicates pooled connections are never automatically closed.

Returns:
The maximum idle time for a pooled connection, in seconds. The default value is 1 hour.

getMaxLifetime

public int getMaxLifetime()
Returns the maximum amount of time (in seconds) after which a physical connection is considered to be expired and should be closed. A value of 0 indicates in-use connections are never automatically closed.

Returns:
The maximum lifetime for an in-use connection, in seconds. The default value is 24 hours.

getMaxPoolSize

public int getMaxPoolSize()
Returns the maximum number of physical connections that the connection pool contains. A value of 0 indicates there is no maximum.

Returns:
The maximum number of connections in the pool. The default value is 0 (no maximum).

getMinPoolSize

public int getMinPoolSize()
Returns the minimum number of physical connections that the connection pool contains. A value of 0 indicates there is no minimum and connections are created as they are needed.

Returns:
The minimum number of available connections in the pool. The default value is 0.

getPooledConnection

public PooledConnection getPooledConnection()
                                     throws SQLException
Returns a pooled connection that is connected to the IBM i system.

Specified by:
getPooledConnection in interface ConnectionPoolDataSource
Returns:
A pooled connection.
Throws:
SQLException - If a database error occurs.

getPooledConnection

public PooledConnection getPooledConnection(String user,
                                            String password)
                                     throws SQLException
Returns a pooled connection that is connected to the IBM i system.

Specified by:
getPooledConnection in interface ConnectionPoolDataSource
Parameters:
user - The userid for the connection.
password - The password for the connection.
Returns:
A pooled connection.
Throws:
SQLException - If a database error occurs.

getPropertyCycle

public int getPropertyCycle()
Returns the interval (in seconds) between runs of the connection pool's maintenance thread. The maintenance thread enforces this pool's connections and statements so that they conform to the specified minimum and maximum pool sizes, idle time, and maximum number of open statements.

Returns:
The number of seconds that this pool should wait before enforcing its properties. The default value is 5 minutes.

getReference

public Reference getReference()
                       throws NamingException
Returns a Reference object for the data source object. This is used by JNDI when bound in a JNDI naming service. Contains the information necessary to reconstruct the data source object when it is later retrieved from JNDI via an object factory.

Specified by:
getReference in interface Referenceable
Overrides:
getReference in class AS400JDBCManagedDataSource
Returns:
A Reference object for the data source object.
Throws:
NamingException - If a naming error occurs resolving the object.

isEnforceMaxPoolSize

public boolean isEnforceMaxPoolSize()
Indicates whether pool size restriction should be strictly enforced. If set to true, and a connection is requested from the pool when the pool is at its maximum size limit and no connections are available, then an exception will be thrown. If set to false, then a warning will be traced, and a new (unpooled) physical connection will be returned.

Returns:
true if the pool size restriction should be strictly enforced; false otherwise. The default value is false.
See Also:
setMaxPoolSize(int)

isPretestConnections

public boolean isPretestConnections()
Indicates whether connections are pretested before being allocated to a requester.

Returns:
true if connections are pretested; false otherwise. The default value is false.

isReuseConnections

public boolean isReuseConnections()
Indicates whether connections are re-used after being returned to the connection pool.

Returns:
true if connections may be reused; false if connections are closed after they are returned to the pool. The default value is true.

setEnforceMaxPoolSize

public void setEnforceMaxPoolSize(boolean enforce)
Sets whether pool size restriction should be strictly enforced. If set to true, and a connection is requested from a full pool with no available connections, then an exception will be thrown. If set to false, then a warning will be traced, and a new (unpooled) physical connection will be returned.

Parameters:
enforce - If true, then the pool size restriction should be strictly enforced. The default value is false.
See Also:
setMaxPoolSize(int)

setInitialPoolSize

public void setInitialPoolSize(int initialPoolSize)
Sets the number of connections that the connection pool contains when it is created. If the pool has already been created, this method has no effect.

Parameters:
initialPoolSize - The number of pooled connections. Valid values are 0 or greater. The default value is 5.

setMaxIdleTime

public void setMaxIdleTime(int maxIdleTime)
Sets the maximum amount of time (in seconds) that a pooled connection in this pool is allowed to remain idle before it is automatically closed. A value of 0 indicates pooled connections are never automatically closed.

Parameters:
maxIdleTime - The maximum idle time for a pooled connection, in seconds. Valid values are 0 or greater. The default value is 1 hour.

setMaxLifetime

public void setMaxLifetime(int maxLifetime)
Sets the maximum amount of time (in seconds) after which an in-use physical connection is considered to be expired and should be closed. A value of 0 indicates in-use connections are never automatically closed.

Parameters:
maxLifetime - The maximum lifetime for an in-use connection, in seconds. Valid values are 0 or greater. The default value is 24 hours.

setMaxPoolSize

public void setMaxPoolSize(int maxPoolSize)
Sets the maximum number of connections that the connection pool contains. A value of 0 indicates there is no maximum.

Parameters:
maxPoolSize - The maximum number of connections in this pool. Valid values are 0 or greater. The default value is 0 (no maximum).
See Also:
setEnforceMaxPoolSize(boolean)

setMinPoolSize

public void setMinPoolSize(int minPoolSize)
Sets the minimum number of connections that the connection pool contains. A value of 0 indicates there is no minimum and connections are created as they are needed.

Parameters:
minPoolSize - The minimum number of available connections in the pool. Valid values are 0 or greater. The default value is 0.

setPretestConnections

public void setPretestConnections(boolean pretest)
Sets whether connections are pretested before being allocated to requesters.

Parameters:
pretest - If true, then connections are pretested; if false, then connections are not pretested. The default value is false.

setPropertyCycle

public void setPropertyCycle(int propertyCycle)
Sets the interval (in seconds) between runs of the connection pool's maintenance thread. The maintenance thread enforces this pool's connections and statements so that they conform to the specified minimum and maximum pool sizes, idle time, and maximum number of open statements. A value of 0 indicates that a maintenance thread should not be created.

Parameters:
propertyCycle - The number of seconds that this pool should wait before enforcing its properties. Valid values are 0 or greater. The default value is 5 minutes.

setReuseConnections

public void setReuseConnections(boolean reuse)
Sets whether connections may be re-used after being returned to the connection pool.

Parameters:
reuse - If true, then connections may be reused; if false, then connections are closed after they are returned to the pool. The default value is true.

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
                     throws SQLException
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
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