Package ninja.leaping.configurate.reference

Interface ConfigurationReference<N extends ConfigurationNode>

Type Parameters:

N - The type of node to work with

All Superinterfaces:

AutoCloseable

public interface ConfigurationReference<N extends ConfigurationNode>
extends AutoCloseable

An updating reference to a base configuration node

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ConfigurationReference.ErrorPhase	Representing the phase where an error occurred

Method Summary

Modifier and Type	Method	Description
void	close()
static <N extends ConfigurationNode> ConfigurationReference<N>	createFixed(ConfigurationLoader<? extends N> loader)	Create a new configuration reference that will only update when loaded
static <T extends ConfigurationNode> ConfigurationReference<T>	createWatching(Function<Path,ConfigurationLoader<? extends T>> loaderCreator, Path file, WatchServiceListener listener)	Create a new configuration reference that will automatically update when triggered by the provided WatchServiceListener
Publisher<Map.Entry<ConfigurationReference.ErrorPhase,Throwable>>	errors()	A stream that will receive errors that occur while loading or saving to this reference
N	get(Object... path)	Get the node at the given path, using the root node
ConfigurationLoader<? extends N>	getLoader()	Get the loader this reference uses to load and save its node
N	getNode()	Get the base node this reference refers to.
void	load()	Reload a configuration using the provided loader.
default <T> ValueReference<T>	referenceTo(TypeToken<T> type, Object... path)	Create a reference to the node at the provided path.
<T> ValueReference<T>	referenceTo(TypeToken<T> type, Object[] path, @Nullable T defaultValue)	Create a reference to the node at the provided path.
default <T> ValueReference<T>	referenceTo(Class<T> type, Object... path)	Create a reference to the node at the provided path.
<T> ValueReference<T>	referenceTo(Class<T> type, Object[] path, @Nullable T defaultValue)	Create a reference to the node at the provided path.
void	save()	Save this configuration using the provided loader.
void	save(N newNode)	Update the configuration node pointed to by this reference, and save it using the reference's loader
Publisher<N>	saveAsync()	Save this configuration using the provided loader.
default void	set(Object[] path, @Nullable Object value)	Update the value of the node at the given path, using the root node as a base.
default <T> void	set(Object[] path, TypeToken<T> type, @Nullable T value)	Set the value of the node at path to the given value, using the appropriate TypeSerializer to serialize the data if it's not directly supported by the provided configuration.
Publisher<N>	updateAsync(Function<N,? extends N> updater)	Update this configuration using the provided function, returning a Publisher which will complete with the result of the operation.
Publisher<N>	updates()	Access the Publisher that will broadcast update events, providing the newly created node.

Method Detail

createFixed

static <N extends ConfigurationNode> ConfigurationReference<N> createFixed(ConfigurationLoader<? extends N> loader)
                                                                    throws IOException

Create a new configuration reference that will only update when loaded

Type Parameters:

N - The type of node

Parameters:

loader - The loader to load and save from

Returns:

The newly created reference, with an initial load performed

Throws:

IOException - If the configuration contained fails to load

createWatching

static <T extends ConfigurationNode> ConfigurationReference<T> createWatching(Function<Path,ConfigurationLoader<? extends T>> loaderCreator,
                                                                              Path file,
                                                                              WatchServiceListener listener)
                                                                       throws IOException

Create a new configuration reference that will automatically update when triggered by the provided WatchServiceListener

Type Parameters:

T - The node type

Parameters:

loaderCreator - A function that can create a ConfigurationLoader

file - The file to load this configuration from

listener - The watch service listener that will receive events

Returns:

The created reference

Throws:

IOException - If the underlying loader fails to load a configuration

See Also:

WatchServiceListener.listenToConfiguration(Function, Path)

load

void load()
   throws IOException

Reload a configuration using the provided loader.

If the load fails, this reference will continue pointing to old configuration values

Throws:

IOException - When an error occurs

save

void save()
   throws IOException

Save this configuration using the provided loader.

Throws:

IOException - When an error occurs in the underlying ID

save

void save(N newNode)
   throws IOException

Update the configuration node pointed to by this reference, and save it using the reference's loader

Even if the loader fails to save this new node, the node pointed to by this reference will be updated.

Parameters:

newNode - The new node to save

Throws:

IOException - When an error occurs within the loader

saveAsync

Publisher<N> saveAsync()

Save this configuration using the provided loader. Any errors will be submitted to subscribers of the returned publisher.

Returns:

publisher providing an event when the save is complete

updateAsync

Publisher<N> updateAsync(Function<N,? extends N> updater)

Update this configuration using the provided function, returning a Publisher which will complete with the result of the operation. The update function will be called asynchronously, and will be saved to this reference's loader when complete.

Parameters:

updater - update function

Returns:

publisher providing an event when the update is complete

getNode

N getNode()

Get the base node this reference refers to.

Returns:

The node

getLoader

ConfigurationLoader<? extends N> getLoader()

Get the loader this reference uses to load and save its node

Returns:

The loader

get

N get(Object... path)

Get the node at the given path, using the root node

Parameters:

path - The path, a series of path elements

Returns:

A child node

See Also:

ConfigurationNode.getNode(Object...)

set

default void set(Object[] path,
                 @Nullable Object value)

Update the value of the node at the given path, using the root node as a base.

Parameters:

path - The path to get the child at

value - The value to set the child node to

set

default <T> void set(Object[] path,
                     TypeToken<T> type,
                     @Nullable T value)
              throws ObjectMappingException

Set the value of the node at path to the given value, using the appropriate TypeSerializer to serialize the data if it's not directly supported by the provided configuration.

Type Parameters:

T - The type parameter for the value

Parameters:

path - The path to set the value at

type - The type of data to serialize

value - The value to set

Throws:

ObjectMappingException - If thrown by the serialization mechanism

referenceTo

default <T> ValueReference<T> referenceTo(TypeToken<T> type,
                                          Object... path)
                                   throws ObjectMappingException

Create a reference to the node at the provided path. The value will be deserialized according to the provided TypeToken.

The returned reference will update with reloads of and changes to the value of the provided configuration. Any serialization errors encountered will be submitted to the errors() stream

Type Parameters:

T - The value type

Parameters:

type - The value's type

path - The path from the root node to the node a value will be gotten from

Returns:

A deserializing reference to the node at the given path

Throws:

ObjectMappingException - if a type serializer could not be found for the provided type

referenceTo

default <T> ValueReference<T> referenceTo(Class<T> type,
                                          Object... path)
                                   throws ObjectMappingException

Create a reference to the node at the provided path. The value will be deserialized according to type of the provided Class.

The returned reference will update with reloads of and changes to the value of the provided configuration. Any serialization errors encountered will be submitted to the errors() stream

Type Parameters:

T - The value type

Parameters:

type - The value's type

path - The path from the root node to the node a value will be gotten from

Returns:

A deserializing reference to the node at the given path

Throws:

ObjectMappingException - if a type serializer could not be found for the provided type

referenceTo

<T> ValueReference<T> referenceTo(TypeToken<T> type,
                                  Object[] path,
                                  @Nullable T defaultValue)
                           throws ObjectMappingException

Create a reference to the node at the provided path. The value will be deserialized according to the provided TypeToken.

The returned reference will update with reloads of and changes to the value of the provided configuration. Any serialization errors encountered will be submitted to the errors() stream

Type Parameters:

T - The value type

Parameters:

type - The value's type.

path - The path from the root node to the node a value will be gotten from.

defaultValue - The value to use when there is no data present in the targeted node.

Returns:

A deserializing reference to the node at the given path

Throws:

ObjectMappingException - if a type serializer could not be found for the provided type

referenceTo

<T> ValueReference<T> referenceTo(Class<T> type,
                                  Object[] path,
                                  @Nullable T defaultValue)
                           throws ObjectMappingException

Create a reference to the node at the provided path. The value will be deserialized according to type of the provided Class.

The returned reference will update with reloads of and changes to the value of the provided configuration. Any serialization errors encountered will be submitted to the errors() stream

Type Parameters:

T - The value type

Parameters:

type - The value's type

path - The path from the root node to the node a value will be gotten from

defaultValue - The value to use when there is no data present in the targeted node.

Returns:

A deserializing reference to the node at the given path

Throws:

ObjectMappingException - if a type serializer could not be found for the provided type

updates

Publisher<N> updates()

Access the Publisher that will broadcast update events, providing the newly created node. The returned publisher will be transaction-aware, i.e. any TransactionalSubscriber attached will progress through their phases appropriately

Returns:

The publisher

errors

Publisher<Map.Entry<ConfigurationReference.ErrorPhase,Throwable>> errors()

A stream that will receive errors that occur while loading or saving to this reference

Returns:

The publisher

close

void close()

Specified by:

close in interface AutoCloseable