com.datastax.oss.dsbulk.config

Class ConfigUtils

java.lang.Object

com.datastax.oss.dsbulk.config.ConfigUtils

public class ConfigUtils
extends Object

Constructor Summary

Constructors

Constructor and Description
ConfigUtils()

Method Summary

Modifier and Type	Method and Description
static IllegalArgumentException	convertConfigException(ConfigException e, String basePath) Creates a IllegalArgumentException from a ConfigException, sanitizing the error message for better user experience.
static Config	createApplicationConfig(Path appConfigPath) Creates an unresolved application config for DSBulk, optionally pulling application settings from the given alternate location.
static Config	createReferenceConfig() Creates an unresolved reference config for DSBulk.
static char	getChar(Config config, String path) Returns the character at the given path.
static Charset	getCharset(Config config, String path) Returns the Charset at the given path.
static String	getComments(ConfigValue value) Returns the comments associated with the given value, excluding type hints.
static ConfigValue	getNullSafeValue(Config config, String path) An alternative to Config.getValue(String) that handles null values gracefully instead of throwing.
static Path	getPath(Config config, String path) Returns the Path object at the given path.
static int	getThreads(Config config, String path) Returns the number of threads at the given path.
static Optional<String>	getTypeHint(ConfigValue value) Retrieves the type hint for the given value, if any.
static Optional<String>	getTypeString(Config config, String path) Returns a string representation of the value type at this path.
static URL	getURL(Config config, String path) Returns the URL object at the given path.
static List<URL>	getURLsFromFile(Path urlfile) Loads list of URLs from a file given as the urlfile argument using encoding.
static ConfigValueType	getValueType(Config config, String path) Alternative to ConfigValue.valueType() that honors any type hints found in the configuration, if any.
static boolean	hasReferenceValue(Config config, String path) Checks whether the given path has a default value or not.
static boolean	hasUserOverride(Config config, String path) Checks whether the given path has a user-defined value or not.
static boolean	isLeaf(ConfigValue value) Returns true if the given value is a leaf.
static boolean	isLeaf(String line) Checks the given line for the presence of an @leaf annotation.
static boolean	isPathPresentAndNotEmpty(Config config, String path) Checks if the given path is present and its value is a non-empty string.
static boolean	isTypeHint(String line) Checks the given line for the presence of an @type annotation.
static Config	readPassword(Config config, String path, Console console) Reads a password from the console, then returns a new Config object containing the password read under the given path.
static Path	resolvePath(String path) Resolves the given path.
static int	resolveThreads(String threadsStr) Resolves the given input as a positive integer representing the number of threads to allocate.
static URL	resolveURL(String url) Resolves the given URL.
static Optional<Path>	resolveUserHome(String path) Resolves a path starting with "~" against the current user's home directory.
static Config	standaloneDriverReference() Creates a resolved config containing only the driver settings that DSBulk overrides.
static Config	standaloneDSBulkReference() Creates a resolved config containing only DSBulk settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConfigUtils

public ConfigUtils()

Method Detail

standaloneDSBulkReference

public static Config standaloneDSBulkReference()

Creates a resolved config containing only DSBulk settings.

The reference config is obtained from all classpath resources named dsbulk-reference.conf.

This method is only useful for documentation purposes.

Returns:

a resolved reference config containing only the driver settings that DSBulk overrides.

standaloneDriverReference

public static Config standaloneDriverReference()

Creates a resolved config containing only the driver settings that DSBulk overrides.

The reference config is obtained from all classpath resources named driver-reference.conf.

This method is only useful for documentation purposes.

Returns:

a resolved reference config containing only the driver settings that DSBulk overrides.

createReferenceConfig

@NonNull
public static Config createReferenceConfig()

Creates an unresolved reference config for DSBulk.

The reference config is obtained from the following stack:

1. All classpath resources named dsbulk-reference.conf: DSBulk specific settings.
2. All classpath resources named driver-reference.conf: DSBulk driver overrides.
3. All classpath resources named reference.conf: Java driver settings.

Returns:

an unresolved reference config for DSBulk.

createApplicationConfig

@NonNull
public static Config createApplicationConfig(@Nullable
                                                      Path appConfigPath)

Creates an unresolved application config for DSBulk, optionally pulling application settings from the given alternate location.

The application config is obtained from the following stack:

1. All classpath resources named application[.conf,.json,.properties] or appConfigPath if non null: application settings (DSBulk and driver overrides).
2. dsbulk-reference.conf: DSBulk specific settings and driver overrides.
3. dse-reference.conf: DSE driver specific settings.
4. reference.conf: OSS driver settings.

* @param appConfigPath An alternate location for the application settings, or null to use the default application resources.

Returns:

an unresolved application config for DSBulk.

getPath

public static Path getPath(Config config,
                           String path)

Returns the Path object at the given path.

The returned Path is normalized and absolute.

For convenience, if the path begins with a tilde (`~`), that symbol will be expanded to the current user's home directory, as supplied by `System.getProperty("user.home")`. Note that this expansion will not occur when the tilde is not the first character in the path, nor when the home directory owner is not the current user.

Parameters:

config - The Config to use.

path - path expression.

Returns:

the Path object at the requested path.

Throws:

ConfigException.Missing - if value is absent or null.

ConfigException.WrongType - if value is not convertible to a Path.

getURL

public static URL getURL(Config config,
                         String path)

Returns the URL object at the given path.

The value will be first interpreted directly as a URL; if the parsing fails, the value will be then interpreted as a path on the local filesystem, then converted to a file URL.

If the value is "-" map it to "std:/", to indicate this url represents stdout (when unloading) and stdin (when loading).

The returned URL is normalized and absolute.

Parameters:

config - The Config to use.

path - path expression.

Returns:

the URL object at the requested path.

Throws:

ConfigException.Missing - if value is absent or null.

ConfigException.WrongType - if value is not convertible to a URL.

getThreads

public static int getThreads(Config config,
                             String path)

Returns the number of threads at the given path.

The given path can be an integer, or alternatively, an integer followed by the letter C, in which case, the resulting value is the integer multiplied by the number of available cores on the system.

Parameters:

config - The Config to use.

path - path expression.

Returns:

the number of threads at the requested path.

Throws:

ConfigException.Missing - if value is absent or null.

ConfigException.WrongType - if value is not convertible to a number of threads.

getChar

public static char getChar(Config config,
                           String path)

Returns the character at the given path.

Parameters:

config - The Config to use.

path - path expression.

Returns:

the character at the requested path.

Throws:

ConfigException.Missing - if value is absent or null.

ConfigException.WrongType - if value is not convertible to a single character.

getCharset

public static Charset getCharset(Config config,
                                 String path)

Returns the Charset at the given path.

Parameters:

config - The Config to use.

path - path expression.

Returns:

the Charset at the requested path.

Throws:

ConfigException.Missing - if value is absent or null.

ConfigException.WrongType - if value is not convertible to a Charset.

resolvePath

@NonNull
public static Path resolvePath(@NonNull
                                        String path)
                                 throws InvalidPathException

Resolves the given path.

The returned path is normalized and absolute. If the input denotes a relative path, it is resolved against the current working directory. If it starts with a tilde, the tilde is expanded into the current user's home directory.

Parameters:

path - The path to resolve.

Returns:

The resolved Path, absolute and normalized.

Throws:

InvalidPathException - If the path cannot be resolved.

resolveURL

@NonNull
public static URL resolveURL(@NonNull
                                      String url)
                               throws MalformedURLException,
                                      InvalidPathException

Resolves the given URL.

The returned URL is normalized.

This method first tries to interpret the input as a valid URL, possibly expanding the special "-" (single dash) URL into DSBulk's standard input/output URL.

If that fails, this method then attempts to interpret the input as a path object. See resolvePath(String).

Parameters:

url - The URL to resolve.

Returns:

The resolved URL, normalized.

Throws:

MalformedURLException - If the URL cannot be resolved.

InvalidPathException - If the path cannot be resolved.

resolveUserHome

@NonNull
public static Optional<Path> resolveUserHome(@NonNull
                                                      String path)

Resolves a path starting with "~" against the current user's home directory. Returns empty if the path is not relative to the user home directory.

Resolving against another user's home directory is not supported and throws InvalidPathException.

Parameters:

path - The path to resolve.

Returns:

The resolved path, or empty if it is not relative to the user home directory.

Throws:

InvalidPathException - if the path string cannot be converted to a Path, or if the path references another user's home directory.

resolveThreads

public static int resolveThreads(@NonNull
                                 String threadsStr)

Resolves the given input as a positive integer representing the number of threads to allocate.

This method first tries to parse the input directly as an integer.

If that fails, it then tries to parse the input as an integer followed by the letter 'C'. If that succeeds, the total number of threads returned is n * number of available cores.

Parameters:

threadsStr - The string to parse.

Returns:

The number of threads.

Throws:

PatternSyntaxException - If the input cannot be parsed.

IllegalArgumentException - If the input can be parsed, but the resulting integer is not positive.

getTypeString

@NonNull
public static Optional<String> getTypeString(@NonNull
                                                      Config config,
                                                      @NonNull
                                                      String path)

Returns a string representation of the value type at this path. This is mostly intended for inclusion in generated documentation.

Parameters:

config - the config.

path - path expression.

Returns:

the type string

Throws:

ConfigException.Missing - if value is absent.

getValueType

@NonNull
public static ConfigValueType getValueType(@NonNull
                                                    Config config,
                                                    @NonNull
                                                    String path)

Alternative to ConfigValue.valueType() that honors any type hints found in the configuration, if any.

Parameters:

config - the config.

path - path expression.

Returns:

the value type.

Throws:

ConfigException.Missing - if value is absent.

getTypeHint

@NonNull
public static Optional<String> getTypeHint(@NonNull
                                                    ConfigValue value)

Retrieves the type hint for the given value, if any.

Parameters:

value - the value to inspect.

Returns:

The type hint, if any, or empty otherwise.

getComments

@NonNull
public static String getComments(@NonNull
                                          ConfigValue value)

Returns the comments associated with the given value, excluding type hints.

Parameters:

value - the value to inspect.

Returns:

The comments associated with the given value

isTypeHint

public static boolean isTypeHint(@NonNull
                                 String line)

Checks the given line for the presence of an @type annotation.

Parameters:

line - The line to inspect.

Returns:

Returns true if the given line contains a type annotation, false otherwise.

isLeaf

public static boolean isLeaf(@NonNull
                             ConfigValue value)

Returns true if the given value is a leaf.

Leaf values are values of all types except OBJECT, or values of type OBJECT explicitly annotated with @leaf.

Parameters:

value - The value to inspect.

Returns:

True if the value is a leaf, false otherwise.

isLeaf

public static boolean isLeaf(@NonNull
                             String line)

Checks the given line for the presence of an @leaf annotation.

Parameters:

line - The line to inspect.

Returns:

Returns true if the given line contains a leaf annotation, false otherwise.

getNullSafeValue

@NonNull
public static ConfigValue getNullSafeValue(@NonNull
                                                    Config config,
                                                    @NonNull
                                                    String path)

An alternative to Config.getValue(String) that handles null values gracefully instead of throwing.

Note that the path must still exist; if the path does not exist (i.e., the value is completely absent from the config object), this method still throws ConfigException.Missing.

Parameters:

config - The config object to get the value from.

path - The path at which the value is to be found.

Returns:

The value.

Throws:

ConfigException.Missing - If the path is not present in the config object.

getURLsFromFile

public static List<URL> getURLsFromFile(Path urlfile)
                                 throws IOException

Loads list of URLs from a file given as the urlfile argument using encoding. The given file should be encoded in UTF_8.

Parameters:

urlfile - The path to file passed as the --urlfile argument to dsbulk.

Returns:

The list of urls resolved from urlfile line by line.

Throws:

IOException - If unable to load a file from urlfile path.

isPathPresentAndNotEmpty

public static boolean isPathPresentAndNotEmpty(Config config,
                                               String path)

Checks if the given path is present and its value is a non-empty string.

Parameters:

config - The config.

path - The path expression.

Returns:

true if the given path is present and its value is a non-empty string, false otherwise.

hasReferenceValue

public static boolean hasReferenceValue(Config config,
                                        String path)

Checks whether the given path has a default value or not.

A default value is the value defined in reference.conf or dsbulk-reference.conf.

If the given path doesn't exist at all this method returns false.

Parameters:

config - The config.

path - The path expression.

Returns:

true if the given path has a default value, false otherwise.

hasUserOverride

public static boolean hasUserOverride(Config config,
                                      String path)

Checks whether the given path has a user-defined value or not.

A user-defined value is a value defined in application.conf.

If the given path doesn't exist at all this method returns false.

Parameters:

config - The config.

path - The path expression.

Returns:

true if the given path has a user-defined value, false otherwise.

convertConfigException

@NonNull
public static IllegalArgumentException convertConfigException(@NonNull
                                                                       ConfigException e,
                                                                       @NonNull
                                                                       String basePath)

Creates a IllegalArgumentException from a ConfigException, sanitizing the error message for better user experience.

The origin description, usually placed at the beginning of the error message, is placed rather at the end, enclosed in parentheses.

Parameters:

e - The original exception

basePath - The base path of the configuration; required to create an absolute path from an error message containing relative paths.

Returns:

A IllegalArgumentException with sanitized error message.

readPassword

@NonNull
public static Config readPassword(@NonNull
                                           Config config,
                                           @NonNull
                                           String path,
                                           @NonNull
                                           Console console)

Reads a password from the console, then returns a new Config object containing the password read under the given path.

Parameters:

config - The initial config; cannot be null.

path - The path of the password setting, relative to the config root; cannot be null.

console - The Console; cannot be null.

Returns:

A new Config containing the password read.