package com.mumfrey.webprefs.interfaces;

import java.util.Set;

import com.mumfrey.webprefs.exceptions.InvalidValueException;

/**
 * Web-based preferences, objects implementing this interface represent a remote
 * asychronous Key/Value store which fetches and commits values on a best-effort
 * basis.
 *
 * <p>Values in this store are not guaranteed to be correct, nor are values
 * written to the store guaranteed to be successfully written to the store.
 *
 * <p>In general, consumers should call {@link #get} and {@link #set} with the
 * assumption that reads and writes will happen asynchronously, eg. they should
 * continually poll {@link #get} rather than caching any responses returned
 * from the preferences object.</p>
 *
 * <p>Behaviour is such that any call to {@link #has} or {@link #get} will
 * trigger asynchronous retrieval of properties from the backend server.
 * Likewise calls to {@link #set} will trigger asychronous commit of dirty
 * values (both reads and sets are batched and sent to the server as a single
 * request where possible).</p>
 *
 * <p>Keys in the collection are restricted to lowercase letters and the period
 * symbol only, failure to adhere to this format will cause any accessor methods
 * to throw InvalidKeyException. Values in the collection are strings and are
 * limited to 255 characters and must not be null, failure to adhere to these
 * restrictions will cause accessors to throw {@link InvalidValueException}.</p>
 *
 * <p>Consumers can trigger synchronisation events on the collection using
 * convenience methods, these methods do not ensure propagation of settings but
 * act can be used to alter the normal behaviour of the set when necessary, for
 * example to poll for updated values periodically. The methods request(),
 * poll() and commit() can be used to trigger synchronisation events, consult
 * the javadoc for each method for more details.</p>
 *
 * @author Adam Mummery-Smith
 */
public interface IWebPreferences
{
    /**
     * Get the UUID assoicated with this preference collection
     */
    public abstract String getUUID();
    
    /**
     * Get whether this collection is private or public
     */
    public abstract boolean isPrivate();

    /**
     * Get whether this collection is read-only. Only the player's local
     * preferences are writable. Any attempt to write to a read-only collection
     * will throw a ReadOnlyPreferencesException.
     */
    public abstract boolean isReadOnly();
    
    /**
     * Indicate to the set that the value specified by key is required an
     * should be fetched from the server in the next batch. In general,
     * consumers should use get() or has() to access the values in this
     * collection, and expect that the collection will manage fetching the
     * values from the server as part of the normal update cycle. However this
     * method has two uses:</p>
     *
     * <ul>
     *   <li>You may choose to call {@link #request} when a handle to a
     *   preferences set is obtained, to indicate to the preferences set that
     *   you will require the value in the future and it should attempt to fetch
     *   the value so that it is ready for queries against the set later.</li>
     *   <li>You may wish to indicate to the set that it should request an
     *   updated value from the server for a key which it already has (normally
     *   values are cached indefinitely).</li>
     * </ul>
     *
     * <p>In both cases, calls to request() should generally be limited to
     * periodic request for values, to avoid constantly polling the server for
     * values, and potentially running foul of request throttling at the server
     * side</p>
     *
     * @param key key to request from the server
     */
    public abstract void request(String key);

    /**
     * Works exactly as {@link IWebPreferences#request(String)} but allows
     * multiple values to be requested in a single invocation
     *
     * @param keys keys to request
     */
    public abstract void request(String... keys);

    /**
     * Works exactly as {@link IWebPreferences#request(String)} but allows
     * multiple values to be requested in a single invocation
     *
     * @param keys keys to request
     */
    public abstract void request(Set<String> keys);

    /**
     * Calling <tt>poll()</tt> is essentially the same as calling
     * {@link #request} for every key currently in the collection, this method
     * can essentially be used to refresh the entire collection and should be
     * called only in exceptional circumstances. It is called automatically by
     * the preferences manager when connecting to a server.
     *
     * <p>Invoking <tt>poll()</tt> causes all of the values in the collection to
     * be requested as a single batch</p>
     */
    public abstract void poll();

    /**
     * Similar to {@link #poll} except for property writes instead of property
     * reads. Under normal circumstances it should not be necessary to call this
     * method, since commits are handled asychronously by the update loop.
     * However it can be used to forcibly commit even "clean" values to the
     * server. This is useful if you wish to ensure that values on the server be
     * set to match the current values in the collection, regardless of
     * comodification elsewhere.
     *
     * @param force If set to false, only dirty properties are batched. If true,
     *      all properties are batched.
     */
    public abstract void commit(boolean force);
    
    /**
     * Get whether this collection has a value for the specified key, and
     * triggers asnchronous retrieval if not
     *
     * @param key Key to check for
     * @return true if collection has specified key
     */
    public abstract boolean has(String key);

    /**
     * Get the value for the specified key from this collection. Invoking this
     * method causes asynchronous retrieval of the specified key if it is not
     * found in the collection and returns null. If the key is found, then the
     * value is returned and the collection remains unchanged.
     *
     * @param key
     * @return value or null
     */
    public abstract String get(String key);
    
    /**
     * Works exactly like get(String), including triggering asynchronous
     * retrieval of the property if the property is not found in the collection,
     * except that if the property is not found the specified defaultValue is
     * returned instead of returning null.
     *
     * @param key
     * @param defaultValue
     * @return value or default
     */
    public abstract String get(String key, String defaultValue);

    /**
     * Sets a value in the collection and marks it for asynchronous commit to
     * the server.
     *
     * @param key
     * @param value
     */
    public abstract void set(String key, String value);

    /**
     * Remove a key from this collection. Marks the key to be deleted from the
     * server as well.
     *
     * @param key
     */
    public abstract void remove(String key);
}