Package org.spongepowered.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.

Since:

4.0.0

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()
Publisher<Map.Entry<ConfigurationReference.ErrorPhase,Throwable>>	errors()	A stream that will receive errors that occur while loading or saving to this reference.
static <N extends ScopedConfigurationNode<N>> ConfigurationReference<N>	fixed(ConfigurationLoader<? extends N> loader)	Create a new configuration reference that will only update when loaded.
N	get(Iterable<?> path)	Get the node at the given path, relative to the root node.
N	get(Object... path)	Get the node at the given path, relative to the root node.
void	load()	Reload a configuration using the provided loader.
ConfigurationLoader<? extends N>	loader()	Get the loader this reference uses to load and save its node.
N	node()	Get the base node this reference refers to.
default <T> ValueReference<T,N>	referenceTo(TypeToken<T> type, Object... path)	Create a reference to the node at the provided path.
default <T> ValueReference<T,N>	referenceTo(TypeToken<T> type, NodePath path)	Create a reference to the node at the provided path.
<T> ValueReference<T,N>	referenceTo(TypeToken<T> type, NodePath path, @Nullable T defaultValue)	Create a reference to the node at the provided path.
default <T> ValueReference<T,N>	referenceTo(Class<T> type, Object... path)	Create a reference to the node at the provided path.
default <T> ValueReference<T,N>	referenceTo(Class<T> type, NodePath path)	Create a reference to the node at the provided path.
<T> ValueReference<T,N>	referenceTo(Class<T> type, NodePath 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(ConfigurationNode 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.
default <T> void	set(Object[] path, Class<T> type, @Nullable T value)	Set the value of the node at path to the given value.
default void	set(NodePath 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(NodePath path, TypeToken<T> type, @Nullable T value)	Set the value of the node at path to the given value.
default <T> void	set(NodePath path, Class<T> type, @Nullable T value)	Set the value of the node at path to the given value.
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.
static <T extends ScopedConfigurationNode<T>> ConfigurationReference<T>	watching(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.

Method Detail

fixed

static <N extends ScopedConfigurationNode<N>> ConfigurationReference<N> fixed(ConfigurationLoader<? extends N> loader)
                                                                       throws ConfigurateException

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:

ConfigurateException - if the configuration contained fails to load

Since:

4.0.0

watching

static <T extends ScopedConfigurationNode<T>> ConfigurationReference<T> watching(Function<Path,ConfigurationLoader<? extends T>> loaderCreator,
                                                                                 Path file,
                                                                                 WatchServiceListener listener)
                                                                          throws ConfigurateException

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:

ConfigurateException - if the underlying loader fails to load a configuration

Since:

4.0.0

See Also:

WatchServiceListener.listenToConfiguration(Function, Path)

load

void load()
   throws ConfigurateException

Reload a configuration using the provided loader.

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

Throws:

ConfigurateException - when an error occurs

Since:

4.0.0

save

void save()
   throws ConfigurateException

Save this configuration using the provided loader.

Throws:

ConfigurateException - when an error occurs in the underlying IO

Since:

4.0.0

save

void save(ConfigurationNode newNode)
   throws ConfigurateException

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:

ConfigurateException - when an error occurs within the loader

Since:

4.0.0

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

Since:

4.0.0

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

Since:

4.0.0

node

N node()

Get the base node this reference refers to.

Returns:

the node

Since:

4.0.0

loader

ConfigurationLoader<? extends N> loader()

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

Returns:

the loader

Since:

4.0.0

get

N get(Object... path)

Get the node at the given path, relative to the root node.

Parameters:

path - the path, a series of path elements

Returns:

a child node

Since:

4.0.0

See Also:

ConfigurationNode.node(Object...)

get

N get(Iterable<?> path)

Get the node at the given path, relative to the root node.

Parameters:

path - the path, a series of path elements

Returns:

a child node

Since:

4.0.0

See Also:

ConfigurationNode.node(Iterable)

set

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

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

Throws:

SerializationException

Since:

4.0.0

set

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

Set the value of the node at path to the given value.

This uses 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:

IllegalArgumentException - if a raw type is provided

SerializationException - if thrown by the serialization mechanism

Since:

4.0.0

set

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

Set the value of the node at path to the given value.

This uses 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:

SerializationException - if thrown by the serialization mechanism

Since:

4.0.0

set

default void set(NodePath path,
                 @Nullable Object value)
          throws SerializationException

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

Throws:

SerializationException

Since:

4.0.0

set

default <T> void set(NodePath path,
                     Class<T> type,
                     @Nullable T value)
              throws SerializationException

Set the value of the node at path to the given value.

This uses 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:

SerializationException - if thrown by the serialization mechanism

Since:

4.0.0

set

default <T> void set(NodePath path,
                     TypeToken<T> type,
                     @Nullable T value)
              throws SerializationException

Set the value of the node at path to the given value.

This uses 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:

SerializationException - if thrown by the serialization mechanism

Since:

4.0.0

referenceTo

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

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 containing the value

Returns:

a deserializing reference to the node at the given path

Throws:

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

Since:

4.0.0

referenceTo

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

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 containing the value

Returns:

a deserializing reference to the node at the given path

Throws:

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

Since:

4.0.0

referenceTo

default <T> ValueReference<T,N> referenceTo(TypeToken<T> type,
                                                  NodePath path)
                                           throws SerializationException

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 containing the value

Returns:

a deserializing reference to the node at the given path

Throws:

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

Since:

4.0.0

referenceTo

default <T> ValueReference<T,N> referenceTo(Class<T> type,
                                                  NodePath path)
                                           throws SerializationException

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 containing the value

Returns:

a deserializing reference to the node at the given path

Throws:

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

Since:

4.0.0

referenceTo

<T> ValueReference<T,N> referenceTo(TypeToken<T> type,
                                          NodePath path,
                                          @Nullable T defaultValue)
                                   throws SerializationException

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 containing the value

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:

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

Since:

4.0.0

referenceTo

<T> ValueReference<T,N> referenceTo(Class<T> type,
                                          NodePath path,
                                          @Nullable T defaultValue)
                                   throws SerializationException

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 - value type

Parameters:

type - value's type

path - path from the root node to the node containing the value

defaultValue - 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:

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

Since:

4.0.0

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

Since:

4.0.0

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

Since:

4.0.0

close

void close()

Specified by:

close in interface AutoCloseable