001/*
002 * Configurate
003 * Copyright (C) zml and Configurate contributors
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.spongepowered.configurate.reference;
018
019import org.checkerframework.checker.nullness.qual.Nullable;
020import org.spongepowered.configurate.ConfigurationNode;
021import org.spongepowered.configurate.reactive.Publisher;
022
023import java.util.function.Function;
024
025/**
026 * A pointer to a node within a configuration tree.
027 *
028 * <p>This value will update automatically with changes to the underlying
029 * configuration file. Subscribers will be provided the current value upon
030 * subscription, followed by any changes.
031 *
032 * @param <T> the type of value to return
033 * @param <N> the type of node
034 * @since 4.0.0
035 */
036public interface ValueReference<T, N extends ConfigurationNode> extends Publisher<T> {
037
038    /**
039     * Get the current value at this node.
040     *
041     * <p>Any deserialization failures will be submitted to the owning
042     * {@link ConfigurationReference}'s error callback
043     *
044     * @return the deserialized value, or null if deserialization fails.
045     * @since 4.0.0
046     */
047    @Nullable T get();
048
049    /**
050     * Set the new value of this node. The configuration won't be saved.
051     *
052     * <p>Any serialization errors will be provided to the error callback of
053     * the owning {@link ConfigurationReference}
054     *
055     * @param value the value
056     * @return true if successful, false if serialization fails
057     * @since 4.0.0
058     */
059    boolean set(@Nullable T value);
060
061    /**
062     * Set the new value of this node and save the underlying configuration.
063     *
064     * <p>Any serialization errors will be provided to the error callback of the
065     * owning {@link ConfigurationReference}
066     *
067     * @param value the value
068     * @return true if successful, false if serialization fails
069     * @since 4.0.0
070     */
071    boolean setAndSave(@Nullable T value); // @cs-: NoGetSetPrefix (not a property accessor)
072
073    /**
074     * Set the new value of this node and save the underlying configuration
075     * asynchronously on the executor of the owning {@link ConfigurationReference}.
076     *
077     * <p>Any serialization errors will be submitted to subscribers of the
078     * returned {@link Publisher}
079     *
080     * @param value the value
081     * @return true if successful, false if serialization fails
082     * @since 4.0.0
083     */
084    Publisher<Boolean> setAndSaveAsync(@Nullable T value); // @cs-: NoGetSetPrefix (not a property accessor)
085
086    /**
087     * Update this value and the underlying node, without saving.
088     *
089     * <p>Any serialization errors will be provided to the error callback of
090     * the owning {@link ConfigurationReference}
091     *
092     * @param action to transform this node's value
093     * @return whether this update was successful
094     * @since 4.0.0
095     */
096    boolean update(Function<@Nullable T, ? extends T> action);
097
098    /**
099     * Update, performing the action and save on the executor of the owning
100     * {@link ConfigurationReference}. Any errors that occur while saving will
101     * be passed along to any subscribers.
102     *
103     * <p>The updated value will only be exposed if the changes are successful.
104     *
105     * @param action to transform this node's value
106     * @return whether this update was successful
107     * @since 4.0.0
108     */
109    Publisher<Boolean> updateAsync(Function<@Nullable T, ? extends T> action);
110
111    /**
112     * Get the node this value reference points to.
113     *
114     * @return the node
115     * @since 4.0.0
116     */
117    N node();
118
119}