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 Summary

All Methods Instance Methods Abstract Methods
`OracleConnectionBuilder` `accessToken​(AccessToken accessToken)` Specifies the `accessToken` to be used when creating a connection.
`OracleConnection` `build()` Builds the connection object.
`java.util.concurrent.CompletionStage<OracleConnection>` `buildAsyncOracle()` Returns a `CompletionStage` that completes with a `Connection` having the same state as if it were built by calling `build` on this `ConnectionBuilder`.
`java.util.concurrent.Flow.Publisher<OracleConnection>` `buildConnectionPublisherOracle()` Returns a `Publisher` that publishes a single `Connection` object with the same state as if it were built by calling `build` on this `ConnectionBuilder`.
`OracleConnectionBuilder` `executorOracle​(java.util.concurrent.Executor executor)` Set the `Executor` used for asynchronous tasks by this `ConnectionBuilder` and any `Connection` objects built by it.
`OracleConnectionBuilder` `gssCredential​(org.ietf.jgss.GSSCredential credential)` Provide the GSSCredential used to authenticate the connection.
`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.
`OracleConnectionBuilder` `password​(java.lang.String password)`
`OracleConnectionBuilder` `radiusChallengeResponseHandler​(java.util.function.Function<byte[],​byte[]> radiusAuthenticationHandler)` Specifies the `Function` that will be used during the Challenge/Response phase of RADIUS authentication.
`OracleConnectionBuilder` `readOnlyInstanceAllowed​(boolean readOnlyInstanceAllowed)` Sets the read-only instance allowed value on this builder.
`OracleConnectionBuilder` `shardingKey​(java.sql.ShardingKey shardingKey)`
`OracleConnectionBuilder` `shardingKey​(OracleShardingKey shardingKey)`
`OracleConnectionBuilder` `sslContext​(javax.net.ssl.SSLContext sslContext)` Specifies a `SSLContext` to use as a factory for SSLEngine objects that carry out the TLS protocol.
`OracleConnectionBuilder` `superShardingKey​(java.sql.ShardingKey superShardingKey)`
`OracleConnectionBuilder` `superShardingKey​(OracleShardingKey superShardingKey)`
`OracleConnectionBuilder` `tracer​(Tracer tracer)` Sets the `Tracer` object on this `OracleConnectionBuilder`.
`OracleConnectionBuilder` `user​(java.lang.String user)`

### Method Detail

#### user

    OracleConnectionBuilder user​(java.lang.String user)

Specified by:
  `user` in interface `java.sql.ConnectionBuilder`
Parameters:
  `user` -
Returns:
  This `OracleConnectionBuilder` object

#### password

    OracleConnectionBuilder password​(java.lang.String password)

Specified by:
  `password` in interface `java.sql.ConnectionBuilder`
Parameters:
  `password` -
Returns:
  This `OracleConnectionBuilder` object

#### shardingKey

    OracleConnectionBuilder shardingKey​(OracleShardingKey shardingKey)

Parameters:
  `shardingKey` - Sharding Key object that needs to be part of connection request
Returns:
  This `OracleConnectionBuilder` object

#### superShardingKey

    OracleConnectionBuilder superShardingKey​(OracleShardingKey superShardingKey)

Parameters:
  `superShardingKey` - Super sharding key object that needs to be part of connection request
Returns:
  This `OracleConnectionBuilder` object

#### 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` object

#### 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` object

#### 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` object

#### 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.
Returns:
  This `OracleConnectionBuilder` object
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` object
Since:
  23c

#### tracer

    OracleConnectionBuilder tracer​(Tracer tracer)

Sets the `Tracer` object on this `OracleConnectionBuilder`.

Parameters:
  `tracer` - tracer Implementation of `Tracer`
Returns:
  This `OracleConnectionBuilder` object

#### 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` object
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` object

#### 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`