Package oracle.ucp.jdbc

Interface PoolDataSource

All Superinterfaces:
CommonDataSource, DataSource, Diagnosable, Wrapper
All Known Subinterfaces:
PoolXADataSource
All Known Implementing Classes:
PoolDataSourceImpl, PoolXADataSourceImpl
public interface PoolDataSource extends DataSource, Diagnosable
A connection pool-aware data source interface. PoolDataSource uses Universal Connection Pool internally. See setters for pool properties and their default values.

The interface also defines the JNDI property names supported by UCP datasource. These properties can be configured in application servers that support datasource configuration using JNDI feature.

For example, In Tomcat you can define the UCP pool JNDI resource in application's context.xml like below- 

 
 <Resource name="tomcat/UCPPool" auth="Container" 
 factory="oracle.ucp.jdbc.PoolDataSourceImpl" 
 type="oracle.ucp.jdbc.PoolDataSource"
 description="UCP Pool in Tomcat" 
 connectionFactoryClassName="oracle.jdbc.pool.OracleDataSource"
 user="<user>" 
 password="<password>"
 initialPoolSize="<val>" 
 url="<database_url>" 
 />
See Also:

  • Field Details

    • SYSTEM_PROPERTY_AFFINITY_STRICT

      static final String SYSTEM_PROPERTY_AFFINITY_STRICT
      Strict RAC affinity flag.

      This system property indicates whether RAC affinity is strict or not. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_MAX_INIT_THREADS

      static final String SYSTEM_PROPERTY_MAX_INIT_THREADS
      The maximum number of worker threads to reach initial pool size.

      This system property defines how many worker threads will perticipate in connection pool warming up creating designated number of initial connections. The default value is 4.

      See Also:

    • SYSTEM_PROPERTY_PRE_WLS1212_COMPATIBLE

      static final String SYSTEM_PROPERTY_PRE_WLS1212_COMPATIBLE
      Pre-WLS 12.1.2 compatibility flag.

      This system property defines whether we should operate in pre-WLS 12.1.2 compatible mode or not. If the property value is "true", we'll be backward-compatible with WLS 10.3.6 and 12.1.1. This is a transient property that will be removed in a future version/patch. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_CONNECTION_CREATION_RETRY_DELAY

      static final String SYSTEM_PROPERTY_CONNECTION_CREATION_RETRY_DELAY
      The retry delay for connection creation polling.

      When a database is inoperable, UCP makes periodic connection creation reattempts. This system property defined the re-attempt timeout in milliseconds. The default value is 3000 milliseconds.

      See Also:

    • SYSTEM_PROPERTY_FAN_ENABLED

      static final String SYSTEM_PROPERTY_FAN_ENABLED
      Driver's High Availability processing switch.

      This system property is the flag for disabling Oracle JDBC driver's High Availability processing. This applies to both UCP and WLS AGL use cases. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_BEGIN_REQUEST_AT_CONNECTION_CREATION

      static final String SYSTEM_PROPERTY_BEGIN_REQUEST_AT_CONNECTION_CREATION
      Driver's implicit beginRequest switch.

      This system property is the flag for disabling Oracle JDBC driver's implicit beginRequest for Auto-AC (Automatic Application Continuity). This applies to both UCP and WLS AGL use cases. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_XML_CONFIG_FILE

      static final String SYSTEM_PROPERTY_XML_CONFIG_FILE
      The XML configuration file path for UCP.

      This system property defines the pathname for an XML file to read and interpret for automatic UCP configuring. No default value (empty string).

      See Also:

    • SYSTEM_PROPERTY_DESTROY_ON_RELOAD

      static final String SYSTEM_PROPERTY_DESTROY_ON_RELOAD
      What to do if a new pool with existing pool name gets created.

      This system property is the flag instructing whether to destroy a pool or throw the "pool already exists" exception if there is an attempt to create a new pool with the name of existing pool. This feature has been implemented per JBoss request because thir reload procedure recreates a pool with the same name expecting the old one is implicitly gets destroyed. The traditional pool's behavior in this case is to throw the exception. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_IMITATE_ASYNC_BORROW

      static final String SYSTEM_PROPERTY_IMITATE_ASYNC_BORROW
      Asynchronous borrow imitation switch.

      This system property is the flag defining whether to run real asynchronous borrow mechanism or its imitation through blocking borrow. This property is introduced for debugging and testing purposes. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_SELFTUNING

      static final String SYSTEM_PROPERTY_SELFTUNING
      Pool Size self-tuning switch.

      This system property is the flag to enable or disable pool size self-tuning. If self-tuning is enabled, UCP will try to keep pool's working set of connection to be able to effectively serve recent number of connection borrow requests. Self-tuning mechanism will not bring the working set of connections beyond designated pool bounds (minumum and maximum pool size). The default value is "false", i.e. self-tuning is disabled.

      See Also:

    • SYSTEM_PROPERTY_WLS_JTA

      static final String SYSTEM_PROPERTY_WLS_JTA
      UCP native data source in WebLogic to work with WLS transaction manager for JTA/XA transactions.

      This system property is the flag that allows UCP native data source in WebLogic to work with WLS transaction manager for JTA/XA transactions. The feature is disabled by default, and can be enabled by setting the system property to true.

      See Also:

    • SYSTEM_PROPERTY_TIMERS_AFFECT_ALL_CONNECTIONS

      static final String SYSTEM_PROPERTY_TIMERS_AFFECT_ALL_CONNECTIONS
      The switch to change the logic of InactiveConnectionTimeout and MaxConnectionReuseTime handling.

      This system property changes the behavior of InactiveConnectionTimeout and MaxConnectionReuseTime: if set to false, a pool will be reduced down to minPoolSize, other connections, even if applicable, will be left opened and not replaced. If set to false and the number of idle connections is equal to the min pool size, then these timeouts are ignored. If set to true, the timeouts are enforced and will affect connections even if the number of idle connections is smaller than the min pool size. This will cause idle connections to be purged and re-created. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_DIAGNOSTIC_ENABLE_TRACE

      static final String SYSTEM_PROPERTY_DIAGNOSTIC_ENABLE_TRACE
      Diagnosability: is tracing enabled?

      This system property is the flag for enabling diagnosability tracing. Initial state for a flag allowing publishing a trace into DiagnosticsCollector's memory handlers. Tracing in this context is a collecting logging messages into an in-memory ring buffer. The default value is "true".

      See Also:

    • SYSTEM_PROPERTY_DIAGNOSTIC_ENABLE_LOGGING

      static final String SYSTEM_PROPERTY_DIAGNOSTIC_ENABLE_LOGGING
      Diagnosability: is debug logging enabled?

      Initial state for a flag allowing publishing a trace into DiagnosticsCollector's debug logger. Logging is the same as the Java logging API. The default value is "false".

      See Also:

    • SYSTEM_PROPERTY_DIAGNOSTIC_BUFFER_SIZE

      static final String SYSTEM_PROPERTY_DIAGNOSTIC_BUFFER_SIZE
      Diagnosability: initial in-memory trace size.

      Initial size of a Diagnosability in-memory tracing buffers. The default value is 1024 log messages.

      See Also:

    • SYSTEM_PROPERTY_DIAGNOSTIC_LOGGING_LEVEL

      static final String SYSTEM_PROPERTY_DIAGNOSTIC_LOGGING_LEVEL
      Diagnosability: initial logging level.

      This system property defines the default logging level for all loggers. Every logger, if not explicitly leveled in the logging config file, will be leveled with this level. The default value is Level.INFO.

      See Also:

    • SYSTEM_PROPERTY_DIAGNOSTIC_ERROR_CODES_TO_WATCH_LIST

      static final String SYSTEM_PROPERTY_DIAGNOSTIC_ERROR_CODES_TO_WATCH_LIST
      Diagnosability: error codes to watch and trigger dumping in-memory tracing buffer into a logger.

      This system property defined the comma separated list of SQLException and UniversalConnectionPoolException error codes to trigger in-memory buffer dump into an appropriate logger. The default value is empty list, nothing.

      See Also:

    • SYSTEM_PROPERTY_ENABLE_SHUTDOWN_HOOK

      static final String SYSTEM_PROPERTY_ENABLE_SHUTDOWN_HOOK
      The shutdown hook of UCP will attempt to gracefully close connections during shutdown by first closing available connections in the pool and then continuously retrying until, eventually, all connections are closed. Note that any pending transaction will be rolled back. This shutdown hook is enabled by default, but can be disabled by setting this system property to false.

      -Doracle.ucp.enableShutdownHook=false

      See Also:

    • SYSTEM_PROPERTY_RLB_INOPERABILITY_TIMEOUT

      static final String SYSTEM_PROPERTY_RLB_INOPERABILITY_TIMEOUT
      Timeout in seconds for the UCP Runtime Load Balancer to be allowed not to follow RLB advisories in case of inoperability of at least one RAC instance (i.e. if an instance is UP but throws SQLRecoverableException on an attempt to create a connection on it).
      See Also:

    • SYSTEM_PROPERTY_CREATE_CONNECTION_IN_BORROW_THREAD

      static final String SYSTEM_PROPERTY_CREATE_CONNECTION_IN_BORROW_THREAD

      Since 23.4, for backward compatibility: there are two modes to grow a pool. If set to true, pool grows with a borrow thread. If set to false, pool grows with a background executor. This property is "false" by default.

      This setting can be overridden by the following property: setCreateConnectionInBorrowThread(boolean). for an apropriate PoolDataSource's object.

      If this property is set to false, a pool waits no longer than a designated connection wait duration no matter how long it takes to create a new connection to grow a pool, if no connection is available at this moment. If this property is set to true, then in this backward compatibility mode a pool waits for a connection to be synchronously created in a borrow thread, and the waiting time can take longer than connectionWaitDuration. For connectionWaitDuration please refer to setConnectionWaitDuration(java.time.Duration).

      See Also:

    • UCP_USER

      static final String UCP_USER
      See Also:

    • UCP_URL

      static final String UCP_URL
      See Also:

    • UCP_PASSWORD

      static final String UCP_PASSWORD
      See Also:

    • UCP_SERVER_NAME

      static final String UCP_SERVER_NAME
      See Also:

    • UCP_PORT_NUMBER

      static final String UCP_PORT_NUMBER
      See Also:

    • UCP_DATABASE_NAME

      static final String UCP_DATABASE_NAME
      See Also:

    • UCP_DATA_SOURCE_NAME

      static final String UCP_DATA_SOURCE_NAME
      See Also:

    • UCP_DESCRIPTION

      static final String UCP_DESCRIPTION
      See Also:

    • UCP_NETWORK_PROTOCOL

      static final String UCP_NETWORK_PROTOCOL
      See Also:

    • UCP_ROLE_NAME

      static final String UCP_ROLE_NAME
      See Also:

    • UCP_CONNECTION_FACTORY_CLASS_NAME

      static final String UCP_CONNECTION_FACTORY_CLASS_NAME
      See Also:

    • UCP_CONNECTION_PROPERTIES

      static final String UCP_CONNECTION_PROPERTIES
      See Also:

    • UCP_CONNECTION_FACTORY_PROPERTIES

      static final String UCP_CONNECTION_FACTORY_PROPERTIES
      See Also:

    • UCP_VALIDATE_CONNECTION_ON_BORROW

      static final String UCP_VALIDATE_CONNECTION_ON_BORROW
      See Also:

    • UCP_SQL_FOR_VALIDATE_CONNECTION

      static final String UCP_SQL_FOR_VALIDATE_CONNECTION
      See Also:

    • UCP_CONNECTION_POOL_NAME

      static final String UCP_CONNECTION_POOL_NAME
      See Also:

    • UCP_INITIAL_POOL_SIZE

      static final String UCP_INITIAL_POOL_SIZE
      See Also:

    • UCP_MIN_POOL_SIZE

      static final String UCP_MIN_POOL_SIZE
      See Also:

    • UCP_MIN_IDLE

      static final String UCP_MIN_IDLE
      See Also:

    • UCP_MAX_POOL_SIZE

      static final String UCP_MAX_POOL_SIZE
      See Also:

    • UCP_NTH_RETURNED_CONNECTION_TO_VALIDATE

      static final String UCP_NTH_RETURNED_CONNECTION_TO_VALIDATE
      See Also:

    • UCP_ABANDONED_CONNECTION_TIMEOUT

      static final String UCP_ABANDONED_CONNECTION_TIMEOUT
      See Also:

    • UCP_TIME_TO_LIVE_CONNECTION_TIMEOUT

      static final String UCP_TIME_TO_LIVE_CONNECTION_TIMEOUT
      See Also:

    • UCP_INACTIVE_CONNECTION_TIMEOUT

      static final String UCP_INACTIVE_CONNECTION_TIMEOUT
      See Also:

    • UCP_MAX_IDLE_TIME

      static final String UCP_MAX_IDLE_TIME
      See Also:

    • UCP_TIMEOUT_CHECK_INTERVAL

      static final String UCP_TIMEOUT_CHECK_INTERVAL
      See Also:

    • UCP_PROPERTY_CYCLE

      static final String UCP_PROPERTY_CYCLE
      See Also:

    • UCP_MAX_STATEMENTS

      static final String UCP_MAX_STATEMENTS
      See Also:

    • UCP_CONNECTION_WAIT_TIMEOUT

      static final String UCP_CONNECTION_WAIT_TIMEOUT
      See Also:

    • UCP_CONNECTION_WAIT_DURATION

      static final String UCP_CONNECTION_WAIT_DURATION
      See Also:

    • UCP_MAX_CONNECTION_REUSE_TIME

      static final String UCP_MAX_CONNECTION_REUSE_TIME
      See Also:

    • UCP_MAX_CONNECTION_REUSE_COUNT

      static final String UCP_MAX_CONNECTION_REUSE_COUNT
      See Also:

    • UCP_CONNECTION_HARVEST_TRIGGER_COUNT

      static final String UCP_CONNECTION_HARVEST_TRIGGER_COUNT
      See Also:

    • UCP_CONNECTION_HARVEST_MAX_COUNT

      static final String UCP_CONNECTION_HARVEST_MAX_COUNT
      See Also:

    • UCP_FAST_CONNECTION_FAILOVER_ENABLED

      static final String UCP_FAST_CONNECTION_FAILOVER_ENABLED
      See Also:

    • UCP_ONS_CONFIGURATION

      static final String UCP_ONS_CONFIGURATION
      See Also:

    • UCP_SECONDS_TO_TRUST_IDLE_CONNECTION

      static final String UCP_SECONDS_TO_TRUST_IDLE_CONNECTION
      See Also:

    • UCP_MAX_CONNECTIONS_PER_SERVICE

      static final String UCP_MAX_CONNECTIONS_PER_SERVICE
      See Also:

    • UCP_LOGIN_TIMEOUT

      static final String UCP_LOGIN_TIMEOUT
      See Also:

    • UCP_SERVICE_NAME

      static final String UCP_SERVICE_NAME
      See Also:

    • UCP_PDB_ROLES

      static final String UCP_PDB_ROLES
      See Also:

    • UCP_CONNECTION_AFFINITY_CALLBACK

      static final String UCP_CONNECTION_AFFINITY_CALLBACK
      See Also:

    • UCP_CONNECTION_INITIALIZATION_CALLBACK

      static final String UCP_CONNECTION_INITIALIZATION_CALLBACK
      See Also:

    • UCP_CONNECTION_CREATION_CONSUMER

      static final String UCP_CONNECTION_CREATION_CONSUMER
      See Also:

    • UCP_CONNECTION_LABELING_CALLBACK

      static final String UCP_CONNECTION_LABELING_CALLBACK
      See Also:

    • UCP_CONNECTION_LABELING_HIGH_COST

      static final String UCP_CONNECTION_LABELING_HIGH_COST
      See Also:

    • UCP_CONNECTION_REPURPOSE_THRESHOLD

      static final String UCP_CONNECTION_REPURPOSE_THRESHOLD
      See Also:

    • UCP_HIGH_COST_CONNECTION_REUSE_THRESHOLD

      static final String UCP_HIGH_COST_CONNECTION_REUSE_THRESHOLD
      See Also:

    • UCP_DATA_SOURCE_FROM_CONFIGURATION

      static final String UCP_DATA_SOURCE_FROM_CONFIGURATION
      See Also:

    • UCP_MAX_CONNECTIONS_PER_SHARD

      static final String UCP_MAX_CONNECTIONS_PER_SHARD
      See Also:

    • UCP_SHARDING_MODE

      static final String UCP_SHARDING_MODE
      See Also:

    • UCP_CONNECTION_VALIDATION_TIMEOUT

      static final String UCP_CONNECTION_VALIDATION_TIMEOUT
      See Also:

    • UCP_READONLY_INSTANCE_ALLOWED

      static final String UCP_READONLY_INSTANCE_ALLOWED
      See Also:

    • UCP_CREATE_CONNECTION_IN_BORROW_THREAD

      static final String UCP_CREATE_CONNECTION_IN_BORROW_THREAD
      See Also:

    • UCP_COMMIT_ON_CONNECTION_RETURN

      static final String UCP_COMMIT_ON_CONNECTION_RETURN
      See Also:

  • Method Details

    • getInitialPoolSize

      int getInitialPoolSize()
      Gets the initial pool size.
      Returns:
      the initial pool size.

    • setInitialPoolSize

      void setInitialPoolSize(int initialPoolSize) throws SQLException
      Sets the initial pool size. This is the number of connections that will be created and placed in the pool when the pool is started.

      The range of valid values is 0 to Integer.MAX_VALUE. It is illegal to set this to a value greater than the maximum pool size. Defaults to 0.

      Parameters:
      initialPoolSize - the initial pool size.
      Throws:
      SQLException - in case of inability to set size.

    • getMinPoolSize

      int getMinPoolSize()
      Gets the minimum number of connections that the connection pool will maintain.
      Returns:
      The minimum number of connections.

    • setMinPoolSize

      void setMinPoolSize(int minPoolSize) throws SQLException
      Sets the minimum number of connections. If the number of available connections PLUS the number of connections in use IS LESS THAN the minimum then the connection is returned to the pool. Otherwise, the connection is closed.

      The range of valid values is 0 to Integer.MAX_VALUE. It is illegal to set this to a value greater than the maximum pool size. The default is 1 connection.

      Parameters:
      minPoolSize - The minimum number of connections.
      Throws:
      SQLException - in case of inability to set min pool size.

    • getMinIdle

      int getMinIdle()
      Gets the minimum number of idle connections that the connection pool will maintain.
      Returns:
      The minimum number of idle connections.

    • setMinIdle

      void setMinIdle(int minIdle) throws SQLException
      Sets the minimum number of idle connections. If the number of available connections IS LESS THAN the minimum then new connections are created and made available in pool.

      The range of valid values is 0 to Integer.MAX_VALUE. It is illegal to set this to a value greater than the maximum pool size. The default is 0.

      Parameters:
      minIdle - The minimum number of idle connections.
      Throws:
      SQLException - in case of inability to set min idle.

    • getMaxPoolSize

      int getMaxPoolSize()
      Gets the maximum number of connections that the connection pool will maintain.
      Returns:
      The maximum number of connections.

    • setMaxPoolSize

      void setMaxPoolSize(int maxPoolSize) throws SQLException
      Sets the maximum number of connections. The maximum number of connections includes the number of connections that are in use as well as the number of available connections.

      The range of valid values is 1 to Integer.MAX_VALUE. Default value is Integer.MAX_VALUE.

      Parameters:
      maxPoolSize - The maximum number of connections.
      Throws:
      SQLException - in case of inability to set max pool size.

    • getInactiveConnectionTimeout

      int getInactiveConnectionTimeout()
      Gets the inactive connection timeout.
      Returns:
      The inactivity timeout.

    • setInactiveConnectionTimeout

      void setInactiveConnectionTimeout(int inactivityTimeout) throws SQLException
      Sets the inactive connection timeout. This timeout determines how long an available connection remains in the connection pool before it is removed from the pool.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 0.

      Setting the value to 0 disables inactive connection timeout processing.

      This property's behaviour is affected by the system property oracle.ucp.timersAffectAllConnections. For more details go to - SYSTEM_PROPERTY_TIMERS_AFFECT_ALL_CONNECTIONS.

      Parameters:
      inactivityTimeout - The inactive connection timeout in seconds.
      Throws:
      SQLException - in case of inability to set timeout.

    • getAbandonedConnectionTimeout

      int getAbandonedConnectionTimeout()
      Gets the abandoned connection timeout value.
      Returns:
      The abandoned connection timeout.

    • setAbandonedConnectionTimeout

      void setAbandonedConnectionTimeout(int abandonedConnectionTimeout) throws SQLException
      Sets the abandoned connection timeout. This timeout determines how long a borrowed connection can remain unused before it is considered as abandoned and reclaimed by the connection pool.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 0.

      Setting the value to 0 disables abandoned connection timeout.

      Parameters:
      abandonedConnectionTimeout - The value of how long a connection has not been used before it is abandoned (in seconds).
      Throws:
      SQLException - in case of inability to set timeout.

    • getConnectionWaitTimeout

      @Deprecated int getConnectionWaitTimeout()
      Deprecated.

      Gets the maximum time (in seconds) that any connection borrow request can wait before it returns to the application.

      This method is deprecated. Use getConnectionWaitDuration() instead.

      Returns:
      The connection wait timeout.
      See Also:

    • getConnectionWaitDuration

      Duration getConnectionWaitDuration()

      Gets the maximum time (in seconds) that any connection borrow request can wait before it returns to the application.

      Returns:
      The connection wait duration.
      See Also:

    • setConnectionWaitTimeout

      @Deprecated void setConnectionWaitTimeout(int waitTimeout) throws SQLException
      Deprecated.

      Configures how much time a connection request call may wait before it either successfully returns a connection or throws an exception.

      The wait duration starts from the point when a connection borrow request is submitted to the pool.

      During this time, UCP may either return a connection that's currently available in the pool (ideal scenario) or create a new connection if the pool hasn't reached its maximum size. Otherwise, UCP waits for a connection to be returned to the pool.

      By default, the connection wait timeout is set to 3 seconds.

      Setting the timeout to 0 makes UCP throw an exception immediately if there is no connection available and no room to grow the pool. Note that it still allows UCP to create a new connection if the maximum size hasn't been reached, and that may take some time.

      This method is deprecated. Use setConnectionWaitDuration(java.time.Duration) instead.

      Parameters:
      waitTimeout - The amount of time in seconds for a connection request to wait.
      Throws:
      SQLException - in case it was not possible to set timeout.

    • setConnectionWaitDuration

      void setConnectionWaitDuration(Duration waitDuration) throws SQLException

      Configures how much time a connection request call may wait before it either successfully returns a connection or throws an exception.

      The wait duration starts from the point when a connection borrow request is submitted to the pool.

      During this time, UCP may either return a connection that's currently available in the pool (ideal scenario) or create a new connection if the pool hasn't reached its maximum size. Otherwise, UCP waits for a connection to be returned to the pool.

      By default, the connection wait timeout is set to 3 seconds.

      Setting the connection wait timeout to Duration.ZERO makes UCP throw an exception immediately if there is no connection available and no room to grow the pool. Note that it still allows UCP to create a new connection if the maximum size hasn't been reached, and that may take some time.

      Parameters:
      waitDuration - The duration for a connection request to wait.
      Throws:
      SQLException - in case it was not possible to set timeout.

    • getTimeToLiveConnectionTimeout

      int getTimeToLiveConnectionTimeout()
      Gets the maximum time (in seconds) a connection may remain in-use. When this timeout expires, the used connection is unconditionally returned to the connection pool. A value of 0 means that the feature is not enabled.
      Returns:
      The maximum time (in seconds) a used connection may be active.

    • setTimeToLiveConnectionTimeout

      void setTimeToLiveConnectionTimeout(int timeToLiveConnectionTimeout) throws SQLException
      Sets the maximum time (in seconds) a connection may remain in-use.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 0.

      Setting the value to 0 disables time-to-live connection timeout processing.

      Parameters:
      timeToLiveConnectionTimeout - The maximum time (in seconds) a used connection may be active.
      Throws:
      SQLException - in case of inability to set timeout.

    • setTimeoutCheckInterval

      void setTimeoutCheckInterval(int timeInterval) throws SQLException
      Sets the timeoutCheckInterval (in seconds). This interval specifies how often the timeout properties such as InactiveConnectionTimeout, AbandonedConnectionTimeout, and TimeToLiveConnectionTimeout are enforced.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 30.

      Setting the value to 0 disables all connection timeout processing.

      Parameters:
      timeInterval - The timeInterval (in seconds) between checks to enforce the timeout properties.
      Throws:
      SQLException - in case of inability to set interval.

    • getTimeoutCheckInterval

      int getTimeoutCheckInterval()
      Gets the timeout check interval (in seconds).
      Returns:
      timeInterval The timeInterval (in seconds) between checks to enforce the timeout properties.

    • setFastConnectionFailoverEnabled

      void setFastConnectionFailoverEnabled(boolean failoverEnabled) throws SQLException
      Enables Fast Connection Failover (FCF) for the connection pool accessed using this pool-enabled data source. By default, FCF is disabled.
      Parameters:
      failoverEnabled - true if Fast Connection Failover is enabled; false if not.
      Throws:
      SQLException - in case of inability to set flag.

    • getFastConnectionFailoverEnabled

      boolean getFastConnectionFailoverEnabled()
      Checks if Fast Connection Failover is enabled.
      Returns:
      true if Fast Connection Failover is enabled; false if not.

    • getConnectionFactoryClassName

      String getConnectionFactoryClassName()
      Gets the Connection Factory class name.
      Returns:
      Name of the connection factory class specified.

    • setConnectionFactoryClassName

      void setConnectionFactoryClassName(String factoryClassName) throws SQLException
      Sets the Connection Factory class name. This is the connection factory used by the connection pool to create physical connections. Must be set for PoolDataSource to operate.
      Parameters:
      factoryClassName - Connection factory class name for obtaining physical connections.
      Throws:
      SQLException - in case of inability to set factory class name.

    • setMaxStatements

      void setMaxStatements(int maxStatements) throws SQLException
      Sets the maximum number of statements that may be pooled or cached on a connection. This is used to enable the statement pooling.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 0.

      Parameters:
      maxStatements - maximum number of statements to be pooled.
      Throws:
      SQLException - Exception occurred during the process of setting maximum statements that may be pooled on a connection.

    • getMaxStatements

      int getMaxStatements()
      Gets the maximum number of statements that may be pooled or cached on a Connection.
      Returns:
      m_maxStatements maximum number of statements that may be pooled or cached on a Connection.

    • setMaxIdleTime

      void setMaxIdleTime(int idleTime) throws SQLException
      Sets the maximum idle time for available connections in the pool. This has the same effect as setting the inactive connection timeout.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 0.

      Parameters:
      idleTime - Maximum idle time in seconds.
      Throws:
      SQLException - in case of inability to set idle time.

    • getMaxIdleTime

      int getMaxIdleTime()
      Gets the maximum idle time.
      Returns:
      The maximum idle time.

    • setPropertyCycle

      void setPropertyCycle(int propertyCycle) throws SQLException
      Sets the property cycle in seconds. This is the time interval between checks to enforce connection pool timeout properties. This has the same effect as setting timeoutCheckInterval.

      The range of valid values is 0 to Integer.MAX_VALUE. Defaults to 30.

      Parameters:
      propertyCycle - Time interval in seconds to enforce connection pool timeout properties.
      Throws:
      SQLException - in case of inability to set property cycle.

    • getPropertyCycle

      int getPropertyCycle()
      Gets the property cycle in seconds.
      Returns:
      The PropertyCycle value.

    • setConnectionPoolName

      void setConnectionPoolName(String connectionpoolName) throws SQLException
      Sets the connection pool name. This property allows the user to specify a String value to name a connection pool instance.

      If not set, the pool name will be automatically generated.

      Parameters:
      connectionpoolName - Name of the connection pool.
      Throws:
      SQLException - in case of inability to set name.

    • getConnectionPoolName

      String getConnectionPoolName()
      Gets the connection pool name.
      Returns:
      The connection pool name.

    • setURL

      void setURL(String url) throws SQLException
      Sets the URL that the data source uses to obtain connections to the database.
      Parameters:
      url - URL to be set.
      Throws:
      SQLException - in case of inability to set URL.

    • getURL

      String getURL()
      Gets the URL for this data source.
      Returns:
      URL for this data source.

    • setUser

      void setUser(String userName) throws SQLException
      Sets the user name with which connections have to be obtained.
      Parameters:
      userName - Username to be set.
      Throws:
      SQLException - in case of inability to set user.

    • getUser

      String getUser()
      Gets the user name for this data source.
      Returns:
      userName for this data source.

    • setPassword

      void setPassword(String pd) throws SQLException
      Sets the password with which connections have to be obtained.
      Parameters:
      pd - Password to be set.
      Throws:
      SQLException - in case of inability to set password.

    • getPassword

      @Deprecated default String getPassword()
      Deprecated.
      Gets the Password for this data source.
      Returns:
      password for this data source.

    • setServerName

      void setServerName(String serverName) throws SQLException
      Sets the database server name.
      Parameters:
      serverName - Database server name to be set.
      Throws:
      SQLException - in case of inability to set server name.

    • getServerName

      String getServerName()
      Gets the database server name.
      Returns:
      Database server name.

    • setPortNumber

      void setPortNumber(int portNumber) throws SQLException
      Sets the database port number.
      Parameters:
      portNumber - Database port number to be set.
      Throws:
      SQLException - in case of inability to set port number.

    • getPortNumber

      int getPortNumber()
      Gets the database port number.
      Returns:
      Database port number.

    • setDatabaseName

      void setDatabaseName(String databaseName) throws SQLException
      Sets the database name.
      Parameters:
      databaseName - Database name to be set.
      Throws:
      SQLException - in case of inability to set db name.

    • getDatabaseName

      String getDatabaseName()
      Gets the database name.
      Returns:
      Database name.

    • setDataSourceName

      void setDataSourceName(String dataSourceName) throws SQLException
      Sets the data source name.
      Parameters:
      dataSourceName - data source name to be set.
      Throws:
      SQLException - in case of inability to set datasource name.

    • getDataSourceName

      String getDataSourceName()
      Gets the data source name.
      Returns:
      data source name.

    • setDescription

      void setDescription(String description) throws SQLException
      Sets the data source description.
      Parameters:
      description - data source description to be set.
      Throws:
      SQLException - in case of inability to set description.

    • getDescription

      String getDescription()
      Gets the data source description.
      Returns:
      data source description.

    • setNetworkProtocol

      void setNetworkProtocol(String networkProtocol) throws SQLException
      Sets the data source network protocol.
      Parameters:
      networkProtocol - data source network protocol to be set.
      Throws:
      SQLException - in case of inability to set protocol.

    • getNetworkProtocol

      String getNetworkProtocol()
      Gets the data source network protocol.
      Returns:
      data source network protocol.

    • setRoleName

      void setRoleName(String roleName) throws SQLException
      Sets the data source role name.
      Parameters:
      roleName - data source role name to be set.
      Throws:
      SQLException - in case of inability to set role name.

    • getRoleName

      String getRoleName()
      Gets the data source role name.
      Returns:
      data source role name.

    • setValidateConnectionOnBorrow

      void setValidateConnectionOnBorrow(boolean validateConnectionOnBorrow) throws SQLException

      Makes the pool validate the connection before returning it to the user by calling the JDBC API "isValid".

      Validating the connection each time it's borrowed from the pool has a performance cost because it typically requires a full roundtrip to the database. You can tune how the Oracle JDBC thin driver validates connections using the "oracle.jdbc.defaultConnectionValidation" property (please refer to the JDBC driver javadoc). You may also configure "secondsToTrustIdleConnection" to avoid validating connections that are often active.

      Default value is false.
      Parameters:
      validateConnectionOnBorrow - Whether or not a connection being borrowed should first be validated.
      Throws:
      SQLException - in case of inability to set flag.
      See Also:

    • getValidateConnectionOnBorrow

      boolean getValidateConnectionOnBorrow()
      Returns whether or not a connection being borrowed should first be validated.
      Returns:
      Whether or not a connection being borrowed should first be validated.

    • setSQLForValidateConnection

      void setSQLForValidateConnection(String SQLString) throws SQLException
      Sets the value of the SQLForValidateConnection property. This is a SQL command used in conjunction with the ValidateConnectionOnBorrow property. The SQL specified should be applicable to the backend database and the JDBC driver configured. Defaults to null.
      Parameters:
      SQLString - The SQL string used for connection validation.
      Throws:
      SQLException - in case of inability to set SQL string.

    • getSQLForValidateConnection

      String getSQLForValidateConnection()
      Gets the value of the SQLForValidateConnection property.
      Returns:
      The SQLForValidateConnection property value.

    • getConnectionHarvestTriggerCount

      int getConnectionHarvestTriggerCount()
      Gets the number of available connections below which the connection pool's connection harvesting will occur. For example, if the value is set to 10, then connection harvesting will occur when the number of available connections drops to 10.
      Returns:
      The number of available connections below which the connection pool's connection harvesting will occur.

    • setConnectionHarvestTriggerCount

      void setConnectionHarvestTriggerCount(int connectionHarvestTriggerCount) throws SQLException
      Sets the number of available connections below which the connection pool's connection harvesting will occur.

      The range of valid values is 0 to maxPoolSize. Defaults to Integer.MAX_VALUE.

      Setting the value to Integer.MAX_VALUE disables connection harvesting.

      Parameters:
      connectionHarvestTriggerCount - The number of available connections below which the connection pool's connection harvesting will occur.
      Throws:
      SQLException - in case of inability to set that count.

    • getConnectionHarvestMaxCount

      int getConnectionHarvestMaxCount()
      Gets the maximum number of connections that may be harvested when the connection harvesting occurs. Note that it is possible that the number of connections that are harvested may be anywhere from 0 to the connectionHarvestMaxCount.
      Returns:
      The maximum number of connections that may be harvested when the connection harvesting occurs.

    • setConnectionHarvestMaxCount

      void setConnectionHarvestMaxCount(int connectionHarvestMaxCount) throws SQLException
      Sets the maximum number of connections that may be harvested when the connection harvesting occurs.

      The range of valid values is 1 to maxPoolSize. Defaults to 1.

      Parameters:
      connectionHarvestMaxCount - the maximum number of connections that may be harvested when the connection harvesting occurs.
      Throws:
      SQLException - in case of inability to set that count.

    • getAvailableConnectionsCount

      int getAvailableConnectionsCount() throws SQLException
      Gets the number of available connections in the pool.
      Returns:
      AvailableConnectionsCount
      Throws:
      SQLException - in case of inability to set that count.

    • getBorrowedConnectionsCount

      int getBorrowedConnectionsCount() throws SQLException
      Gets the number of borrowed connections from the pool.
      Returns:
      BorrowedConnectionsCount
      Throws:
      SQLException - in case of inability to set that count.

    • getONSConfiguration

      String getONSConfiguration() throws SQLException
      Returns the ONS configuration string that is used for remote ONS subscription in the form specified in setONSConfiguration(String). This is used by Fast Connection Failover and Runtime Connection Load Balancing.
      Returns:
      The ONS configuration string used for remote ONS subscription.
      Throws:
      SQLException - in case of inability to set that configuration.

    • setONSConfiguration

      void setONSConfiguration(String onsConfigStr) throws SQLException
      Sets the configuration string used for remote ONS subscription. The parameter string closely resembles the content of the ONS configuration file (ons.config). The string contains a list of name=value pairs separated by a newline character (\n). The name can be one of nodes, walletfile, or walletpassword.

      The parameter string should at least specify the ONS configuration nodes attribute as a list of host:port pairs separated by a comma. SSL would be used when the walletfile attribute is specified as an Oracle wallet file.

      An example ONS configuration string: "nodes=host1:4200,host2:4200\nwalletfile=wfile\nwalletpassword=wpwd" This is used primarily by Fast Connection Failover and Runtime Load Balancing.

      Parameters:
      onsConfigStr - The configuration string for remote ONS subscription.
      Throws:
      SQLException - in case of inability to set that configuration.

    • getConnection

      Connection getConnection(Properties labels) throws SQLException
      Attempts to obtain a database connection with the requested connection labels.
      Parameters:
      labels - The requested connection labels.
      Returns:
      A Connection to the database.
      Throws:
      SQLException - if a database-access error occurs.

    • getConnection

      Connection getConnection(String username, String password, Properties labels) throws SQLException
      Attempts to obtain a database connection with the requested connection labels.
      Parameters:
      username - The database user on whose behalf the connection is being made.
      password - The user's password.
      labels - The requested connection labels.
      Returns:
      A Connection to the database.
      Throws:
      SQLException - if a database-access error occurs.

    • registerConnectionLabelingCallback

      void registerConnectionLabelingCallback(ConnectionLabelingCallback cbk) throws SQLException
      Registers a connection labeling callback with the underlying connection pool.
      Parameters:
      cbk - The ConnectionLabelingCallback object to be registered.
      Throws:
      SQLException - If there is a callback already registered with the pool.

    • removeConnectionLabelingCallback

      void removeConnectionLabelingCallback() throws SQLException
      Removes the ConnectionLabelingCallback object registered with the underlying connection pool, if any.
      Throws:
      SQLException - If callback removal fails.

    • registerConnectionAffinityCallback

      void registerConnectionAffinityCallback(ConnectionAffinityCallback cbk) throws SQLException
      Registers a connection affinity callback on the connection pool.
      Parameters:
      cbk - Affinity Callback object that must be registered.
      Throws:
      SQLException - If callback registration fails.

    • removeConnectionAffinityCallback

      void removeConnectionAffinityCallback() throws SQLException
      Removes the ConnectionAffinityCallback object registered on the connection pool.
      Throws:
      SQLException - If callback removal fails.

    • getConnectionProperties

      Properties getConnectionProperties()
      Gets the connection properties that are set on this data source.
      Returns:
      Connection properties.

    • getConnectionProperty

      String getConnectionProperty(String propertyName)
      Gets the specified connection property that are set on this data source.
      Parameters:
      propertyName - The name of the specified property.
      Returns:
      The value of the inquired connection property. Null if the property is not set.

    • setConnectionProperty

      void setConnectionProperty(String name, String value) throws SQLException
      Sets a connection property on the connection factory. This is used only for DataSource connection factories that also support connection properties; for example, the oracle.jdbc.pool.OracleDataSource in the Oracle JDBC driver.
      Parameters:
      name - The name of the connection property to be set on the connection factory class.
      value - The value of the connection property to be set on the connection factory class.
      Throws:
      SQLException - If any exception occurred while setting the connection property.
      See Also:

    • setConnectionProperties

      void setConnectionProperties(Properties connectionProperties) throws SQLException
      Sets the connection properties on the connection factory. This is used only for DataSource connection factories that also support connection properties; for example, the oracle.jdbc.pool.OracleDataSource in the Oracle JDBC driver.
      Parameters:
      connectionProperties - Connection properties to be set on the connection factory class.
      Throws:
      SQLException - If any exception occurred while setting the connection properties.
      See Also:

    • getConnectionFactoryProperties

      Properties getConnectionFactoryProperties()
      Gets the connection factory properties that are set on this data source.
      Returns:
      Connection factory properties.

    • getConnectionFactoryProperty

      String getConnectionFactoryProperty(String propertyName)
      Gets the specified connection factory property that are set on this data source.
      Parameters:
      propertyName - The name of the specified property.
      Returns:
      The value of the inquired connection factory property. Null if the property is not set.

    • setConnectionFactoryProperty

      void setConnectionFactoryProperty(String name, String value) throws SQLException
      Sets a connection factory property on the connection factory.

      For connection factories that implement java.sql.Driver, the connection factory property specified here will be assumed as a connection property.

      For DataSource connection factories, the property specified here will be assumed as a DataSource property.

      Parameters:
      name - The name of the connection factory property to be set on the connection factory class.
      value - The value of the connection factory property to be set on the connection factory class.
      Throws:
      SQLException - If any exception occurred while setting the connection factory property.
      IllegalArgumentException - If the property name or value is invalid.

    • setConnectionFactoryProperties

      void setConnectionFactoryProperties(Properties factoryProperties) throws SQLException
      Sets the connection factory properties on the connection factory.

      For connection factories that implement java.sql.Driver, the connection factory properties specified here will be assumed as the connection properties.

      For DataSource connection factories, the properties specified here will be assumed as the DataSource properties.

      Parameters:
      factoryProperties - Connection factory properties to be set on the connection factory class.
      Throws:
      SQLException - If any exception occurred while setting the connection factory properties.
      IllegalArgumentException - If factoryProperties is empty.

    • getMaxConnectionReuseTime

      long getMaxConnectionReuseTime()
      Gets the maximum connection reuse time property value. See property description in setMaxConnectionReuseTime().
      Returns:
      Maximum connection reuse time (in seconds).

    • setMaxConnectionReuseTime

      void setMaxConnectionReuseTime(long maxConnectionReuseTime) throws SQLException
      Sets the maximum connection reuse time property. This property specifies the maximum time any connection can potentially be reused after which the pool removes and closes a connection. The value is specified in seconds and must be greater than 0. For example, if the specified value is 3600 seconds, then when a connection is in existence for more than 3600 seconds, the connection is closed and removed from the pool. Connections are closed gracefully after they are returned to the pool and the specified property value has been exceeded. Default is 0, which means this feature is not enabled.

      This property's behaviour is affected by the system property oracle.ucp.timersAffectAllConnections. For more details go to - SYSTEM_PROPERTY_TIMERS_AFFECT_ALL_CONNECTIONS.

      Parameters:
      maxConnectionReuseTime - Maximum connection reuse time (in seconds).
      Throws:
      SQLException - in case of inability to set reuse time.

    • getMaxConnectionReuseCount

      int getMaxConnectionReuseCount()
      Gets the maximum connection reuse count property value. See property description in setMaxConnectionReuseCount().
      Returns:
      Maximum connection reuse count.

    • setMaxConnectionReuseCount

      void setMaxConnectionReuseCount(int maxConnectionReuseCount) throws SQLException
      Sets the maximum connection reuse count property. This property specifies the maximum number of times any connection can be reused after which the pool removes and closes a connection. The value must be greater than 0 for this feature to be enabled. For example, if the specified value is 100, then when a connection is reused or borrowed 100 times from the pool, it is closed and removed from the pool. Connections are closed gracefully after they are returned to the pool and the property value has been exceeded. Default is 0, which means this feature is not enabled.
      Parameters:
      maxConnectionReuseCount - Maximum connection reuse count.
      Throws:
      SQLException - in case of inability to set reuse time.

    • getStatistics

      JDBCConnectionPoolStatistics getStatistics()
      Gets the statistics of the connection pool.
      Returns:
      The statistics of the connection pool.

    • registerConnectionInitializationCallback

      void registerConnectionInitializationCallback(ConnectionInitializationCallback cbk) throws SQLException
      Registers a connection initialization callback.
      Parameters:
      cbk - The ConnectionInitializationCallback object to be registered.
      Throws:
      SQLException - If there is a callback already registered with the pool.

    • unregisterConnectionInitializationCallback

      void unregisterConnectionInitializationCallback() throws SQLException
      Unregisters the connection initialization callback on this pool.
      Throws:
      SQLException - If callback removal fails.

    • getConnectionInitializationCallback

      ConnectionInitializationCallback getConnectionInitializationCallback()
      Obtains the registered connection initialization callback, if any.
      Returns:
      The registered ConnectionInitializationCallback, or null if there is no callback registered.

    • registerConnectionCreationConsumer

      default void registerConnectionCreationConsumer(Consumer<oracle.ucp.ConnectionCreationInformation> consumer)
      Registers a connection creation Consumer.
      Parameters:
      consumer - The Consumer object to be registered.

    • unregisterConnectionCreationConsumer

      default void unregisterConnectionCreationConsumer()
      Unregisters the connection creation Consumer on this pool.

    • getConnectionCreationConsumer

      default Consumer<oracle.ucp.ConnectionCreationInformation> getConnectionCreationConsumer()
      Obtains the registered connection creation Consumer, if any.
      Returns:
      The registered Consumer, or null if there is no Consumer registered.

    • getConnectionLabelingHighCost

      int getConnectionLabelingHighCost()
      Obtains the cost value which identifies a connection as "high-cost" for connection labeling.
      Returns:
      The cost value that identifies a connection as "high-cost" for connection labeling.
      See Also:

    • setConnectionLabelingHighCost

      void setConnectionLabelingHighCost(int highCost) throws SQLException
      Sets the cost value which identifies a connection as "high-cost" for connection labeling. Connection labeling uses the cost(Properties, Properties) method in ConnectionLabelingCallback to find a connection in the pool for a request. When this property is set, connections with a cost value equal to or greater than the property value are considered "high-cost" connections. The default value is Integer.MAX_VALUE.
      Parameters:
      highCost - The cost value that identifies a connection as "high-cost" for connection labeling.
      Throws:
      SQLException - If an exception occurs while setting the cost.

    • getHighCostConnectionReuseThreshold

      int getHighCostConnectionReuseThreshold()
      Obtains the high-cost connection reuse threshold property value for connection labeling.
      Returns:
      The high-cost connection reuse threshold property value currently set.
      See Also:

    • setHighCostConnectionReuseThreshold

      void setHighCostConnectionReuseThreshold(int threshold) throws SQLException
      Sets the high-cost connection reuse threshold for connection labeling. This property works together with the ConnectionLabelingHighCost property to determine when high-cost connections are reused for connection labeling. This property specifies a threshold of the number of total connections in the pool. If Connection Labeling finds all available connections are high-cost connections (i.e., the lowest cost value exceeds the ConnectionLabelingHighCost value), it checks this threshold to determine whether to reuse those connections. Only when this threshold is reached, Connection Labeling will try to reuse the high-cost connections in the pool to serve a labeled connection request. Otherwise, Connection Labeling picks a low-cost connection, a no-label connection available in the pool, or creates a brand-new physical connection to serve a labeled request. For example, if the property value is set to 10, Connection Labeling reuses high-cost connections when there are no low-cost connections available and the total connections reach 10. Note that any labeled connection with cost Integer.MAX_VALUE will not be reused. This is consistent with connection labeling behavior when this property and ConnectionLabelingHighCost are not set. A Connection Labeling callback must be registered at the same time for this property to take effect. The default value is 0, which is treated the same way as MinPoolSize.
      Parameters:
      threshold - The high-cost connection reuse threshold to set.
      Throws:
      SQLException - If any exception occurs while setting the threshold.

    • createConnectionBuilder

      UCPConnectionBuilder createConnectionBuilder()
      Creates a new UCPConnectionBuilder instance.
      Specified by:
      createConnectionBuilder in interface DataSource
      Returns:
      The OracleConnectionBuilder instance that was created

    • createShardingKeyBuilder

      default oracle.jdbc.OracleShardingKeyBuilder createShardingKeyBuilder()
      Creates a new OracleShardingKeyBuilder instance
      Specified by:
      createShardingKeyBuilder in interface CommonDataSource
      Returns:
      The OracleShardingKeyBuilder instance that was created

    • getConnectionRepurposeThreshold

      int getConnectionRepurposeThreshold()
      Gets the connection repurpose threshold for the pool. This property is used in cases when the connection pool is shared by multiple datasources connecting to the same database but using different services.Only when this threshold is reached the pool will try to repurpose connections between different services before trying to create new connections. This property is applicable only for multi-tenant databases.
      Returns:
      connection repurpose threshold property value currently set.

    • setConnectionRepurposeThreshold

      void setConnectionRepurposeThreshold(int threshold) throws SQLException
      Sets the connection repurpose threshold for the pool. This property is applicable only for multi-tenant databases.
      Parameters:
      threshold - connection repurpose threshold to set.
      Throws:
      SQLException - If any exception occurs while setting the threshold.
      See Also:

    • getPdbRoles

      Properties getPdbRoles()
      Gets the PDB roles specified for this datasource
      Returns:
      roles key values pairs that correspond to the role names and password that are set for this datasource

    • getServiceName

      String getServiceName()
      Gets the service name set on this data source
      Returns:
      service name on this data source

    • getSecondsToTrustIdleConnection

      int getSecondsToTrustIdleConnection()
      Gets the seconds To Trust Idle Connection value.
      Returns:
      The seconds To Trust Idle Connection.

    • setSecondsToTrustIdleConnection

      void setSecondsToTrustIdleConnection(int secondsToTrustIdleConnection) throws SQLException
      Sets the time in seconds to trust an idle connection to skip a validation test. It works in conjunction with setValidateConnectionOnBorrow(boolean). When set to any positive value, a connection validation during the checkout is skipped if the connection was successfully used and returned to the pool within the time specified for secondsToTrustIdleConnection. Default value is set to 0 seconds which means that the feature is disabled.

      With this mode enabled, UCP will do a SOCKET validation on every connection borrow and default driver validation type (can be changed with the "oracle.jdbc.defaultConnectionValidation" system property) after designated seconds to trust idle connection has passed

      * @param secondsToTrustIdleConnection The value of how long a connection can be trusted to skip connectionValidationOnBorrow
      Throws:
      SQLException - in case of inability to set these seconds.

    • reconfigureDataSource

      void reconfigureDataSource(Properties configuration) throws SQLException
      Reconfigures the data source. This API can be only used to modify existing data source properties. To add a new data source to a running pool instance, use PoolDataSourceFactory's getPoolDataSource(Properties configuration) API instead. Only the following data source properties can be modified using this API: user, password, description, serviceName, pdbRoles.
      Parameters:
      configuration - the configuration input
      Throws:
      SQLException - If an error occurs while configuring the data source.

    • getMaxConnectionsPerService

      int getMaxConnectionsPerService()
      Gets the maximum number of connections that can be obtained to a particular service, in a shared pool.
      Returns:
      The maximum number of connections that can be obtained to a particular service.

    • getQueryTimeout

      int getQueryTimeout()
      Gets the number of seconds the driver will wait for a Statement object to execute to the given number of seconds.
      Returns:
      The query timeout in seconds

    • setQueryTimeout

      void setQueryTimeout(int queryTimeout) throws SQLException
      Sets the number of seconds the driver will wait for a Statement object to execute to the given number of seconds.
      Parameters:
      queryTimeout - in seconds
      Throws:
      SQLException - in case of inability to set that timeout.

    • getMaxConnectionsPerShard

      int getMaxConnectionsPerShard()
      Gets the currently configured max connections that can be created per shard from this connection pool.
      Returns:
      The configured max number of connections that can be created per shard.

    • setMaxConnectionsPerShard

      void setMaxConnectionsPerShard(int maxConnectionsPerShard) throws SQLException
      Sets the max number of connections that can be created per shard from this connection pool. (Note: This property is applicable to Sharded databases only. It should not be used when the Sharded database is configured with Oracle Golden Gate)
      Parameters:
      maxConnectionsPerShard - The max number of connections that can be created per shard
      Throws:
      SQLException - if there is an any exception while setting this parameter

    • setShardingMode

      void setShardingMode(boolean shardingMode) throws SQLException
      This API changes the mode of UCP when UCP is using a Sharded Database. By default UCP requires the caller to provide a sharding key for every connection request. When switching off the sharding mode, UCP behaves like a regular connection pool and all the sharding features are disabled so that a caller can request a connection without providing any sharding key.
      Parameters:
      shardingMode - Mode of UCP when using a Sharded Database.
      Throws:
      SQLException - in case of inability to set sharding mode.

    • getShardingMode

      boolean getShardingMode()
      Returns the mode of UCP when UCP is using a Sharded Database. By default sharding mode is ON which means UCP requires the caller to provide a sharding key for every connection request.
      Returns:
      Mode of UCP when using a Sharded Database.

    • setConnectionValidationTimeout

      void setConnectionValidationTimeout(int connectionValidationTimeout) throws SQLException
      This property changes the connection validation timeout which is specified in seconds. Default is 15 seconds. This is the maximum time for connection validation operation. If not completed during this timeout, the connection is treated as invalid.
      Parameters:
      connectionValidationTimeout - timeout to validate connection
      Throws:
      SQLException - if tiomeout is negative

    • getConnectionValidationTimeout

      int getConnectionValidationTimeout()
      Connection validation timeout getter
      Returns:
      the current connection validation timaout value in seconds

    • setSSLContext

      void setSSLContext(SSLContext sslContext)
      Specifies a SSLContext to use as a factory for SSLEngine objects that carry out the TLS protocol.

      The SSLContext must be initialized before setting it on PoolDataSource. The certificates specified by that initialization will be used in place of any connection properties that would otherwise have specified certificates, such as oracle.jdbc.OracleConnection#CONNECTION_PROPERTY_KEYSTORE key store and oracle.jdbc.OracleConnection#CONNECTION_PROPERTY_TRUSTSTORE trust store property values.

      Parameters:
      sslContext - SSLContext instance to be used as an SSLEngine factory.

    • setHostnameResolver

      void setHostnameResolver(PoolDataSource.HostnameResolver hostnameResolver)
      Specifies a PoolDataSource.HostnameResolver to use by the pool
      Parameters:
      hostnameResolver - HostnameResolver instance to be used as a custom DNS name resolver.

    • isReadOnlyInstanceAllowed

      boolean isReadOnlyInstanceAllowed()
      Returns true if the connection borrow is allowed to a read-only instance, false otherwise. This property is applicable to sharded database only. A shard instance can be in read-only mode for a chunk if chunk move/split operation is in progress.
      Returns:
      true if the connection borrow is allowed to a read-only instance, false otherwise.

    • setReadOnlyInstanceAllowed

      void setReadOnlyInstanceAllowed(boolean readOnlyInstanceAllowed) throws SQLException
      Sets the read-only instance allowed value on the datasource. This property is applicable to sharded database only. When the property value is set to true, UCP allows connection borrow to read-only instances as well otherwise not. A shard instance goes into read-only mode for a chunk if the chunk move/split operation is in progress on that instance. The default value is false which means by default connection borrow is not allowed to a read-only instance.
      Parameters:
      readOnlyInstanceAllowed - whether to allow connection borrow to a read-only instance or not
      Throws:
      SQLException - if unable to set property value

    • setTokenSupplier

      void setTokenSupplier(Supplier<? extends oracle.jdbc.AccessToken> tokenSupplier) throws SQLException

      Sets a supplier function that generates an access token when creating a connection with this DataSource. The supplier function is invoked each time this DataSource creates a connection. Instances of AccessToken that are output by the supplier must represent a token type that is supported by Oracle Database for client authentication. The supplier must be thread safe.

      It is invalid to configure this DataSource with both a token supplier and with a user name or password. If invocations of setUser(String), setPassword(String), setConnectionProperties(java.util.Properties), or setConnectionProperty(String, String) have configured this DataSource with a user name or password, and an invocation of this method has also configured a token supplier, then a SQLException indicating an invalid configuration is thrown when creating a connection with this datasource.

      Note that AccessToken.createJsonWebTokenCache(Supplier) can be called to create a thread safe Supplier that caches tokens from a user defined Supplier.

      Parameters:
      tokenSupplier - Token supplying function. Not null.
      Throws:
      NullPointerException - If the tokenSupplier is null.
      SQLException - if unable to set property value

    • isCreateConnectionInBorrowThread

      boolean isCreateConnectionInBorrowThread()
      Returns the connection creation mode: either "true" if connections are created using the borrowing thread, or "false" if connections are created in the background (the default).
      Returns:
      true, if creating connections in a borrow thread, false otherwise.
      See Also:

    • setCreateConnectionInBorrowThread

      void setCreateConnectionInBorrowThread(boolean createConnectionInBorrowThread) throws SQLException

      Set this flag to true to make UCP use the borrowing thread to create new connections. By default, connections are created in the background. The only reason why you may want to set this to "true" is to make a connection request fail-fast if the driver throws an exception while connecting; otherwise, the background task will keep trying until the connection wait timeout expires.

      If this property is set to false, a pool waits no longer than a designated connection wait duration no matter how long it takes to create a new connection to grow a pool, if no connection is available at this moment. If this property is set to true, then in this backward compatibility mode a pool waits for a connection to be synchronously created in a borrow thread, and the waiting time can take longer than connectionWaitDuration. For connectionWaitDuration please refer to setConnectionWaitDuration(java.time.Duration).

      Parameters:
      createConnectionInBorrowThread - if true, create connections in a borrow thread.
      Throws:
      SQLException - if unable to set property value.

    • isCommitOnConnectionReturn

      boolean isCommitOnConnectionReturn()
      Returns the boolean value for the property that controls the behavior of UCP when a connection is released back to the pool with pending uncommitted changes in an active transaction. By default, UCP will commit the changes (default value is "true"). When setting this property to "false" the changes will be rolled back.
      Returns:
      true to commit, false to rollback.

    • setCommitOnConnectionReturn

      void setCommitOnConnectionReturn(boolean commit) throws SQLException
      Sets the boolean value for the property that controls the behavior of UCP when a connection is released back to the pool with pending uncommitted changes in an active transaction. By default, UCP will commit the changes (default value is "true"). When setting this property to "false" the changes will be rolled back.
      Parameters:
      commit - 'true' to commit, 'false' to rollback. The default is 'true'.
      Throws:
      SQLException