public interface LabelableConnection
java.sql.Connections
.
The Connection Labeling mechanism is application-driven. Labels can be applied on and removed from a borrowed connection, with each connection label defined as a (key, value) pair. Connection labels are used for connection matching purposes. Any number of connection labels may be applied on a borrowed connection. It is also possible to obtain all the labels currently applied on a borrowed connection, as well as all the unmatched labels within application-requested labels for each connection-borrowing request.
Applications use this interface along with the
getConnection(...)
methods (with labels parameter) and the
labeling callbacks for complete connection labeling functions.
PoolDataSource
,
ConnectionLabelingCallback
Modifier and Type | Method and Description |
---|---|
void |
applyConnectionLabel(java.lang.String key,
java.lang.String value)
Applies connection labels on a borrowed connection while the
connection is open.
|
java.util.Properties |
getConnectionLabels()
Retrieves all the connection labels applied on this connection.
|
java.util.Properties |
getUnmatchedConnectionLabels(java.util.Properties requestedLabels)
Obtains all the requested labels that did not match the applied
labels on this connection when this connection was borrowed from
the pool.
|
void |
removeConnectionLabel(java.lang.String key)
Removes the connection label with the given key from the connection
labels applied on this connection.
|
void applyConnectionLabel(java.lang.String key, java.lang.String value) throws java.sql.SQLException
UniversalConnectionPoolException
.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.java.sql.SQLException
- If this connection was closed or the
key is null
or an empty
string.void removeConnectionLabel(java.lang.String key) throws java.sql.SQLException
key
- The key of the connection label to be removed. Cannot be
null
or an empty string.java.sql.SQLException
- If this connection was closed or the
key is null
or an empty
string.java.util.Properties getConnectionLabels() throws java.sql.SQLException
java.util.Properties
object storing all the
applied labels as key/value pairs. Returns null if there are
no applied labels on this connection.java.sql.SQLException
- If this connection was closed.java.util.Properties getUnmatchedConnectionLabels(java.util.Properties requestedLabels) throws java.sql.SQLException
This method is typically used to verify which labels in the requested labels are matched and which labels are not.
requestedLabels
- The requested labels that borrowed this
connection from the pool.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.java.sql.SQLException
- If this connection was closed.