com.datastax.oss.driver.api.core.config

Interface DriverConfigLoader

All Superinterfaces:

AutoCloseable

public interface DriverConfigLoader
extends AutoCloseable

Manages the initialization, and optionally the periodic reloading, of the driver configuration.

See Also:

SessionBuilder.withConfigLoader(DriverConfigLoader)

Method Summary

Modifier and Type	Method and Description
void	close() Called when the cluster closes.
static DriverConfigLoader	fromClasspath(String resourceBaseName) Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from a classpath resource with a custom name.
static DriverConfigLoader	fromFile(File file) Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from the given file.
static DriverConfigLoader	fromUrl(URL url) Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from the given URL.
DriverConfig	getInitialConfig() Loads the first configuration that will be used to initialize the driver.
void	onDriverInit(DriverContext context) Called when the driver initializes.
static ProgrammaticDriverConfigLoaderBuilder	programmaticBuilder() Starts a builder that allows configuration options to be overridden programmatically.
CompletionStage<Boolean>	reload() Triggers an immediate reload attempt.
boolean	supportsReloading() Whether this implementation supports programmatic reloading with the reload() method.

Method Detail

fromClasspath

@NonNull
static DriverConfigLoader fromClasspath(@NonNull
                                                 String resourceBaseName)

Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from a classpath resource with a custom name.

More precisely, configuration properties are loaded and merged from the following (first-listed are higher priority):

• system properties
• <resourceBaseName>.conf (all resources on classpath with this name)
• <resourceBaseName>.json (all resources on classpath with this name)
• <resourceBaseName>.properties (all resources on classpath with this name)
• reference.conf (all resources on classpath with this name). In particular, this will load the reference.conf included in the core driver JAR, that defines default options for all mandatory options.

The resulting configuration is expected to contain a datastax-java-driver section.

The returned loader will honor the reload interval defined by the option basic.config-reload-interval.

fromFile

@NonNull
static DriverConfigLoader fromFile(@NonNull
                                            File file)

Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from the given file.

More precisely, configuration properties are loaded and merged from the following (first-listed are higher priority):

• system properties
• the contents of file
• reference.conf (all resources on classpath with this name). In particular, this will load the reference.conf included in the core driver JAR, that defines default options for all mandatory options.

The resulting configuration is expected to contain a datastax-java-driver section.

The returned loader will honor the reload interval defined by the option basic.config-reload-interval.

fromUrl

@NonNull
static DriverConfigLoader fromUrl(@NonNull
                                           URL url)

Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from the given URL.

More precisely, configuration properties are loaded and merged from the following (first-listed are higher priority):

• system properties
• the contents of url
• reference.conf (all resources on classpath with this name). In particular, this will load the reference.conf included in the core driver JAR, that defines default options for all mandatory options.

The resulting configuration is expected to contain a datastax-java-driver section.

The returned loader will honor the reload interval defined by the option basic.config-reload-interval.

programmaticBuilder

@NonNull
static ProgrammaticDriverConfigLoaderBuilder programmaticBuilder()

Starts a builder that allows configuration options to be overridden programmatically.

For example:

 DriverConfigLoader loader =
     DriverConfigLoader.programmaticBuilder()
         .withDuration(DefaultDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(5))
         .startProfile("slow")
         .withDuration(DefaultDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(30))
         .endProfile()
         .build();
 

produces the same overrides as:

 datastax-java-driver {
   basic.request.timeout = 5 seconds
   profiles {
     slow {
       basic.request.timeout = 30 seconds
     }
   }
 }
 

The resulting loader still uses the driver's default implementation (based on Typesafe config), except that the programmatic configuration takes precedence. More precisely, configuration properties are loaded and merged from the following (first-listed are higher priority):

• system properties
• properties that were provided programmatically
• application.conf (all resources on classpath with this name)
• application.json (all resources on classpath with this name)
• application.properties (all resources on classpath with this name)
• reference.conf (all resources on classpath with this name). In particular, this will load the reference.conf included in the core driver JAR, that defines default options for all mandatory options.

Note that application.* is entirely optional, you may choose to only rely on the driver's built-in reference.conf and programmatic overrides.

The resulting configuration is expected to contain a datastax-java-driver section.

The loader will honor the reload interval defined by the option basic.config-reload-interval.

Note that the returned builder is not thread-safe.

getInitialConfig

@NonNull
DriverConfig getInitialConfig()

Loads the first configuration that will be used to initialize the driver.

If this loader supports reloading, this object should be mutable and reflect later changes when the configuration gets reloaded.

onDriverInit

void onDriverInit(@NonNull
                  DriverContext context)

Called when the driver initializes. For loaders that periodically check for configuration updates, this is a good time to grab an internal executor and schedule a recurring task.

reload

@NonNull
CompletionStage<Boolean> reload()

Triggers an immediate reload attempt.

Returns:

a stage that completes once the attempt is finished, with a boolean indicating whether the configuration changed as a result of this reload. If so, it's also guaranteed that internal driver components have been notified by that time; note however that some react to the notification asynchronously, so they may not have completely applied all resulting changes yet. If this loader does not support programmatic reloading — which you can check by calling supportsReloading() before this method — the returned object will fail immediately with an UnsupportedOperationException.

supportsReloading

boolean supportsReloading()

Whether this implementation supports programmatic reloading with the reload() method.

close

void close()

Called when the cluster closes. This is a good time to release any external resource, for example cancel a scheduled reloading task.

Specified by:

close in interface AutoCloseable