Package oracle.jdbc.spi

## Interface OracleConfigurationProvider

All Known Subinterfaces:
  `OracleConfigurationCachableProvider`

    public interface OracleConfigurationProvider

Using the Service Provider Interface (SPI) abstraction, the Oracle JDBC driver can be configured using a configuration service provider. This interface defines such a configuration service and can be implemented by a provider.

A custom JDBC URL can be used to make the driver load a specific configuration provider. For example, `jdbc:oracle:thin:@config-xyz://{parameters}` will make the driver attempt to load a provider of type "xyz".

The provider returns a Properties object that is applied to the `OracleCommonDataSource.setConnectionProperties(Properties)` using the same rules and priorities, except for the url value, that will be applied with `OracleCommonDataSource.setURL(String)`. A property may be configured by different methods. For example, a username can be set in the connection URL, or configured with the "oracle.jdbc.user" property. The precedence of how properties are set is defined in the JavaDoc of `CONNECTION_PROPERTY_CONFIG_FILE`.

Note: If your `OracleConfigurationProvider` instance requires caching capabilities, consider using `OracleConfigurationCachableProvider` interface for additional caching behaviors.

The system property oracle.jdbc.configurationProviders can be used to indicate which configuration providers can be used by the driver. This value can be "(ALL)" (all providers are enabled) or "(NONE)" (all providers are disabled) or a comma-separated list of allowed providers names (case sensitive) between parenthesis. By default, all providers are enabled. The value is set to "(ALL)".

#### The driver includes built-in providers (file and https) to load the configuration from a JSON document that has the following schema:

- An optional key identifier to define multiple configurations in a single JSON document.

- 'connect_descriptor'. This is the connection descriptor that will be used to create the JDBC URL after adding 'jdbc:oracle:thin:@'. This is the only required property. It also corresponds to the values defined in tnsnames.ora configuration file.
- 'user': The database user. It is an optional string.
- 'password'. The database password. It is an optional object. More information in: `OracleConfigurationSecretProvider`.
- 'wallet_location'. The database wallet binary data (as a Base64 representation) stored in a secret provider. The JDBC Driver sets this property using the URI Data Schema, pre-appending 'data:;base64,' to this value. This only applies to the not-for-production Base64 Secret Provider included in the JDBC Driver. External providers need to pre-append the URI Data Schema. It is an optional object. More information in: `OracleConfigurationSecretProvider`.

#### URL Examples :

- `jdbc:oracle:thin:@config-file//:config.json
  `
- `jdbc:oracle:thin:@config-https://myserver/config/myapp?key=dev
  `

#### Payload Examples:

###### Example with no key:

    {
      "connect_descriptor": "(description=(address_list=(address=(protocol=tcp)
          (host=myhost)(port=5521)))(connect_data=(service_name=myservice)))",
      "user": "scott",
      "password": {
        "type": "base64",
        "value": "dGlnZXI="
      },
      "wallet_location": {
        "type": "base64",
        "value": "bXl3YWxsZXRiaW5hcnlmaWxlCg=="
      },
      "jdbc": {
        "autoCommit": "true"
      }
    }

###### Example with a key:

    {
      "dev": {
        "connect_descriptor": "myhost:5521/myservice",
        "user": "scott",
        "password": {
          "type": "base64",
          "value": "dGlnZXI="
        },
        "jdbc": {
          "oracle.jdbc.ReadTimeout": 1000,
          "defaultRowPrefetch": 20,
          "autoCommit": "false"
        }
      }
    }

### Field Summary

Fields
`static java.util.Set<java.lang.String>` `allowedProviders`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods
`static OracleConfigurationProvider` `find​(java.lang.String providerType)` Helper method to retrieve a provider based on the type.
`java.util.Properties` `getConnectionProperties​(java.lang.String parameters)` Returns the Connection Properties configured in an external provider.
`java.lang.String` `getType()` Type of provider (eg: 'azure' for Azure App Configuration).
`static java.util.Map<java.lang.String,​java.lang.String>` `mapOptions​(java.lang.String urlOptions)` Helper method to map options out of a url.

### Field Detail

#### allowedProviders

    static final java.util.Set<java.lang.String> allowedProviders

### Method Detail

#### getType

    java.lang.String getType()

Type of provider (eg: 'azure' for Azure App Configuration).

Returns:
  type of the provider

#### getConnectionProperties

    java.util.Properties getConnectionProperties​(java.lang.String parameters)
                                          throws java.sql.SQLException

Returns the Connection Properties configured in an external provider. The contract is that the provider would load the properties using the same keys that the driver uses in oracle.jdbc.OracleConnection.

Parameters:
  `parameters` - used by the provider to retrieve the connection properties. Eg: for the 'text' provider is a location in the file system, for the 'http' is a URL, for the 'azure' provider is the name of the App Config followed by prefix of the keys and an optional label. It is the responsibility of the provider to specify its format.
Returns:
  Connection Properties that are applied to the connection. It has the same effect of calling the setProperties API.
Throws:
  `java.sql.SQLException`

#### find

    static OracleConfigurationProvider find​(java.lang.String providerType)

Helper method to retrieve a provider based on the type.

Parameters:
  `providerType` -
Returns:
  OracleConfigurationProvider

#### mapOptions

    static java.util.Map<java.lang.String,​java.lang.String> mapOptions​(java.lang.String urlOptions)

Helper method to map options out of a url.

Parameters:
  `urlOptions` - that contains key-value pairs separated by '&'.
Returns:
  map with the options, where the keys are stored in lowercase.