Oracle Universal Connection Pool
Release 12.2.0.0.0

Production README
=======================================================================


Contents Of This Release
------------------------

For all platforms:

  [ORACLE_HOME]/ucp/lib contains:

  - ucp.jar
    Classes for use with JDK 6 and JDK 7. It contains the Universal
    Connection Pool classes, as well as the built-in JDBC Pool Adapter
    classes for standalone UCP / JDBC applications.

  - ucpdemos.jar
    Classes for use with JDK 6 and JDK 7. It contains the Universal
    Connection Pool demos and code samples, sample logging configurations,
    and a quick-start toolkit for Fast Connection Failover.

  Javadoc / Documentation / Demo:

    All of the above are also available for download on OTN.


Installation
------------

The Oracle Installer puts the Universal Connection Pool files in the
[ORACLE_HOME]/ucp directory.


Setting Up Your Environment
---------------------------

On Windows platforms:
  - Add [ORACLE_HOME]\ucp\lib\ucp.jar to your CLASSPATH.

On all Unix platforms:
  - Add [ORACLE_HOME]/ucp/lib/ucp.jar to your CLASSPATH.


Important Notes
---------------

 * UCP works with older Oracle databases such as 11g and 10g databases,
   as well as non-Oracle databases such as DB2, SQLServer. Please refer
   to OTN for complete UCP certification information, including JDBC driver
   and vendor database versions.

 * UCP's connection affinity features (Web-session based affinity and
   Transaction based affinity) are designed to work with Oracle Real
   Application Clusters (RAC) 11.1 or above, since they are designed to
   leverage features of the 11g RAC database. These UCP features may not
   work as expected with older RAC versions.

 * In this release, UCP can automatically retrieve the ONS configuration
   information generated by the database server for features like FCF,
   Applications, however, still have the option to override such configuration
   by calling PoolDataSource.setONSConfiguration(String remoteONSConfig).
   For more detail, please refer to the "Using Global Data Services" section
   in the UCP 12.2 documentation.

 * RAC features now support more than 128 instances. This was an upper limit
   in previous releases.

 * Runtime Connection Load-Balancing (RCLB) is significantly improved.
   Connection opening and closing are minimized, and RCLB follows server
   advisories more closely and smoothly. UCP 12.2 also provides enhanced
   RCLB statistics information in the logs.

 * A strict-affinity mode is added for connection affinity features.
   Applications that require connections to always go to the same instance
   can set the system property "oracle.ucp.jdbc.oracle.affinity.strict"
   to true. In this mode, UCP throws an exception if it cannot find an
   available connection to the affinity instance. For more detail, please
   refer to the "Using Connection Affinity" section in the UCP 12.2
   documentation.

 * AbandonedConnectionTimeout processing is more graceful on borrowed
   connections with long-running queries. Please refer to the "Setting
   the Abandon Connection Timeout" section in the UCP 12.2 documentation.

 * This release supports automatic bad-connection removal. Any JDBC
   connection hitting SQLRecoverableException will not be returned to
   the pool.

 * If you are using UCP's Connection Labeling feature, and enabled Fast
   Connection Failover as well as RAC Load Balancing Advisory, note that
   UCP's Runtime Connection Load-Balancing (RCLB) takes precedence over
   connection labeling. In other words, in a RAC enabled environment,
   UCP's RCLB would provide better performance characteristics than
   generic Connection Labeling feature.


Known Problems/Limitations In This Release
------------------------------------------

 * Bug #15880508: UCP's Runtime Connection Load-Balancing (RCLB) feature
   in 12.1 requires Oracle JDBC 12.1 driver jars to function. This applies
   when using either THIN or JDBC-OCI driver.

 * Using Connection Labeling with Database Resident Connection Pooling
   (DRCP) may not yield optimal performance, because of DRCP's simple
   tagging support.

 * For applications using the built-in pool adapter PoolDataSource and
   PoolXADataSource, the pool allows dynamic setting of properties on
   the specified connection factory, such as connect-URL, host, port,
   etc., during run-time. However, other than connect-URL, the pool
   does not refresh itself when setting other connection factory properties.
   This applies to both standard connection factory properties (for
   example, those on javax.sql.DataSource including user, password,
   portNumber, databaseName, etc.), and customized properties specific
   to a connection factory.

   Workaround: Application should try to avoid dynamic setting of
     important connection factory properties, after the pool has been
     populated with connections. If this can not be avoided, application
     can explicitly perform pool refresh after all dynamic property set.


Problems/Limitations Fixed in This Release
------------------------------------------

BUG-15858757
    Excessive connection open and close during pool start

BUG-14734972
    UCP JDBC proxies reference non-public driver interfaces

BUG-14588478 and 13982926
    Handle bad connections inside UCP JDBC proxies

BUG-14546567
    Slow pool startup with large InitialPoolSize configured

BUG-14402709
    Statement.isClosed() returns wrong value after closeOnCompletion()

BUG-14324523
    Blocking issue during FAN UP-event processing

BUG-14107279
    UCP isValid(0) behaves incorrectly on connection proxies

BUG-14067981
    Obscure error message "All connections are in use"

BUG-13926828
    Problem in handling connection wait timeout under heavy load

BUG-13916297
    AbandonedConnectionTimeout aborts long running query

BUG-13889871
    Synchronization issue in connection request queue

BUG-13879083
    Incorrect per-instance connection counts

BUG-13829763
    Logoff trigger does not fire with sessions created by UCP

BUG-13113879
    Connection validation blocks pool

BUG-13090371
    InstanceAlreadyExistsException occurs when creating a second pool instance

BUG-12908935
    Labeling callback configure() is not called on new connections

BUG-12720962
    Cannot use service name in upper-case with FCF

BUG-12596492
    Delayed FAN processing due to connection validation

BUG-12317354
    GetFCFProcessingInfo() returns empty string for non-processed FAN events

BUG-11927620
    Need MBean operation to map pool name to its MBean

BUG-11725265
    InactiveConnectionTimeout causes excessive connection close/open

BUG-10323666
    NoClassDefFoundError during MBean registration causes pool to error out

