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 Details

    • allowedProviders

      static final Set<String> allowedProviders

  • Method Details

    • getType

      String getType()
      Type of provider (eg: 'azure' for Azure App Configuration).
      Returns:
      type of the provider

    • getConnectionProperties

      Properties getConnectionProperties(String parameters) throws 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:
      SQLException

    • find

      static OracleConfigurationProvider find(String providerType)
      Helper method to retrieve a provider based on the type.
      Parameters:
      providerType -
      Returns:
      OracleConfigurationProvider

    • mapOptions

      static Map<String,String> mapOptions(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.