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

  • Method Details

    • 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