// This Source Code is in the Public Domain per: http://unlicense.org
package org.litesoft.GWT.eventbus.client;

import java.io.*;
import java.util.*;

public class ParamMap implements Serializable {
    public static final ParamMap LOCKED_EMPTY = new ImmutableParamMap();

    public static ParamMap immutableCopy( ParamMap paramMap ) {
        return (paramMap != null) ? paramMap.immutableCopy() : null;
    }

    public ParamMap immutableCopy() {
        return new ImmutableParamMap( this );
    }

    // Native boolean
    public ParamMap add( String key, boolean value ) {
        return privatePut( key, Boolean.valueOf( value ) );
    }

    public ParamMap add( String key, boolean[] value ) {
        return privatePut( key, value );
    }

    public boolean get_boolean( String pKey, boolean pDefault ) {
        return get_booleanFrom( this, pKey, pDefault );
    }

    public static boolean get_booleanFrom( ParamMap pMap, String pKey, boolean pDefault ) {
        Boolean value = getBooleanFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.booleanValue() : pDefault;
    }

    public boolean[] get_booleanArray( String pKey ) {
        return get_booleanArrayFrom( this, pKey );
    }

    public boolean[] get_booleanArray( String pKey, boolean[] pDefault ) {
        return get_booleanArrayFrom( this, pKey, pDefault );
    }

    public static boolean[] get_booleanArrayFrom( ParamMap pMap, String pKey, boolean[] pDefault ) {
        boolean[] value = get_booleanArrayFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value : pDefault;
    }

    public static boolean[] get_booleanArrayFrom( ParamMap pMap, String pKey ) {
        return (boolean[]) getFrom( pMap, pKey );
    }

    // Boolean
    public ParamMap add( String key, Boolean value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Boolean[] value ) {
        return privatePut( key, value );
    }

    public Boolean getBoolean( String pKey ) {
        return getBoolean( pKey, null );
    }

    public Boolean getBoolean( String pKey, Boolean pDefault ) {
        return getBooleanFrom( this, pKey, pDefault );
    }

    public static Boolean getBooleanFrom( ParamMap pMap, String pKey, Boolean pDefault ) {
        Boolean value = getBooleanFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Boolean getBooleanFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Boolean ) {
            return (Boolean) value;
        }
        return Boolean.valueOf( value.toString() );
    }

    public Boolean[] getBooleanArray( String pKey ) {
        return getBooleanArrayFrom( this, pKey );
    }

    public Boolean[] getBooleanArray( String pKey, Boolean[] pDefault ) {
        return getBooleanArrayFrom( this, pKey, pDefault );
    }

    public static Boolean[] getBooleanArrayFrom( ParamMap pMap, String pKey, Boolean[] pDefault ) {
        Boolean[] value = getBooleanArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Boolean[] getBooleanArrayFrom( ParamMap pMap, String pKey ) {
        return (Boolean[]) getFrom( pMap, pKey );
    }

    // Date
    public ParamMap add( String key, Date value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Date[] value ) {
        return privatePut( key, value );
    }

    public Date getDate( String pKey ) {
        return getDate( pKey, null );
    }

    public Date getDate( String pKey, Date pDefault ) {
        return getDateFrom( this, pKey, pDefault );
    }

    public static Date getDateFrom( ParamMap pMap, String pKey ) {
        return (Date) getFrom( pMap, pKey );
    }

    public static Date getDateFrom( ParamMap pMap, String pKey, Date pDefault ) {
        Date value = getDateFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public Date[] getDateArray( String pKey ) {
        return getDateArrayFrom( this, pKey );
    }

    public Date[] getDateArray( String pKey, Date[] pDefault ) {
        return getDateArrayFrom( this, pKey, pDefault );
    }

    public static Date[] getDateArrayFrom( ParamMap pMap, String pKey, Date[] pDefault ) {
        Date[] value = getDateArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Date[] getDateArrayFrom( ParamMap pMap, String pKey ) {
        return (Date[]) getFrom( pMap, pKey );
    }

    // Native double
    public ParamMap add( String key, double value ) {
        return privatePut( key, new Double( value ) );
    }

    public ParamMap add( String key, double[] value ) {
        return privatePut( key, value );
    }

    public double get_double( String pKey, double pDefault ) {
        return get_doubleFrom( this, pKey, pDefault );
    }

    public static double get_doubleFrom( ParamMap pMap, String pKey, double pDefault ) {
        Double value = getDoubleFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.doubleValue() : pDefault;
    }

    public double[] get_doubleArray( String pKey ) {
        return get_doubleArrayFrom( this, pKey );
    }

    public double[] get_doubleArray( String pKey, double[] pDefault ) {
        return get_doubleArrayFrom( this, pKey, pDefault );
    }

    public static double[] get_doubleArrayFrom( ParamMap pMap, String pKey, double[] pDefault ) {
        double[] value = get_doubleArrayFrom( pMap, pKey );
        return value != null ? value : pDefault;
    }

    public static double[] get_doubleArrayFrom( ParamMap pMap, String pKey ) {
        return (double[]) getFrom( pMap, pKey );
    }

    // Double
    public ParamMap add( String key, Double value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Double[] value ) {
        return privatePut( key, value );
    }

    public Double getDouble( String pKey ) {
        return getDouble( pKey, null );
    }

    public Double getDouble( String pKey, Double pDefault ) {
        return getDoubleFrom( this, pKey, pDefault );
    }

    public static Double getDoubleFrom( ParamMap pMap, String pKey, Double pDefault ) {
        Double value = getDoubleFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Double getDoubleFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Double ) {
            return (Double) value;
        }
        if ( value instanceof Number ) {
            //noinspection UnnecessaryBoxing
            return new Double( ((Number) value).doubleValue() );
        }
        return new Double( value.toString() );
    }

    public Double[] getDoubleArray( String pKey ) {
        return getDoubleArrayFrom( this, pKey );
    }

    public Double[] getDoubleArray( String pKey, Double[] pDefault ) {
        return getDoubleArrayFrom( this, pKey, pDefault );
    }

    public static Double[] getDoubleArrayFrom( ParamMap pMap, String pKey, Double[] pDefault ) {
        Double[] value = getDoubleArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Double[] getDoubleArrayFrom( ParamMap pMap, String pKey ) {
        return (Double[]) getFrom( pMap, pKey );
    }

    // Native float
    public ParamMap add( String key, float value ) {
        return privatePut( key, new Float( value ) );
    }

    public ParamMap add( String key, float[] value ) {
        return privatePut( key, value );
    }

    public float get_float( String pKey, float pDefault ) {
        return get_floatFrom( this, pKey, pDefault );
    }

    public static float get_floatFrom( ParamMap pMap, String pKey, float pDefault ) {
        Float value = getFloatFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.floatValue() : pDefault;
    }

    public float[] get_floatArray( String pKey ) {
        return get_floatArrayFrom( this, pKey );
    }

    public float[] get_floatArray( String pKey, float[] pDefault ) {
        return get_floatArrayFrom( this, pKey, pDefault );
    }

    public static float[] get_floatArrayFrom( ParamMap pMap, String pKey, float[] pDefault ) {
        float[] value = get_floatArrayFrom( pMap, pKey );
        return value != null ? value : pDefault;
    }

    public static float[] get_floatArrayFrom( ParamMap pMap, String pKey ) {
        return (float[]) getFrom( pMap, pKey );
    }

    // Float
    public ParamMap add( String key, Float value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Float[] value ) {
        return privatePut( key, value );
    }

    public Float getFloat( String pKey ) {
        return getFloat( pKey, null );
    }

    public Float getFloat( String pKey, Float pDefault ) {
        return getFloatFrom( this, pKey, pDefault );
    }

    public static Float getFloatFrom( ParamMap pMap, String pKey, Float pDefault ) {
        Float value = getFloatFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Float getFloatFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Float ) {
            return (Float) value;
        }
        if ( value instanceof Number ) {
            //noinspection UnnecessaryBoxing
            return new Float( ((Number) value).floatValue() );
        }
        return new Float( value.toString() );
    }

    public Float[] getFloatArray( String pKey ) {
        return getFloatArrayFrom( this, pKey );
    }

    public Float[] getFloatArray( String pKey, Float[] pDefault ) {
        return getFloatArrayFrom( this, pKey, pDefault );
    }

    public static Float[] getFloatArrayFrom( ParamMap pMap, String pKey, Float[] pDefault ) {
        Float[] value = getFloatArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Float[] getFloatArrayFrom( ParamMap pMap, String pKey ) {
        return (Float[]) getFrom( pMap, pKey );
    }

    // Native int
    public ParamMap add( String key, int value ) {
        return privatePut( key, new Integer( value ) );
    }

    public ParamMap add( String key, int[] value ) {
        return privatePut( key, value );
    }

    public int get_int( String pKey, int pDefault ) {
        return get_intFrom( this, pKey, pDefault );
    }

    public static int get_intFrom( ParamMap pMap, String pKey, int pDefault ) {
        Integer value = getIntegerFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.intValue() : pDefault;
    }

    public int[] get_intArray( String pKey ) {
        return get_intArrayFrom( this, pKey );
    }

    public int[] get_intArray( String pKey, int[] pDefault ) {
        return get_intArrayFrom( this, pKey, pDefault );
    }

    public static int[] get_intArrayFrom( ParamMap pMap, String pKey, int[] pDefault ) {
        int[] value = get_intArrayFrom( pMap, pKey );
        return value != null ? value : pDefault;
    }

    public static int[] get_intArrayFrom( ParamMap pMap, String pKey ) {
        return (int[]) getFrom( pMap, pKey );
    }

    // Integer
    public ParamMap add( String key, Integer value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Integer[] value ) {
        return privatePut( key, value );
    }

    public Integer getInteger( String pKey ) {
        return getInteger( pKey, null );
    }

    public Integer getInteger( String pKey, Integer pDefault ) {
        return getIntegerFrom( this, pKey, pDefault );
    }

    public static Integer getIntegerFrom( ParamMap pMap, String pKey, Integer pDefault ) {
        Integer value = getIntegerFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Integer getIntegerFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Integer ) {
            return (Integer) value;
        }
        if ( value instanceof Number ) {
            //noinspection UnnecessaryBoxing
            return new Integer( ((Number) value).intValue() );
        }
        return new Integer( value.toString() );
    }

    public Integer[] getIntegerArray( String pKey ) {
        return getIntegerArrayFrom( this, pKey );
    }

    public Integer[] getIntegerArray( String pKey, Integer[] pDefault ) {
        return getIntegerArrayFrom( this, pKey, pDefault );
    }

    public static Integer[] getIntegerArrayFrom( ParamMap pMap, String pKey, Integer[] pDefault ) {
        Integer[] value = getIntegerArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Integer[] getIntegerArrayFrom( ParamMap pMap, String pKey ) {
        return (Integer[]) getFrom( pMap, pKey );
    }

    // Native long
    public ParamMap add( String key, long value ) {
        return privatePut( key, new Long( value ) );
    }

    public ParamMap add( String key, long[] value ) {
        return privatePut( key, value );
    }

    public long get_long( String pKey, long pDefault ) {
        return get_longFrom( this, pKey, pDefault );
    }

    public static long get_longFrom( ParamMap pMap, String pKey, long pDefault ) {
        Long value = getLongFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.longValue() : pDefault;
    }

    public long[] get_longArray( String pKey, long[] pDefault ) {
        return get_longArrayFrom( this, pKey, pDefault );
    }

    public static long[] get_longArrayFrom( ParamMap pMap, String pKey, long[] pDefault ) {
        long[] value = get_longArrayFrom( pMap, pKey );
        return value != null ? value : pDefault;
    }

    public static long[] get_longArrayFrom( ParamMap pMap, String pKey ) {
        return (long[]) getFrom( pMap, pKey );
    }

    // Long
    public ParamMap add( String key, Long value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Long[] value ) {
        return privatePut( key, value );
    }

    public Long getLong( String pKey ) {
        return getLong( pKey, null );
    }

    public Long getLong( String pKey, Long pDefault ) {
        return getLongFrom( this, pKey, pDefault );
    }

    public static Long getLongFrom( ParamMap pMap, String pKey, Long pDefault ) {
        Long value = getLongFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Long getLongFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Long ) {
            return (Long) value;
        }
        if ( value instanceof Number ) {
            //noinspection UnnecessaryBoxing
            return new Long( ((Number) value).longValue() );
        }
        return new Long( value.toString() );
    }

    public Long[] getLongArray( String pKey ) {
        return getLongArrayFrom( this, pKey );
    }

    public Long[] getLongArray( String pKey, Long[] pDefault ) {
        return getLongArrayFrom( this, pKey, pDefault );
    }

    public static Long[] getLongArrayFrom( ParamMap pMap, String pKey, Long[] pDefault ) {
        Long[] value = getLongArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Long[] getLongArrayFrom( ParamMap pMap, String pKey ) {
        return (Long[]) getFrom( pMap, pKey );
    }

    // Native short
    public ParamMap add( String key, short value ) {
        return privatePut( key, new Short( value ) );
    }

    public ParamMap add( String key, Short[] value ) {
        return privatePut( key, value );
    }

    public short get_short( String pKey, short pDefault ) {
        return get_shortFrom( this, pKey, pDefault );
    }

    public static short get_shortFrom( ParamMap pMap, String pKey, short pDefault ) {
        Short value = getShortFrom( pMap, pKey );
        //noinspection UnnecessaryUnboxing
        return value != null ? value.shortValue() : pDefault;
    }

    public short[] get_shortArray( String pKey ) {
        return get_shortArrayFrom( this, pKey );
    }

    public short[] get_shortArray( String pKey, short[] pDefault ) {
        return get_shortArrayFrom( this, pKey, pDefault );
    }

    public static short[] get_shortArrayFrom( ParamMap pMap, String pKey, short[] pDefault ) {
        short[] value = get_shortArrayFrom( pMap, pKey );
        return value != null ? value : pDefault;
    }

    public static short[] get_shortArrayFrom( ParamMap pMap, String pKey ) {
        return (short[]) getFrom( pMap, pKey );
    }

    // Short
    public ParamMap add( String key, Short value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, short[] value ) {
        return privatePut( key, value );
    }

    public Short getShort( String pKey ) {
        return getShort( pKey, null );
    }

    public Short getShort( String pKey, Short pDefault ) {
        return getShortFrom( this, pKey, pDefault );
    }

    public static Short getShortFrom( ParamMap pMap, String pKey, Short pDefault ) {
        Short value = getShortFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Short getShortFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        if ( value instanceof Short ) {
            return (Short) value;
        }
        if ( value instanceof Number ) {
            //noinspection UnnecessaryBoxing
            return new Short( ((Number) value).shortValue() );
        }
        return new Short( value.toString() );
    }

    public Short[] getShortArray( String pKey ) {
        return getShortArrayFrom( this, pKey );
    }

    public Short[] getShortArray( String pKey, Short[] pDefault ) {
        return getShortArrayFrom( this, pKey, pDefault );
    }

    public static Short[] getShortArrayFrom( ParamMap pMap, String pKey, Short[] pDefault ) {
        Short[] value = getShortArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Short[] getShortArrayFrom( ParamMap pMap, String pKey ) {
        return (Short[]) getFrom( pMap, pKey );
    }

    // String
    public ParamMap add( String key, String value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, String[] value ) {
        return privatePut( key, value );
    }

    public String getString( String pKey ) {
        return getString( pKey, null );
    }

    public String getString( String pKey, String pDefault ) {
        return getStringFrom( this, pKey, pDefault );
    }

    public static String getStringFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        return (value == null) ? null : (String) value;
    }

    public static String getStringFrom( ParamMap pMap, String pKey, String pDefault ) {
        String value = getStringFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public String[] getStringArray( String pKey ) {
        return getStringArrayFrom( this, pKey );
    }

    public String[] getStringArray( String pKey, String[] pDefault ) {
        return getStringArrayFrom( this, pKey, pDefault );
    }

    public static String[] getStringArrayFrom( ParamMap pMap, String pKey, String[] pDefault ) {
        String[] value = getStringArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static String[] getStringArrayFrom( ParamMap pMap, String pKey ) {
        return (String[]) getFrom( pMap, pKey );
    }

    // ParamMap
    public ParamMap add( String key, ParamMap value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, ParamMap[] value ) {
        return privatePut( key, value );
    }

    public ParamMap getParamMap( String pKey ) {
        return getParamMap( pKey, null );
    }

    public ParamMap getParamMap( String pKey, ParamMap pDefault ) {
        return getParamMapFrom( this, pKey, pDefault );
    }

    public static ParamMap getParamMapFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        return (value == null) ? null : (ParamMap) value;
    }

    public static ParamMap getParamMapFrom( ParamMap pMap, String pKey, ParamMap pDefault ) {
        ParamMap value = getParamMapFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public ParamMap[] getParamMapArray( String pKey ) {
        return getParamMapArrayFrom( this, pKey );
    }

    public ParamMap[] getParamMapArray( String pKey, ParamMap[] pDefault ) {
        return getParamMapArrayFrom( this, pKey, pDefault );
    }

    public static ParamMap[] getParamMapArrayFrom( ParamMap pMap, String pKey, ParamMap[] pDefault ) {
        ParamMap[] value = getParamMapArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static ParamMap[] getParamMapArrayFrom( ParamMap pMap, String pKey ) {
        return (ParamMap[]) getFrom( pMap, pKey );
    }

    // Serializable
    public ParamMap add( String key, Serializable value ) {
        return privatePut( key, value );
    }

    public ParamMap add( String key, Serializable[] value ) {
        return privatePut( key, value );
    }

    public Serializable getSerializable( String pKey ) {
        return getSerializable( pKey, null );
    }

    public Serializable getSerializable( String pKey, Serializable pDefault ) {
        return getSerializableFrom( this, pKey, pDefault );
    }

    public static Serializable getSerializableFrom( ParamMap pMap, String pKey, Serializable pDefault ) {
        Serializable value = getSerializableFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Serializable getSerializableFrom( ParamMap pMap, String pKey ) {
        Object value = getFrom( pMap, pKey );
        if ( value == null ) {
            return null;
        }
        return (Serializable) value;
    }

    public Serializable[] getSerializableArray( String pKey ) {
        return getSerializableArrayFrom( this, pKey );
    }

    public Serializable[] getSerializableArray( String pKey, Serializable[] pDefault ) {
        return getSerializableArrayFrom( this, pKey, pDefault );
    }

    public static Serializable[] getSerializableArrayFrom( ParamMap pMap, String pKey, Serializable[] pDefault ) {
        Serializable[] value = getSerializableArrayFrom( pMap, pKey );
        return (value != null) ? value : pDefault;
    }

    public static Serializable[] getSerializableArrayFrom( ParamMap pMap, String pKey ) {
        return (Serializable[]) getFrom( pMap, pKey );
    }

    // Object
    private static Object getFrom( ParamMap pMap, String pKey ) {
        return (pMap == null) ? null : pMap.mProxiedMap.get( pKey );
    }

    public ParamMap() {
    }

    public ParamMap( ParamMap pMap ) {
        LLputAll( pMap );
    }

    public ParamMap( String[] pNameValuePairs ) {
        if ( pNameValuePairs != null ) {
            if ( (pNameValuePairs.length & 1) == 1 ) {
                throw new IllegalArgumentException( "NameValuePairs not paired" );
            }
            for ( int i = 0; i < pNameValuePairs.length; ) {
                String name = pNameValuePairs[i++];
                String value = pNameValuePairs[i++];
                add( name, value );
            }
        }
    }

    private void LLputAll( ParamMap t ) {
        if ( t != null ) {
            invalidateCache();
            mProxiedMap.putAll( t.mProxiedMap );
        }
    }

    /**
     * Returns the number of key-value mappings in this map.  If the
     * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
     * <tt>Integer.MAX_VALUE</tt>.
     *
     * @return the number of key-value mappings in this map (or <tt>Integer.MAX_VALUE</tt>).
     */
    public int size() {
        return mProxiedMap.size();
    }

    /**
     * Returns <tt>true</tt> if this map contains no key-value mappings.
     *
     * @return <tt>true</tt> if this map contains no key-value mappings.
     */
    public boolean isEmpty() {
        return mProxiedMap.isEmpty();
    }

    /**
     * Returns <tt>true</tt> if this map contains a mapping for the specified
     * key.  More formally, returns <tt>true</tt> if and only if
     * this map contains a mapping for a key <tt>k</tt> such that
     * <tt>(key==null ? k==null : key.equals(k))</tt>.  (There can be
     * at most one such mapping.)
     *
     * @param key key whose presence in this map is to be tested.
     *
     * @return <tt>true</tt> if this map contains a mapping for the specified
     * key.
     *
     * @throws ClassCastException   if the key is of an inappropriate type for
     *                              this map (optional).
     * @throws NullPointerException if the key is <tt>null</tt> and this map
     *                              does not permit <tt>null</tt> keys (optional).
     */
    public boolean containsKey( String key ) {
        return mProxiedMap.containsKey( key );
    }

    // todo: ==============================================================================================//

    // todo: Eliminate
    public <T> List<T> get_RawList_ThisMethodShouldNotEverEverBeUsed( String pKey ) {
        return (List<T>) getFrom( this, pKey );
    }

    // todo: Eliminate
    public <T> Set<T> get_RawSet_ThisMethodShouldNotEverEverBeUsed( String pKey ) {
        return (Set<T>) getFrom( this, pKey );
    }

    // todo: Eliminate
    public ParamMap add_RawMap_ThisMethodShouldNotEverEverBeUsed( String key, Map value ) {
        return privatePut( key, value );
    }

    // todo: Eliminate
    public ParamMap add_RawSet_ThisMethodShouldNotEverEverBeUsed( String key, Set value ) {
        return privatePut( key, value );
    }

    // todo: Eliminate
    public ParamMap add_RawList_ThisMethodShouldNotEverEverBeUsed( String key, List value ) {
        return privatePut( key, value );
    }

    // todo: Eliminate
    public void putAll_RawObjects_ThisMethodShouldNotEverEverBeUsed( Map<?, ?> t ) {
        if ( t != null ) {
            //noinspection ForLoopReplaceableByForEach
            for ( Iterator<?> it = t.keySet().iterator(); it.hasNext(); ) {
                Object key = it.next();
                if ( key instanceof String ) {
                    privatePut( key.toString(), t.get( key ) );
                }
            }
        }
    }

    /**
     * Removes the mapping for this key from this map if it is present
     * (optional operation).   More formally, if this map contains a mapping
     * from key <tt>k</tt> to value <tt>v</tt> such that
     * <code>(key==null ?  k==null : key.equals(k))</code>, that mapping
     * is removed.  (The map can contain at most one such mapping.)
     * <p/>
     * <p>Returns the value to which the map previously associated the key, or
     * <tt>null</tt> if the map contained no mapping for this key.  (A
     * <tt>null</tt> return can also indicate that the map previously
     * associated <tt>null</tt> with the specified key if the implementation
     * supports <tt>null</tt> values.)  The map will not contain a mapping for
     * the specified  key once the call returns.
     *
     * @param key key whose mapping is to be removed from the map.
     *
     * @return previous value associated with specified key, or <tt>null</tt>
     * if there was no mapping for key.
     *
     * @throws ClassCastException            if the key is of an inappropriate type for
     *                                       this map (optional).
     * @throws NullPointerException          if the key is <tt>null</tt> and this map
     *                                       does not permit <tt>null</tt> keys (optional).
     * @throws UnsupportedOperationException if the <tt>remove</tt> method is
     *                                       not supported by this map.
     */
    public Object remove( String key ) {
        return privatePut( key, null );
    }

    // Bulk Operations

    /**
     * Copies all of the mappings from the specified map to this map
     * (optional operation).  The effect of this call is equivalent to that
     * of calling put(k, v) on this map once
     * for each mapping from key <tt>k</tt> to value <tt>v</tt> in the
     * specified map.  The behavior of this operation is unspecified if the
     * specified map is modified while the operation is in progress.
     *
     * @param t Mappings to be stored in this map.
     *
     * @throws UnsupportedOperationException if the <tt>putAll</tt> method is
     *                                       not supported by this map.
     * @throws ClassCastException            if the class of a key or value in the
     *                                       specified map prevents it from being stored in this map.
     * @throws IllegalArgumentException      some aspect of a key or value in the
     *                                       specified map prevents it from being stored in this map.
     * @throws NullPointerException          if the specified map is <tt>null</tt>, or if
     *                                       this map does not permit <tt>null</tt> keys or values, and the
     *                                       specified map contains <tt>null</tt> keys or values.
     */
    public void putAll( ParamMap t ) {
        LLputAll( t );
    }

    /**
     * Removes all mappings from this map (optional operation).
     *
     * @throws UnsupportedOperationException clear is not supported by this
     *                                       map.
     */
    public void clear() {
        invalidateCache();
        mProxiedMap.clear();
    }

    // Views

    /**
     * Returns a collection view of the values contained in this map.  The
     * collection is NOT backed by the map.
     *
     * @return a collection view of the values contained in this map.
     */
    public Collection<Object> values() {
        //noinspection unchecked
        return new ArrayList<Object>( mProxiedMap.values() );
    }

    // Comparison and hashing

    /**
     * Compares the specified object with this map for equality.  Returns
     * <tt>true</tt> if the given object is also a map and the two Maps
     * represent the same mappings.  More formally, two maps <tt>t1</tt> and
     * <tt>t2</tt> represent the same mappings if
     * <tt>t1.entrySet().equals(t2.entrySet())</tt>.  This ensures that the
     * <tt>equals</tt> method works properly across different implementations
     * of the <tt>Map</tt> interface.
     *
     * @param o object to be compared for equality with this map.
     *
     * @return <tt>true</tt> if the specified object is equal to this map.
     */
    public boolean equals( Object o ) {
        return (this == o) || mProxiedMap.equals( (o instanceof ParamMap) ? ((ParamMap) o).mProxiedMap : o );
    }

    /**
     * Returns the hash code value for this map.  The hash code of a map
     * is defined to be the sum of the hashCodes of each entry in the map's
     * entrySet view.  This ensures that <tt>t1.equals(t2)</tt> implies
     * that <tt>t1.hashCode()==t2.hashCode()</tt> for any two maps
     * <tt>t1</tt> and <tt>t2</tt>, as required by the general
     * contract of Object.hashCode.
     *
     * @return the hash code value for this map.
     *
     * @see Object#hashCode()
     * @see Object#equals(Object)
     * @see #equals(Object)
     */
    public int hashCode() {
        return mProxiedMap.hashCode();
    }

    public synchronized String[] keys() {
        if ( mKeysAsStringsUnsorted == null ) {
            String[] temp = new String[mProxiedMap.size()];
            mProxiedMap.keySet().toArray( temp );
            mKeysAsStringsUnsorted = temp; // atomic assignment (GWT?)
        }
        return mKeysAsStringsUnsorted;
    }

    public synchronized String[] sortedKeys() {
        if ( mKeysAsStringsSorted == null ) {
            String[] temp = new String[mProxiedMap.size()];
            mProxiedMap.keySet().toArray( temp );
            Arrays.sort( temp );
            mKeysAsStringsSorted = temp; // atomic assignment (GWT?)
        }
        return mKeysAsStringsSorted;
    }

    public String toString() {
        StringBuilder sb = new StringBuilder( "[" );
        if ( !isEmpty() ) {
            String[] keys = keys();
            String zKey = keys[0];
            sb.append( zKey ).append( '=' ).append( mProxiedMap.get( zKey ) );
            for ( int i = 1; i < keys.length; i++ ) {
                zKey = keys[i];
                sb.append( ", " ).append( zKey ).append( '=' ).append( mProxiedMap.get( zKey ) );
            }
        }
        return sb.append( ']' ).toString();
    }

    // below here for internal use!

    private ParamMap privatePut( String key, Object value ) {
        if ( key == null ) {
            return null;
        }
        invalidateCache();
        //noinspection unchecked
        if ( (value == null) ) {
            mProxiedMap.remove( key );
        } else {
            mProxiedMap.put( key, value );
        }
        return this;
    }

    private void invalidateCache() {
        mKeysAsStringsUnsorted = null;
        mKeysAsStringsSorted = null;
    }

    private HashMap<String, Object> mProxiedMap = new HashMap<String, Object>();

    private transient String[] mKeysAsStringsUnsorted = null;
    private transient String[] mKeysAsStringsSorted = null;

    protected void finalize()
            throws Throwable {
        mProxiedMap.clear();
        super.finalize();
    }

    /**
     * Copy all the entries from the ParamMap into the supplied Map (pMap).
     *
     * @param pMap
     *
     * @return pMap
     */
    public Map<Object, Object> putAllInto( Map<Object, Object> pMap ) {
        if ( (pMap != null) && !isEmpty() ) {
            for ( Iterator<String> it = mProxiedMap.keySet().iterator(); it.hasNext(); ) {
                Object zKey = it.next();
                pMap.put( zKey, mProxiedMap.get( zKey ) );
            }
        }
        return pMap;
    }

    // todo: Eliminate
    private Object LLgetRawValue( String pKey ) {
        return mProxiedMap.get( pKey );
    }

    public static final class BackDoor {
        public static Object getRawValue( ParamMap pParamMap, String pKey ) {
            return pParamMap.LLgetRawValue( pKey );
        }
    }
}