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
All Methods Static Methods Instance Methods Abstract Methods Default Methods 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 atpath
to the given value.default <T> void
set(Object[] path, Class<T> type, @Nullable T value)
Set the value of the node atpath
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 atpath
to the given value.default <T> void
set(NodePath path, Class<T> type, @Nullable T value)
Set the value of the node atpath
to the given value.Publisher<N>
updateAsync(Function<N,? extends N> updater)
Update this configuration using the provided function, returning aPublisher
which will complete with the result of the operation.Publisher<N>
updates()
Access thePublisher
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 providedWatchServiceListener
.
-
-
-
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 providedWatchServiceListener
.- Type Parameters:
T
- the node type- Parameters:
loaderCreator
- a function that can create aConfigurationLoader
file
- the file to load this configuration fromlistener
- 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 aPublisher
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
-
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 atvalue
- 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 atpath
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 attype
- the type of data to serializevalue
- the value to set- Throws:
IllegalArgumentException
- if a raw type is providedSerializationException
- 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 atpath
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 attype
- the type of data to serializevalue
- 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 atvalue
- 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 atpath
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 attype
- the type of data to serializevalue
- 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 atpath
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 attype
- the type of data to serializevalue
- 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 typepath
- 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 providedClass
.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 typepath
- 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 providedTypeToken
.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 typepath
- 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 providedClass
.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 typepath
- 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 providedTypeToken
.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 valuedefaultValue
- 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 providedClass
.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 typepath
- path from the root node to the node containing the valuedefaultValue
- 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 thePublisher
that will broadcast update events, providing the newly created node. The returned publisher will be transaction-aware, i.e. anyTransactionalSubscriber
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 interfaceAutoCloseable
-
-