Package org.apache.tomcat.jdbc.pool
Class PooledConnection
java.lang.Object
org.apache.tomcat.jdbc.pool.PooledConnection
- All Implemented Interfaces:
- PooledConnectionMBean
Represents a pooled connection
 and holds a reference to the 
Connection object- 
Field SummaryFieldsModifier and TypeFieldDescriptionprotected ConnectionPoolThe parentprotected PoolConfigurationThe properties for the connection poolstatic final Stringstatic final Stringstatic final intValidate when connection is borrowed flagstatic final intValidate when connection is idle flagstatic final intValidate when connection is initialized flagstatic final intValidate when connection is returned flagprotected XAConnectionIf using a XAConnection underneath.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionbooleanDeprecated.voidvoidconnect()Connects the underlying connection to the database.protected voidprotected voidvoidlongReturns abandon timeout in millisecondsbooleanReturns the underlying connectionlongReturns the first handler in the interceptor chainintlongReturns the timestamp of when the connection was last connected to the database.longReturns the timestamp of the last successful validation query execution.Returns the configuration for this connection and poollongThe time limit for how long the object can remain unused before it is releasedReturns the stack trace from when this connection was borrowed.longReturn the timestamps of last pool action.intReturns the underlying XA connectionbooleanisClosed()booleanReturns the discarded flag.booleanbooleanReturns true if the connection has been connected more thanPoolConfiguration.getMaxAge()milliseconds. false otherwise.booleanbooleanReturns true if this connection has been released and wont be reused.booleanvoidlock()Locks the connection only if eitherPoolConfiguration.isPoolSweeperEnabled()orPoolConfiguration.getUseLock()return true.voidIssues a call todisconnect(boolean)with the argument false followed by a call toconnect()booleanrelease()This method is called if (Now - timeCheckedIn > getReleaseTime()) This method disconnects the connection, logs an error in debug mode if it happens then sets thereleasedflag to false.voidsetDiscarded(boolean discarded) An interceptor can call this method with the value true, and the connection will be closed when it is returned to the pool.voidsetHandler(JdbcInterceptor handler) voidsetLastValidated(long lastValidated) Set the timestamp the connection was last validated.voidsetPoolProperties(PoolConfiguration poolProperties) Sets the pool configuration for this connection and connection pool.voidsetStackTrace(String trace) The pool will set the stack trace when it is check out and checked invoidsetSuspect(boolean suspect) voidsetTimestamp(long timestamp) Sets a timestamp on this connection.booleanshouldForceReconnect(String username, String password) Returns true if we must force reconnect based on credentials passed in.toString()voidunlock()Unlocks the connection only if the sweeper is enabled Otherwise this is a noop for performancebooleanvalidate(int validateAction) Returnstrueif the object is still valid. if not the pool will call the getExpiredAction() and follow up with one of the four expired methodsbooleanValidates a connection.
- 
Field Details- 
PROP_USER- See Also:
 
- 
PROP_PASSWORD- See Also:
 
- 
VALIDATE_BORROWpublic static final int VALIDATE_BORROWValidate when connection is borrowed flag- See Also:
 
- 
VALIDATE_RETURNpublic static final int VALIDATE_RETURNValidate when connection is returned flag- See Also:
 
- 
VALIDATE_IDLEpublic static final int VALIDATE_IDLEValidate when connection is idle flag- See Also:
 
- 
VALIDATE_INITpublic static final int VALIDATE_INITValidate when connection is initialized flag- See Also:
 
- 
poolPropertiesThe properties for the connection pool
- 
xaConnectionIf using a XAConnection underneath.
- 
parentThe parent
 
- 
- 
Constructor Details- 
PooledConnectionConstructor- Parameters:
- prop- - pool properties
- parent- - the parent connection pool
 
 
- 
- 
Method Details- 
getConnectionVersionpublic long getConnectionVersion()- Specified by:
- getConnectionVersionin interface- PooledConnectionMBean
 
- 
checkUserDeprecated.useshouldForceReconnect(String, String)method kept since it was public, to avoid changing interface.- Parameters:
- username- The user name
- password- The password
- Returns:
- trueif the pool does not need to reconnect
 
- 
shouldForceReconnectReturns true if we must force reconnect based on credentials passed in. Returns false ifPoolConfiguration.isAlternateUsernameAllowed()method returns false. Returns false if the username/password has not changed since this connection was connected- Parameters:
- username- the username you wish to connect with, pass in null to accept the default username from- PoolConfiguration.getUsername()
- password- the password you wish to connect with, pass in null to accept the default username from- PoolConfiguration.getPassword()
- Returns:
- true is the pool must reconnect
 
- 
connectConnects the underlying connection to the database.- Throws:
- SQLException- if the method- release()has been called.
- SQLException- if driver instantiation fails
- SQLException- if a call to- Driver.connect(String, java.util.Properties)fails.
- SQLException- if default properties are configured and a call to- Connection.setAutoCommit(boolean),- Connection.setCatalog(String),- Connection.setTransactionIsolation(int)or- Connection.setReadOnly(boolean)fails.
 
- 
connectUsingDataSource- Throws:
- SQLException
 
- 
connectUsingDriver- Throws:
- SQLException
 
- 
isInitializedpublic boolean isInitialized()- Specified by:
- isInitializedin interface- PooledConnectionMBean
- Returns:
- true if connect() was called successfully and disconnect has not yet been called
 
- 
isMaxAgeExpiredpublic boolean isMaxAgeExpired()Returns true if the connection has been connected more thanPoolConfiguration.getMaxAge()milliseconds. false otherwise.- Specified by:
- isMaxAgeExpiredin interface- PooledConnectionMBean
- Returns:
- Returns true if the connection has been connected more than
 PoolConfiguration.getMaxAge()milliseconds. false otherwise.
 
- 
reconnectIssues a call todisconnect(boolean)with the argument false followed by a call toconnect()- Throws:
- SQLException- if the call to- connect()fails.
 
- 
getAbandonTimeoutpublic long getAbandonTimeout()Returns abandon timeout in milliseconds- Returns:
- abandon timeout in milliseconds
 
- 
validatepublic boolean validate(int validateAction) Returnstrueif the object is still valid. if not the pool will call the getExpiredAction() and follow up with one of the four expired methods- Parameters:
- validateAction- The value
- Returns:
- trueif the connection is valid
 
- 
validateValidates a connection.- Parameters:
- validateAction- the action used. One of- VALIDATE_BORROW,- VALIDATE_IDLE,- VALIDATE_INITor- VALIDATE_RETURN
- sql- the SQL to be used during validation. If the- PoolConfiguration.setInitSQL(String)has been called with a non null value and the action is- VALIDATE_INITthe init SQL will be used for validation.
- Returns:
- true if the connection was validated successfully. It returns true even if validation was not performed, such as when
 PoolConfiguration.setValidationInterval(long)has been called with a positive value.false if the validation failed. The caller should close the connection if false is returned since a session could have been left in an unknown state during initialization. 
 
- 
getReleaseTimepublic long getReleaseTime()The time limit for how long the object can remain unused before it is released
- 
releasepublic boolean release()This method is called if (Now - timeCheckedIn > getReleaseTime()) This method disconnects the connection, logs an error in debug mode if it happens then sets thereleasedflag to false. Any attempts to connect this cached object again will fail perconnect()The connection pool uses the atomic return value to decrement the pool size counter.- Returns:
- true if this is the first time this method has been called. false if this method has been called before.
 
- 
setStackTraceThe pool will set the stack trace when it is check out and checked in- Parameters:
- trace- the stack trace for this connection
 
- 
getStackTraceReturns the stack trace from when this connection was borrowed. Can return null if no stack trace was set.- Returns:
- the stack trace or null of no trace was set
 
- 
setTimestamppublic void setTimestamp(long timestamp) Sets a timestamp on this connection. A timestamp usually means that some operation performed successfully.- Parameters:
- timestamp- the timestamp as defined by- System.currentTimeMillis()
 
- 
isSuspectpublic boolean isSuspect()- Specified by:
- isSuspectin interface- PooledConnectionMBean
 
- 
setSuspectpublic void setSuspect(boolean suspect) 
- 
setDiscardedpublic void setDiscarded(boolean discarded) An interceptor can call this method with the value true, and the connection will be closed when it is returned to the pool.- Parameters:
- discarded- - only valid value is true
- Throws:
- IllegalStateException- if this method is called with the value false and the value true has already been set.
 
- 
setLastValidatedpublic void setLastValidated(long lastValidated) Set the timestamp the connection was last validated. This flag is used to keep track when we are using avalidation-interval.- Parameters:
- lastValidated- a timestamp as defined by- System.currentTimeMillis()
 
- 
setPoolPropertiesSets the pool configuration for this connection and connection pool. Object is shared with theConnectionPool- Parameters:
- poolProperties- The pool properties
 
- 
getTimestamppublic long getTimestamp()Return the timestamps of last pool action. Timestamps are typically set when connections are borrowed from the pool. It is used to keep track ofabandon-timeouts. This timestamp can also be reset by theResetAbandonedTimer.invoke(Object, java.lang.reflect.Method, Object[])- Specified by:
- getTimestampin interface- PooledConnectionMBean
- Returns:
- the timestamp of the last pool action as defined by System.currentTimeMillis()
 
- 
isDiscardedpublic boolean isDiscarded()Returns the discarded flag.- Specified by:
- isDiscardedin interface- PooledConnectionMBean
- Returns:
- the discarded flag. If the value is true,
 either disconnect(boolean)has been called or it will be called when the connection is returned to the pool.
 
- 
getLastValidatedpublic long getLastValidated()Returns the timestamp of the last successful validation query execution.- Specified by:
- getLastValidatedin interface- PooledConnectionMBean
- Returns:
- the timestamp of the last successful validation query execution as defined by System.currentTimeMillis()
 
- 
getPoolPropertiesReturns the configuration for this connection and pool- Returns:
- the configuration for this connection and pool
 
- 
lockpublic void lock()Locks the connection only if eitherPoolConfiguration.isPoolSweeperEnabled()orPoolConfiguration.getUseLock()return true. The per connection lock ensures thread safety is multiple threads are performing operations on the connection. Otherwise this is a noop for performance
- 
unlockpublic void unlock()Unlocks the connection only if the sweeper is enabled Otherwise this is a noop for performance
- 
getConnectionReturns the underlying connection- Returns:
- the underlying JDBC connection as it was returned from the JDBC driver
- See Also:
 
- 
getXAConnectionReturns the underlying XA connection- Returns:
- the underlying XA connection as it was returned from the Datasource
 
- 
getLastConnectedpublic long getLastConnected()Returns the timestamp of when the connection was last connected to the database. ie, a successful call toDriver.connect(String, java.util.Properties).- Specified by:
- getLastConnectedin interface- PooledConnectionMBean
- Returns:
- the timestamp when this connection was created as defined by System.currentTimeMillis()
 
- 
getHandlerReturns the first handler in the interceptor chain- Returns:
- the first interceptor for this connection
 
- 
setHandler
- 
toString
- 
isReleasedpublic boolean isReleased()Returns true if this connection has been released and wont be reused.- Specified by:
- isReleasedin interface- PooledConnectionMBean
- Returns:
- true if the method release()has been called
 
- 
getAttributes
- 
createMBeanpublic void createMBean()
- 
getObjectName
- 
clearWarningspublic void clearWarnings()- Specified by:
- clearWarningsin interface- PooledConnectionMBean
 
- 
isClosed- Specified by:
- isClosedin interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
getAutoCommit- Specified by:
- getAutoCommitin interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
getCatalog- Specified by:
- getCatalogin interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
getHoldability- Specified by:
- getHoldabilityin interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
isReadOnly- Specified by:
- isReadOnlyin interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
getSchema- Specified by:
- getSchemain interface- PooledConnectionMBean
- Throws:
- SQLException
 
- 
getTransactionIsolation- Specified by:
- getTransactionIsolationin interface- PooledConnectionMBean
- Throws:
- SQLException
 
 
- 
shouldForceReconnect(String, String)method kept since it was public, to avoid changing interface.