weblogic.jdbc.extensions
Interface WLConnection

All Superinterfaces:

HarvestableConnection, LabelableConnection

public interface WLConnection
extends LabelableConnection, HarvestableConnection

A WLConnection provides methods not supported by java.sql.Connection.

WLConnection provide methods for the following:

• Getting the vendor Connection from a logical pool connection
• Clearing the statement cache
• Clearing a single callable statement from the statement cache
• Clearing a single prepared statement from the statement cache
• Managing connection labels

See Also:

Connection

clearStatementCache

void clearStatementCache()
                         throws SQLException

Clears the statement cache.

Throws:

SQLException - - if a database access error occurs

getVendorConnection

Connection getVendorConnection()
                               throws SQLException

Returns the underlying physical connection (the vendor connection) from a pooled database connection (a logical connection).

Returns:

java.sql.Connection

Throws:

SQLException - - if a database access error occurs

clearCallableStatement

boolean clearCallableStatement(String sql)
                               throws SQLException

Clears a callable statement from the Statement Cache

Parameters:

sql - - an SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.

Returns:

true - statement found and removed from cache
false - statement not found in cache. This is not always an erroneous condition as it can happen if statement caching is diabled, or the statement got ejected from the cache to make space for another.

Throws:

SQLException - - if a database access error occurs

clearCallableStatement

boolean clearCallableStatement(String sql,
                               int resType,
                               int resConcurrency)
                               throws SQLException

Clears a callable statement from the Statement Cache

Parameters:

sql - - an SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.

resType - - a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE

resConcurrency - - a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE

Returns:

true - statement found and removed from cache
false - statement not found in cache. This is not always an erroneous condition as it can happen if statement caching is diabled, or the statement got ejected from the cache to make space for another.

Throws:

SQLException - - if a database access error occurs

clearPreparedStatement

boolean clearPreparedStatement(String sql)
                               throws SQLException

Clears a prepared statement from the Statement Cache

Parameters:

sql - - an SQL statement that may contain one or more '?' IN parameter placeholders

Returns:

true - statement found and removed from cache
false - statement not found in cache. This is not always an erroneous condition as it can happen if statement caching is diabled, or the statement got ejected from the cache to make space for another.

Throws:

SQLException - - if a database access error occurs

clearPreparedStatement

boolean clearPreparedStatement(String sql,
                               int resType,
                               int resConcurrency)
                               throws SQLException

Clears a prepared statement from the Statement Cache

Parameters:

sql - - an SQL statement that may contain one or more '?' IN parameter placeholders

resType - - a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE

resConcurrency - - a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE

Returns:

true - statement found and removed from cache
false - statement not found in cache. This is not always an erroneous condition as it can happen if statement caching is diabled, or the statement got ejected from the cache to make space for another.

Throws:

SQLException - - if a database access error occurs

getPoolName

String getPoolName()

Returns the name of the connection pool to which this connection belongs to.

setFailed

void setFailed()
               throws SQLException

Force this connection to be destroyed by connection pool

Throws:

SQLException - - if a connection pool error happen

isValid

boolean isValid(int timeout)
                throws SQLException

Returns true if connection is still valid. Please refer to java.sql.Connection.isValid(int timeout) for more information.

Parameters:

timeout - - The time in seconds to wait for the database operation used to validate the connection to complete. A value of 0 indicates a timeout is not applied to the database operation.

Returns:

true if the connection is valid, false otherwise

Throws:

SQLException - - if the value supplied for timeout is less then 0

isValid

boolean isValid()
                throws SQLException

This method equals to isValid(15).

Throws:

SQLException

getVendorConnectionSafe

Connection getVendorConnectionSafe()
                                   throws SQLException

Returns the underlying physical connection (the vendor connection) from a pooled database connection (a logical connection). When the connection is closed, it is returned to the pool, independent of the setting of Remove Infected Connections Enabled.

Returns:

java.sql.Connection

Throws:

SQLException - - if a database access error occurs

applyConnectionLabel

void applyConnectionLabel(String key,
                          String value)
                          throws SQLException

Description copied from interface: LabelableConnection

Applies connection labels on a borrowed connection while the connection is open. Applying connection labels is cumulative; the supplied key/value pair is added to those connection labels already applied each time this method is called. However, for each particular label key, only the last applied value is retained. Applying connection labels on a closed connection throws a UniversalConnectionPoolException.

Specified by:

applyConnectionLabel in interface LabelableConnection

Parameters:

key - The key of the connection label to be applied. Cannot be null or an empty string.

value - The value of the connection label to be applied. Can be null or an empty string.

Throws:

SQLException - If this connection was closed or the key is null or an empty string.

removeConnectionLabel

void removeConnectionLabel(String key)
                           throws SQLException

Description copied from interface: LabelableConnection

Removes the connection label with the given key from the connection labels applied on this connection. This method does nothing if there is no applied label with the specified key.

Specified by:

removeConnectionLabel in interface LabelableConnection

Parameters:

key - The key of the connection label to be removed. Cannot be null or an empty string.

Throws:

SQLException - If this connection was closed or the key is null or an empty string.

getConnectionLabels

Properties getConnectionLabels()
                               throws SQLException

Description copied from interface: LabelableConnection

Retrieves all the connection labels applied on this connection. Any change to the result Properties object does not affect the labels applied to this connection.

Specified by:

getConnectionLabels in interface LabelableConnection

Returns:

A java.util.Properties object storing all the applied labels as key/value pairs. Returns null if there are no applied labels on this connection.

Throws:

SQLException - If this connection was closed.

getUnmatchedConnectionLabels

Properties getUnmatchedConnectionLabels(Properties requestedLabels)
                                        throws SQLException

Description copied from interface: LabelableConnection

Obtains all the requested labels that did not match the applied labels on this connection when this connection was borrowed from the pool.

This method is typically used to verify which labels in the requested labels are matched and which labels are not.

Specified by:

getUnmatchedConnectionLabels in interface LabelableConnection

Parameters:

requestedLabels - The requested labels that borrowed this connection from the pool.

Returns:

A java.util.Properties object storing all the requested labels that did not match the labels applied on this connection. Returns null if there are none.

Throws:

SQLException - If this connection was closed.