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}