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	compose(DriverConfigLoader primaryConfigLoader, DriverConfigLoader fallbackConfigLoader) Composes two existing config loaders to form a new one.
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	fromClasspath(String resourceBaseName, ClassLoader appClassLoader) Just like fromClasspath(java.lang.String) except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.
static DriverConfigLoader	fromDefaults(ClassLoader appClassLoader) Builds an instance using the driver's default implementation (based on Typesafe config) except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.
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	fromMap(OptionsMap source) Builds an instance backed by an OptionsMap, which holds all options in memory.
static DriverConfigLoader	fromPath(Path file) Builds an instance using the driver's default implementation (based on Typesafe config), except that application-specific options are loaded from the given path.
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.
static ProgrammaticDriverConfigLoaderBuilder	programmaticBuilder(ClassLoader appClassLoader) Just like programmaticBuilder() except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.
CompletionStage<Boolean>	reload() Triggers an immediate reload attempt and returns a stage that completes once the attempt is finished, with a boolean indicating whether the configuration changed as a result of this reload.
boolean	supportsReloading() Whether this implementation supports programmatic reloading with the reload() method.

Method Detail

fromDefaults

@NonNull
static DriverConfigLoader fromDefaults(@NonNull
                                                ClassLoader appClassLoader)

Builds an instance using the driver's default implementation (based on Typesafe config) except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.

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

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.

The class loader used to locate application-specific classpath resources is the current thread's context class loader. This might not be suitable for OSGi deployments, which should use fromClasspath(String, ClassLoader) instead.

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.

fromClasspath

@NonNull
static DriverConfigLoader fromClasspath(@NonNull
                                                 String resourceBaseName,
                                                 @NonNull
                                                 ClassLoader appClassLoader)

Just like fromClasspath(java.lang.String) except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.

fromPath

@NonNull
static DriverConfigLoader fromPath(@NonNull
                                            Path file)

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

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.

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.

Note that fromMap(OptionsMap) provides an alternative approach for programmatic configuration, that might be more convenient if you wish to completely bypass Typesafe config.

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 class loader used to locate application-specific classpath resources is the current thread's context class loader. This might not be suitable for OSGi deployments, which should use programmaticBuilder(ClassLoader) instead.

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.

See Also:

fromMap(OptionsMap)

programmaticBuilder

@NonNull
static ProgrammaticDriverConfigLoaderBuilder programmaticBuilder(@NonNull
                                                                          ClassLoader appClassLoader)

Just like programmaticBuilder() except that application-specific classpath resources will be located using the provided ClassLoader instead of the current thread's context class loader.

fromMap

@NonNull
static DriverConfigLoader fromMap(@NonNull
                                           OptionsMap source)

Builds an instance backed by an OptionsMap, which holds all options in memory.

This is the simplest implementation. It is intended for clients who wish to completely bypass Typesafe config, and instead manage the configuration programmatically. A typical example is a third-party tool that already has its own configuration file, and doesn't want to introduce a separate mechanism for driver options.

With this loader, the driver's built-in reference.conf file is ignored, the provided OptionsMap must explicitly provide all mandatory options. Note however that OptionsMap.driverDefaults() allows you to initialize an instance with the same default values as reference.conf.

 // This creates a configuration equivalent to the built-in reference.conf:
 OptionsMap map = OptionsMap.driverDefaults();

 // Customize an option:
 map.put(TypedDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(5));

 DriverConfigLoader loader = DriverConfigLoader.fromMap(map);
 CqlSession session = CqlSession.builder()
     .withConfigLoader(loader)
     .build();
 

If the OptionsMap is modified at runtime, this will be reflected immediately in the configuration, you don't need to call reload(). Note however that, depending on the option, the driver might not react to a configuration change immediately, or ever (this is documented in reference.conf).

Since:

4.6.0

compose

@NonNull
static DriverConfigLoader compose(@NonNull
                                           DriverConfigLoader primaryConfigLoader,
                                           @NonNull
                                           DriverConfigLoader fallbackConfigLoader)

Composes two existing config loaders to form a new one.

When the driver reads an option, the "primary" config will be queried first. If the option is missing, then it will be looked up in the "fallback" config.

All execution profiles will be surfaced in the new config. If a profile is defined both in the primary and the fallback config, its options will be merged using the same precedence rules as described above.

The new config is reloadable if at least one of the input configs is. If you invoke reload() on the new loader, it will reload whatever is reloadable, or fail if nothing is. If the input loaders have periodic reloading built-in, each one will reload at its own pace, and the changes will be reflected in the new config.

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 and 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 stage should fail immediately with an UnsupportedOperationException. The default implementation of this interface does support programmatic reloading however, and never returns a failed stage.

supportsReloading

boolean supportsReloading()

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

The default implementation of this interface does support programmatic reloading and always returns true.

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