package org.litesoft.GWT.client.localstorage;

import org.litesoft.commonfoundation.annotations.*;

import java.util.*;

/**
 * Local Storage is a Proxy/Adapter to the underlying HTML5 LocalStorage.
 * <p/>
 * The exposed API is that of a String to String Map with three important differences:
 * <li>null keys are NOT supported</li>
 * <li>null values for values on a <code>put</code> are treated as a call to <code>remove</code></li>
 * <li>keys are trimmed of their leading and trailing whitespace and if the resulting key is empty it is treated as a null</li>
 */
public interface LocalStorage extends Map<String, String> {
    /**
     * The same behavior as the regular Map.get, but with an explicit key type of String.
     * <p/>
     * Note: The regular Map.get <code>key</code> parameter will also be enforced to be a String and not be null!
     *
     * @param pKey the key whose associated value is to be returned
     *
     * @return the value to which the specified key is mapped, or
     * {@code null} if this map contains no mapping for the key
     */
    String get( @NotNull String pKey );
}