Interface ConfigurationReference<N extends ConfigurationNode>

  • Type Parameters:
    N - the type of node to work with
    All Superinterfaces:
    java.lang.AutoCloseable

    public interface ConfigurationReference<N extends ConfigurationNode>
    extends java.lang.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<java.util.Map.Entry<ConfigurationReference.ErrorPhase,​java.lang.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​(java.lang.Iterable<?> path)
      Get the node at the given path, relative to the root node.
      N get​(java.lang.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​(io.leangen.geantyref.TypeToken<T> type, java.lang.Object... path)
      Create a reference to the node at the provided path.
      default <T> ValueReference<T,​N> referenceTo​(io.leangen.geantyref.TypeToken<T> type, NodePath path)
      Create a reference to the node at the provided path.
      <T> ValueReference<T,​N> referenceTo​(io.leangen.geantyref.TypeToken<T> type, NodePath path, @Nullable T defaultValue)
      Create a reference to the node at the provided path.
      default <T> ValueReference<T,​N> referenceTo​(java.lang.Class<T> type, java.lang.Object... path)
      Create a reference to the node at the provided path.
      default <T> ValueReference<T,​N> referenceTo​(java.lang.Class<T> type, NodePath path)
      Create a reference to the node at the provided path.
      <T> ValueReference<T,​N> referenceTo​(java.lang.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​(java.lang.Object[] path, @Nullable java.lang.Object value)
      Update the value of the node at the given path, using the root node as a base.
      default <T> void set​(java.lang.Object[] path, io.leangen.geantyref.TypeToken<T> type, @Nullable T value)
      Set the value of the node at path to the given value.
      default <T> void set​(java.lang.Object[] path, java.lang.Class<T> type, @Nullable T value)
      Set the value of the node at path to the given value.
      default void set​(NodePath path, @Nullable java.lang.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, io.leangen.geantyref.TypeToken<T> type, @Nullable T value)
      Set the value of the node at path to the given value.
      default <T> void set​(NodePath path, java.lang.Class<T> type, @Nullable T value)
      Set the value of the node at path to the given value.
      Publisher<N> updateAsync​(java.util.function.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​(java.util.function.Function<java.nio.file.Path,​ConfigurationLoader<? extends T>> loaderCreator, java.nio.file.Path file, WatchServiceListener listener)
      Create a new configuration reference that will automatically update when triggered by the provided WatchServiceListener.
    • Method Detail

      • 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​(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<NsaveAsync()
        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<NupdateAsync​(java.util.function.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 Nloader()
        Get the loader this reference uses to load and save its node.
        Returns:
        the loader
        Since:
        4.0.0
      • get

        N get​(java.lang.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​(java.lang.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​(java.lang.Object[] path,
                         @Nullable java.lang.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 - when unable to write the provided value
        Since:
        4.0.0
      • set

        default <T> void set​(java.lang.Object[] path,
                             java.lang.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:
        java.lang.IllegalArgumentException - if a raw type is provided
        SerializationException - if thrown by the serialization mechanism
        Since:
        4.0.0
      • set

        default <T> void set​(java.lang.Object[] path,
                             io.leangen.geantyref.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 java.lang.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,
                             java.lang.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,
                             io.leangen.geantyref.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,​NreferenceTo​(io.leangen.geantyref.TypeToken<T> type,
                                                          java.lang.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,​NreferenceTo​(java.lang.Class<T> type,
                                                          java.lang.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,​NreferenceTo​(io.leangen.geantyref.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,​NreferenceTo​(java.lang.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,​NreferenceTo​(io.leangen.geantyref.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,​NreferenceTo​(java.lang.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<Nupdates()
        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
      • close

        void close()
        Specified by:
        close in interface java.lang.AutoCloseable