com.electronwill.nightconfig.core.file

Interface FileConfig

All Superinterfaces:

java.lang.AutoCloseable, ConcurrentConfig, Config, UnmodifiableConfig

All Known Subinterfaces:

CommentedFileConfig

All Known Implementing Classes:

ConvertedCommentedFileConfig, ConvertedFileConfig

public interface FileConfig
extends ConcurrentConfig, java.lang.AutoCloseable

A configuration that is tied to a particular file.

IO operations

When created, a FileConfig is empty. It is linked to a file, but that file has not been parsed yet. To parse the file and fill the FileConfig, call the load() method. You probably want to call load() before using the configuration.

Depending on the options that you have chosen when building the FileConfig (see FileConfigBuilder), it may be saved automatically after each writing operation. To manually save the content of the configuration to its file, call the save() method.

Optimizing writes

If your FileConfig has been configured to automatically save its content, it can suffer from performance issues when applying many modifications. A solution is to use bulkUpdate(Consumer) in order to apply multiple modifications as one writing operation, which will trigger only one save operation (at the end of bulkUpdate).

Example:

 
 FileConfig config = FileConfig.builder(file).autosave().build();
 config.bulkUpdate(c -> {
     c.set("key1", "value1");
     c.set("key2", "value2");
     // ... other operations
     // NOTE: you must NOT use the config variable here, only c
 });
 
 

Even if your FileConfig is not auto-saved, bulk methods like bulkUpdate(Consumer) are useful to ensure the consistency of the configuration in a multi-thread environment. See the next section for more details.

Thread safety

Since NightConfig 3.7.0, every FileConfig is thread-safe (see PR #152). In other words, you can read and modify the same FileConfig from different threads at the same time, without any external synchronization (no need to guard the configuration with a lock).

However, some rules need to be followed in order to ensure the consistency of the configuration's content. In particular, when you write multiple values to a FileConfig, or read multiple values from a FileConfig, and expect all the values to be consistent (i.e. you are performing multiple operations as if they were all applied together, with no other thread modifying the configuration in between), you should use bulkUpdate(Consumer) and ConcurrentConfig.bulkRead(Consumer).

For more details, please see the documentation of the concurrent package, which is internally used by FileConfigs: com.electronwill.nightconfig.core.concurrent.

Nested Class Summary

Nested classes/interfaces inherited from interface com.electronwill.nightconfig.core.Config

Config.Entry

Method Summary

Modifier and Type	Method and Description
static FileConfigBuilder	builder(java.io.File file) Returns a FileConfigBuilder to create a FileConfig with many options.
static FileConfigBuilder	builder(java.io.File file, ConfigFormat<?> format) Returns a FileConfigBuilder to create a FileConfig with many options.
static FileConfigBuilder	builder(java.nio.file.Path file) Returns a FileConfigBuilder to create a FileConfig with many options.
static FileConfigBuilder	builder(java.nio.file.Path file, ConfigFormat<?> format) Returns a FileConfigBuilder to create a FileConfig with many options.
static FileConfigBuilder	builder(java.lang.String filePath) Returns a FileConfigBuilder to create a FileConfig with many options.
static FileConfigBuilder	builder(java.lang.String filePath, ConfigFormat<?> format) Returns a FileConfigBuilder to create a FileConfig with many options.
default void	bulkUpdate(java.util.function.Consumer<? super Config> action) Performs multiple read/write operations, and do not save the configuration until the end (unless save() is called by action).
<R> R	bulkUpdate(java.util.function.Function<? super Config,R> action) Performs multiple read/write operations, and do not save the configuration until the end (unless save() is called by action).
default FileConfig	checked() Returns a checked view of the config.
void	close() Closes this FileConfig, releases its associated resources (if any), and ensure that the ongoing saving operations complete.
java.io.File	getFile()
java.nio.file.Path	getNioPath()
void	load() (Re)loads this config from the file.
static FileConfig	of(java.io.File file) Creates a new FileConfig based on the specified file.
static FileConfig	of(java.io.File file, ConfigFormat<? extends Config> format) Creates a new FileConfig based on the specified file and format.
static FileConfig	of(java.nio.file.Path file) Creates a new FileConfig based on the specified file.
static FileConfig	of(java.nio.file.Path file, ConfigFormat<? extends Config> format) Creates a new FileConfig based on the specified file and format.
static FileConfig	of(java.lang.String filePath) Creates a new FileConfig based on the specified file.
static FileConfig	of(java.lang.String filePath, ConfigFormat<?> format) Creates a new FileConfig based on the specified file and format.
static FileConfig	ofConcurrent(java.io.File file) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
static FileConfig	ofConcurrent(java.io.File file, ConfigFormat<?> format) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
static FileConfig	ofConcurrent(java.nio.file.Path file) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
static FileConfig	ofConcurrent(java.nio.file.Path file, ConfigFormat<?> format) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
static FileConfig	ofConcurrent(java.lang.String filePath) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
static FileConfig	ofConcurrent(java.lang.String filePath, ConfigFormat<?> format) Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig
void	save() Saves this config as soon as possible.

Methods inherited from interface com.electronwill.nightconfig.core.concurrent.ConcurrentConfig

bulkRead, bulkRead, createSubConfig

Methods inherited from interface com.electronwill.nightconfig.core.Config

add, add, addAll, clear, concurrentCopy, concurrentCopy, copy, copy, copy, copy, entrySet, getDefaultMapCreator, getDefaultMapCreator, inMemory, inMemoryConcurrent, inMemoryUniversal, inMemoryUniversalConcurrent, isInsertionOrderPreserved, of, of, ofConcurrent, putAll, remove, remove, removeAll, set, set, setInsertionOrderPreserved, unmodifiable, update, update, valueMap, wrap

Methods inherited from interface com.electronwill.nightconfig.core.UnmodifiableConfig

apply, apply, configFormat, contains, contains, get, get, getByte, getByte, getByteOrElse, getByteOrElse, getChar, getChar, getCharOrElse, getCharOrElse, getEnum, getEnum, getEnum, getEnum, getEnumOrElse, getEnumOrElse, getEnumOrElse, getEnumOrElse, getEnumOrElse, getEnumOrElse, getEnumOrElse, getEnumOrElse, getInt, getInt, getIntOrElse, getIntOrElse, getIntOrElse, getIntOrElse, getLong, getLong, getLongOrElse, getLongOrElse, getLongOrElse, getLongOrElse, getOptional, getOptional, getOptionalEnum, getOptionalEnum, getOptionalEnum, getOptionalEnum, getOptionalInt, getOptionalInt, getOptionalLong, getOptionalLong, getOrElse, getOrElse, getOrElse, getOrElse, getRaw, getRaw, getShort, getShort, getShortOrElse, getShortOrElse, isEmpty, isNull, isNull, size

Method Detail

getFile

java.io.File getFile()

Returns:

the config's file, as a classic File object

getNioPath

java.nio.file.Path getNioPath()

Returns:

the config's file, as a NIO Path object

save

void save()

Saves this config as soon as possible. This method may return quickly and perform the IO operations in background, or it may block until the operations are done.

load

void load()

(Re)loads this config from the file. This method blocks until the read operation completes.

close

void close()

Closes this FileConfig, releases its associated resources (if any), and ensure that the ongoing saving operations complete.

A closed FileConfig can still be used via the Config's methods, but save() and load() will throw an IllegalStateException. Closing an aleady closed FileConfig has no effect.

Specified by:

close in interface java.lang.AutoCloseable

checked

default FileConfig checked()

Description copied from interface: Config

Returns a checked view of the config. It checks that all the values put into the config are supported by the config's format (as per the ConfigFormat.supportsType(Class) method. Trying to insert an unsupported value throws an IllegalArgumentException.

The values that are in the config when this method is called are also checked.

Specified by:

checked in interface Config

Returns:

a checked view of the config.

bulkUpdate

<R> R bulkUpdate(java.util.function.Function<? super Config,R> action)

Performs multiple read/write operations, and do not save the configuration until the end (unless save() is called by action). This is a way of manually grouping config modifications together.

If this configuration automatically saves, it will not do so before the end of the bulkUpdate.

This has the same guarantees of consistency as ConcurrentConfig.bulkUpdate(Function).

Specified by:

bulkUpdate in interface ConcurrentConfig

Type Parameters:

R - the type of the function's result

Parameters:

action - a function to execute on the configuration view

Returns:

the result of the function

bulkUpdate

default void bulkUpdate(java.util.function.Consumer<? super Config> action)

Performs multiple read/write operations, and do not save the configuration until the end (unless save() is called by action). This is a way of manually grouping config modifications together.

If this configuration automatically saves, it will not do so before the end of the bulkUpdate.

This has the same guarantees of consistency as ConcurrentConfig.bulkUpdate(Consumer).

Specified by:

bulkUpdate in interface ConcurrentConfig

Parameters:

action - a function to execute on the configuration view

of

static FileConfig of(java.io.File file)

Creates a new FileConfig based on the specified file. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

builder(File)

of

static FileConfig of(java.io.File file,
                     ConfigFormat<? extends Config> format)

Creates a new FileConfig based on the specified file and format.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new FileConfig associated to the specified file

See Also:

builder(File, ConfigFormat)

of

static FileConfig of(java.nio.file.Path file)

Creates a new FileConfig based on the specified file. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

builder(Path)

of

static FileConfig of(java.nio.file.Path file,
                     ConfigFormat<? extends Config> format)

Creates a new FileConfig based on the specified file and format.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new FileConfig associated to the specified file

See Also:

builder(Path, ConfigFormat)

of

static FileConfig of(java.lang.String filePath)

Creates a new FileConfig based on the specified file. The format is detected automatically.

Parameters:

filePath - the file's path

Returns:

a new FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

builder(String)

of

static FileConfig of(java.lang.String filePath,
                     ConfigFormat<?> format)

Creates a new FileConfig based on the specified file and format.

Parameters:

filePath - the file's path

format - the config's format

Returns:

a new FileConfig associated to the specified file

See Also:

builder(String, ConfigFormat)

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.io.File file)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new thread-safe FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.io.File file,
                                           ConfigFormat<?> format)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file and format.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new thread-safe FileConfig associated to the specified file

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.nio.file.Path file)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new thread-safe FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.nio.file.Path file,
                                           ConfigFormat<?> format)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file and format.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new thread-safe FileConfig associated to the specified file

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.lang.String filePath)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file. The format is detected automatically.

Parameters:

filePath - the file's path

Returns:

a new thread-safe FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

ofConcurrent

@Deprecated
static FileConfig ofConcurrent(java.lang.String filePath,
                                           ConfigFormat<?> format)

Deprecated. All FileConfig are now thread-safe by default, backed by a ConcurrentConfig

Creates a new thread-safe FileConfig based on the specified file and format.

Parameters:

filePath - the file's path

format - the config's format

Returns:

a new thread-safe FileConfig associated to the specified file

builder

static FileConfigBuilder builder(java.io.File file)

Returns a FileConfigBuilder to create a FileConfig with many options. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

FileConfigBuilder

builder

static FileConfigBuilder builder(java.io.File file,
                                 ConfigFormat<?> format)

Returns a FileConfigBuilder to create a FileConfig with many options.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

See Also:

FileConfigBuilder

builder

static FileConfigBuilder builder(java.nio.file.Path file)

Returns a FileConfigBuilder to create a FileConfig with many options. The format is detected automatically.

Parameters:

file - the file to use to save and load the config

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

FileConfigBuilder

builder

static FileConfigBuilder builder(java.nio.file.Path file,
                                 ConfigFormat<?> format)

Returns a FileConfigBuilder to create a FileConfig with many options.

Parameters:

file - the file to use to save and load the config

format - the config's format

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

See Also:

FileConfigBuilder

builder

static FileConfigBuilder builder(java.lang.String filePath)

Returns a FileConfigBuilder to create a FileConfig with many options. The format is detected automatically.

Parameters:

filePath - the file's path

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

Throws:

NoFormatFoundException - if the format detection fails

See Also:

FileConfigBuilder

builder

static FileConfigBuilder builder(java.lang.String filePath,
                                 ConfigFormat<?> format)

Returns a FileConfigBuilder to create a FileConfig with many options.

Parameters:

filePath - the file's path

format - the config's format

Returns:

a new FileConfigBuilder that will build a FileConfig associated to the specified file

See Also:

FileConfigBuilder