Package oracle.ucp.jdbc

Interface UCPXAConnectionBuilder

  • All Superinterfaces:
    javax.sql.XAConnectionBuilder
    public interface UCPXAConnectionBuilder
extends javax.sql.XAConnectionBuilder
    A builder created from a PoolXADataSource object, used to get a connection to the database that the PoolXADataSource object represents. The connection properties that were specified for the PoolXADataSource are used as the default values by the UCPXAConnectionBuilder.

    To use the builder, the corresponding builder method needs to be called for each parameter that needs to be part of the connection request followed by a build() method. The order in which the builder methods are called is not important. However if the same builder attribute is applied more than once, only the most recent value will be considered while building the connection. The builder object can be reused to build more than one connection and the builder attributes will be retained across multiple invocations of the build() method.

    The following example illustrates the use of UCPXAConnectionBuilder to get a XAConnection: 

     
   PoolXADataSource pdsXa = new PoolXADataSourceImpl();
   OracleShardingKey superShardingKey = pdsXa.createShardingKeyBuilder()
                                             .subkey("EASTERN_REGION", JDBCType.VARCHAR)
                                             .build();
   OracleShardingKey shardingKey = pdsXa.createShardingKeyBuilder()
                                        .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
                                        .build();
                                
   OracleConnection connection = pds.createConnectionBuilder()
                                    .user("rafa")
                                    .password("tennis")
                                    .shardingKey(shardingKey)
                                    .superShardingKey(superShardingKey)
                                    .build();

    • Method Detail

      • user

        UCPXAConnectionBuilder user​(java.lang.String user)
        Sets the user attribute on the builder
        Specified by:
        user in interface javax.sql.XAConnectionBuilder
        Parameters:
        user - the database user on whose behalf the connection is being made
        Returns:
        this builder object

      • password

        UCPXAConnectionBuilder password​(java.lang.String password)
        Sets the password attribute on the builder
        Specified by:
        password in interface javax.sql.XAConnectionBuilder
        Parameters:
        password - to set
        Returns:
        this connection builder object

      • labels

        UCPXAConnectionBuilder labels​(java.util.Properties labels)
        Sets the labels attribute on the builder
        Parameters:
        labels - The requested connection labels.
        Returns:
        this connection builder object

      • serviceName

        UCPXAConnectionBuilder serviceName​(java.lang.String serviceName)
        Sets the service name attribute on the builder
        Parameters:
        serviceName - to retrieve the connection
        Returns:
        this connection builder instance

      • proxyProperties

        UCPXAConnectionBuilder proxyProperties​(int proxyType,
                                       java.util.Properties proxyProperties)
        Sets the proxy properties on the builder that is used to create proxy session of the particular type as specified by the parameter proxyType
        Parameters:
        proxyType - create proxy session of this type
        proxyProperties - connection with these proxy properties
        Returns:
        this connection builder instance

      • shardingKey

        UCPXAConnectionBuilder shardingKey​(oracle.jdbc.OracleShardingKey shardingKey)
        Parameters:
        shardingKey - Sharding Key object that needs to be part of connection request
        Returns:
        This instance of the connection builder.

      • superShardingKey

        UCPXAConnectionBuilder superShardingKey​(oracle.jdbc.OracleShardingKey superShardingKey)
        Parameters:
        superShardingKey - Super shardingKey key object that needs to be part of connection request
        Returns:
        This instance of the connection builder.

      • pdbRoles

        UCPXAConnectionBuilder pdbRoles​(java.util.Properties pdbRoles)
        Sets the PDB roles to be set on the connection from the pool in connection repurposing case for a multitenant database.
        Parameters:
        pdbRoles - PDB roles and their passwords passed in as key value pairs
        Returns:
        This instance of the connection builder.

      • build

        javax.sql.XAConnection build()
                      throws java.sql.SQLException
        Builds the XA connection object.
        Specified by:
        build in interface javax.sql.XAConnectionBuilder
        Returns:
        XAConnection created considering the builder attributes
        Throws:
        java.sql.SQLException - if there is a failure in building the connection.

      • buildAsyncOracle

        default java.util.concurrent.CompletionStage<javax.sql.XAConnection> buildAsyncOracle()
                                                                               throws java.lang.UnsupportedOperationException
        Creates a completion stage for a connection. The returned stage will be completed when the pool has an available connection to borrow.
        Returns:
        A CompletionStage which completes with a connection borrowed from the pool.
        Throws:
        java.lang.UnsupportedOperationException - if this method is not implemented

      • buildConnectionPublisherOracle

        default java.util.concurrent.Flow.Publisher<javax.sql.XAConnection> buildConnectionPublisherOracle()
                                                                                            throws java.lang.UnsupportedOperationException
        Creates a Flow.Publisher for a connection. The returned stage will be completed when the pool has an available connection to borrow.
        Returns:
        A CompletionStage which completes with a connection borrowed from the pool.
        Throws:
        java.lang.UnsupportedOperationException - if this method is not implemented

      • executor

        default UCPXAConnectionBuilder executor​(java.util.concurrent.Executor executor)
                                 throws java.lang.UnsupportedOperationException
        Submits an executor to be used in the asynchronous builder's operations.
        Parameters:
        executor - - executor to submit (default is ForkJoinPool)
        Returns:
        a builder
        Throws:
        java.lang.UnsupportedOperationException

      • connectionWaitTimeout

        @Deprecated
UCPXAConnectionBuilder connectionWaitTimeout​(int timeout)
        Deprecated.
        Set connection wait timeout (in seconds) for this connection builder particularly. if not set, the PoolDataSource's setting will be used.

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

        Parameters:
        timeout - - connection wait timeout (in seconds).
        Returns:
        This instance of the connection builder.

      • connectionWaitDuration

        UCPXAConnectionBuilder connectionWaitDuration​(java.time.Duration duration)
        Set connection wait timeout (in java.time.Duration) for this connection builder particularly. if not set, the PoolDataSource's setting will be used.
        Parameters:
        duration - - connection wait timeout (in java.time.Duration).
        Returns:
        This instance of the connection builder.