using Common.Logging;

namespace Common.AppSettings;

public interface IAppSettingsProvider
{
    /// <summary>
    /// Any internal event inside of the App Settings Provider. 
    /// </summary>
    event EventHandler<LogEntry>? LogWorthyEvent;

    /// <summary>
    /// Retrieves the app settings from the persistant location and loads them into memory.
    /// Loading settings will override the currently stored settings in the memory.
    /// If loading happens and there were already settings in the memory, a <see cref="LogWorthyEvent"/> is generated.
    /// </summary>
    void Load();

    /// <summary>
    /// Saves the app settings to the persistant location.
    /// If the saving does not work, logs the exception as a <see cref="LogWorthyEvent"/> but does not throw an exception.
    /// Rationale: A User is happier if the app is useable and does not remember settings than if the app always throws an exception on startup.
    /// </summary>
    void Save();

    /// <summary>
    /// Creates a new setting or overwrites the value of an existing setting in the memory (not persistent location). Settings are identified by key.
    /// Informs about issues using the <see cref="LogWorthyEvent"/>.
    /// </summary>
    /// <param name="key">key of the setting, must not be empty or null</param>
    /// <param name="value">value of the setting, must not be empty or null</param>
    /// <returns>true if the setting is successfully written or overwritten</returns>
    bool WriteSetting(string key, string value);

    /// <summary>
    /// Tries to read a setting from the memory (not persistent location). Settings are identified by key.
    /// Informs about issues using the <see cref="LogWorthyEvent"/>.
    /// If no setting with the given <paramref name="key"/> is found, the <paramref name="value"/> is set to <see cref="String.Empty"/>.
    /// </summary>
    /// <param name="key">key of the setting, must not be empty or null</param>
    /// <param name="value">the found value or an empty string if no setting is found</param>
    /// <returns>true when the setting exists and could be read successfully</returns>
    bool TryReadSetting(string key, out string value);

    /// <summary>
    /// Tries to read a setting from the memory (not persistent location). Settings are identified by key.
    /// Informs about issues using the <see cref="LogWorthyEvent"/>.
    /// If no setting with the given <paramref name="key"/> is found, the setting is created with the given <paramref name="defaultValue"/>. <paramref name="value"/> is also set to <paramref name="defaultValue"/>.
    /// </summary>
    /// <param name="key">key of the setting, must not be empty or null</param>
    /// <param name="value">the found value or an empty string if no setting is found</param>
    /// <param name="defaultValue">the default value to initialize the setting with if it does not exist yet. must not be empty or null</param>
    /// <returns>true when the setting could be read or was created successfully</returns>
    bool TryReadSettingOrAddDefault(string key, out string value, string defaultValue);
}