Package oracle.jdbc

Interface OracleConnectionBuilder

  • All Superinterfaces:
    java.sql.ConnectionBuilder, OracleCommonConnectionBuilder
    All Known Implementing Classes:
    OracleConnectionBuilderImpl
    public interface OracleConnectionBuilder
extends OracleCommonConnectionBuilder
    A builder created from a OracleDataSource object, used to establish a connection to the database that the OracleDataSource object represents. The connection properties that were specified for the OracleDataSource are used as the default values by the OracleConnectionBuilder.

    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 OracleConnectionBuilder to create a OracleConnection: 

      
    OracleDataSource ods = new oracle.jdbc.pool.OracleDataSource();
    OracleShardingKey superShardingKey =
        ods.createShardingKeyBuilder()
           .subkey("EASTERN_REGION", JDBCType.VARCHAR)
           .build();
    OracleShardingKey shardingKey =
        ods.createShardingKeyBuilder()
           .subkey("PITTSBURGH_BRANCH", JDBCType.VARCHAR)
           .build();
    OracleConnection connection = ods.createConnectionBuilder()
                                     .user("rafa")
                                     .password("tennis")
                                     .shardingKey(shardingKey)
                                     .superShardingKey(superShardingKey)
                                     .build();

    Since:
    12.2

    • Method Detail

      • user

        OracleConnectionBuilder user​(java.lang.String user)
        Specified by:
        user in interface java.sql.ConnectionBuilder
        Parameters:
        user -
        Returns:
        This OracleConnectionBuilder

      • password

        OracleConnectionBuilder password​(java.lang.String password)
        Specified by:
        password in interface java.sql.ConnectionBuilder
        Parameters:
        password -
        Returns:
        This OracleConnectionBuilder

      • shardingKey

        OracleConnectionBuilder shardingKey​(OracleShardingKey shardingKey)
        Parameters:
        shardingKey - Sharding Key object that needs to be part of connection request
        Returns:
        This OracleConnectionBuilder

      • superShardingKey

        OracleConnectionBuilder superShardingKey​(OracleShardingKey superShardingKey)
        Parameters:
        superShardingKey - Super sharding key object that needs to be part of connection request
        Returns:
        This OracleConnectionBuilder

      • shardingKey

        OracleConnectionBuilder shardingKey​(java.sql.ShardingKey shardingKey)
        Specified by:
        shardingKey in interface java.sql.ConnectionBuilder
        Parameters:
        shardingKey - Sharding Key object that needs to be part of connection request
        Returns:
        This OracleConnectionBuilder

      • superShardingKey

        OracleConnectionBuilder superShardingKey​(java.sql.ShardingKey superShardingKey)
        Specified by:
        superShardingKey in interface java.sql.ConnectionBuilder
        Parameters:
        superShardingKey - Super sharding key object that needs to be part of connection request
        Returns:
        This OracleConnectionBuilder

      • gssCredential

        OracleConnectionBuilder gssCredential​(org.ietf.jgss.GSSCredential credential)
        Provide the GSSCredential used to authenticate the connection.
        Parameters:
        credential - used to authenticate the connection. Not null.
        Returns:
        This OracleConnectionBuilder

      • sslContext

        OracleConnectionBuilder sslContext​(javax.net.ssl.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 building the connection. The certificates specified by that initialization will be used in place of any connection properties that would otherwise have specified certificates, such as key store and trust store property values.

        Specifying a null value will clear any non-null value that may have been set previously, causing this builder to behave as if this method had never been called at all.

        Parameters:
        sslContext - An SSLContext to use as an SSLEngine factory. May be null.
        Returns:
        This OracleConnectionBuilder
        Since:
        20

      • radiusChallengeResponseHandler

        OracleConnectionBuilder radiusChallengeResponseHandler​(java.util.function.Function<byte[],​byte[]> radiusAuthenticationHandler)
        Specifies the Function that will be used during the Challenge/Response phase of RADIUS authentication.

        The byte[] input is the challenge hint text that is used while prompting the user for a response. The text is UTF-8 encoded. The handler is expected to return the response for the challenge as byte[].

        Challenge response handler can also be configured via connection property OracleConnection.CONNECTION_PROPERTY_THIN_NET_RADIUS_CHALLENGE_RESPONSE_HANDLER


        Example: 
              OracleDataSource ods  = new OracleDataSource();
      ods.setURL(url);
      ods.setUser("myRadiusUser");
      ods.setPassword("myRadiusPassword");
      OracleConnection conn  = (OracleConnection)ods.createConnectionBuilder()
            .radiusChallengeResponseHandler((hint) -> {
              // do some processing to calculate the challenge response
              final String response = getChallengeResponse(hint);
              return response.getBytes(StandardCharsets.UTF_8);
            }).build();
        Parameters:
        radiusAuthenticationHandler - Radius authentication handler. May be null.
        Returns:
        This OracleConnectionBuilder
        Since:
        23ai

      • traceEventListener

        OracleConnectionBuilder traceEventListener​(TraceEventListener traceEventListener)
        Configures a TraceEventListener that receives events from connections built by this builder.
        Parameters:
        traceEventListener - Listener that receives trace events. May be null to disable tracing.
        Returns:
        This OracleConnectionBuilder.

      • hostnameResolver

        OracleConnectionBuilder hostnameResolver​(OracleHostnameResolver hostnameResolver)
        Sets a custom hostname resolver implementing OracleHostnameResolver used to provide a custom DNS name resolution strategy to locate the database host.
        Parameters:
        hostnameResolver - an OracleHostnameResolver to use when resolving the datasource hostname
        Returns:
        This OracleConnectionBuilder
        Since:
        23

      • readOnlyInstanceAllowed

        OracleConnectionBuilder readOnlyInstanceAllowed​(boolean readOnlyInstanceAllowed)
        Sets the read-only instance allowed value on this builder. This property is applicable to sharded database only. When the property value is set to true, the database allows connection creation 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 creation is not allowed to a read-only instance.
        Parameters:
        readOnlyInstanceAllowed - whether to allow connection creation to a read-only instance or not
        Returns:
        This OracleConnectionBuilder

      • executorOracle

        OracleConnectionBuilder executorOracle​(java.util.concurrent.Executor executor)

        Set the Executor used for asynchronous tasks by this ConnectionBuilder and any Connection objects built by it. The default value is ForkJoinPool.commonPool().

        Oracle JDBC implements this OracleCommonConnection method to return this instance of OracleConnectionBuilder.

        Specified by:
        executorOracle in interface OracleCommonConnectionBuilder
        Parameters:
        executor - an Executor to use for asynchronous tasks. Not null.
        Returns:
        this OracleCommonConnectionBuilder

      • accessToken

        OracleConnectionBuilder accessToken​(AccessToken accessToken)

        Specifies the accessToken to be used when creating a connection. The issuer of the token must be one that is supported by Oracle Database for client authentication.

        It is invalid to configure this builder with both a token and with a username or password. If both this method and password(String) or user(String) are invoked with non null values, then a SQLException indicating an invalid configuration is thrown when creating a connection with this builder.

        Parameters:
        accessToken - the token to use for this connection. Not null.
        Returns:
        the same ConnectionBuilder instance
        Throws:
        java.lang.NullPointerException - If the accessToken is null.

      • buildAsyncOracle

        java.util.concurrent.CompletionStage<OracleConnection> buildAsyncOracle()
                                                                 throws java.sql.SQLException
        Returns a CompletionStage that completes with a Connection having the same state as if it were built by calling build on this ConnectionBuilder.

        The returned stage is completed exceptionally with a SQLException if a failure occurs when building the Connection.

        Returns:
        a CompletionStage that completes with a Connection built by this ConnectionBuilder
        Throws:
        java.sql.SQLException
        Since:
        20

      • buildConnectionPublisherOracle

        java.util.concurrent.Flow.Publisher<OracleConnection> buildConnectionPublisherOracle()
                                                                              throws java.sql.SQLException

        Returns a Publisher that publishes a single Connection object with the same state as if it were built by calling build on this ConnectionBuilder. The returned Publisher does not support multiple Subscribers.

        Oracle JDBC implements this OracleCommonConnection method to publish an instance of OracleConnection.

        Specified by:
        buildConnectionPublisherOracle in interface OracleCommonConnectionBuilder
        Returns:
        a Publisher of a Connection built by this ConnectionBuilder
        Throws:
        java.sql.SQLException

      • build

        OracleConnection build()
                throws java.sql.SQLException
        Builds the connection object.
        Specified by:
        build in interface java.sql.ConnectionBuilder
        Returns:
        New OracleConnection that is created.
        Throws:
        java.sql.SQLException