package com.atlassian.stash.internal.plugin;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public interface PluginSettingDao {

    /**
     * Re-associate a {@link PluginSetting} object (returned by a previous call to {@link #put} in a different session)
     * with the current session.  This is necessary if a plugin setting is modified in an inner transaction to ensure
     * that stale values are not cached in the session associated with an outer transaction.
     *
     * @param setting setting object to re-associate with the current session
     */
    void attach(@Nonnull PluginSetting setting);

    /**
     * Remove this key-value pair from the session cache.
     *
     * @param namespace name for the key-value pair (ex: the plugin id)
     * @param key key
     */
    void evict(@Nonnull String namespace, @Nonnull String key);

    /**
     * Add a key-value pair.
     *
     * <p>If the key already exists, its <em>value</em> will be updated.</p>
     *
     * @param namespace name for the key-value pair (ex: the plugin id)
     * @param key key
     * @param val value
     * @return the {@link PluginSetting} object that was just inserted or updated
     */
    @Nonnull
    PluginSetting put(@Nonnull String namespace, @Nonnull String key, @Nonnull String val);

    /**
     * Get the value of a key-value pair.
     *
     * @param namespace name for the key-value pair (ex: the plugin id)
     * @param key key
     * @return value of the key-value pair or {@code null} if it does not exist
     */
    @Nullable
    String get(@Nonnull String namespace, @Nonnull String key);

    /**
     * Remove a key-value pair.
     *
     * <p>If the key-value pair does not exist, this is equivalent to a NOOP.</p>
     *
     * @param namespace name for the key-value pair (ex: plugin id)
     * @param key key
     */
    void remove(@Nonnull String namespace, @Nonnull String key);
}
