/*
 Copyright (c) 2006 - 2008  Eric J. Feminella  <eric@ericfeminella.com>
 All rights reserved.

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is 
 furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included in 
 all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
 THE SOFTWARE.

 @internal
 */

package com.ericfeminella.application
{
    import com.ericfeminella.collections.IMap;

    /**
     *
     * Defines the contract for classes which must provide a robust
     * API which allows detailed inspection of a QueryString
     *
     * @see com.ericfeminella.utils.IMap
     *
     */
    public interface IQueryString
    {
        /**
         *
         * Determines if parameters have been provided to the
         * application
         *
         * @return true if supplied, false if not
         *
         */
        function get isProvided() : Boolean;

        /**
         *
         * Retrieves the raw query string provided to the application
         *
         * @param  specifies if the query string is to be URL decoded
         * @return the raw query string which has been supplied / modified
         *
         */
        function getQueryString(decode:Boolean = false) : String;

        /**
         *
         * Retrieves each name / value pair provided to the application
         * and returns an Array of Objects which contain each parameter
         * name and value
         *
         * @return IMap containing key / values as specified in the querystring
         *
         */
        function getParameters() : IMap;

        /**
         *
         * Adds a new parameter; name / value pair to the querystring
         *
         * <p>
         * If the parameter name which has been specified currently
         * exists in the querystring then it is simply ignored.
         * </p>
         *
         * <p>
         * If you need to overwrite an existing parameter or modify the
         * value of an existing parameter use <code>setValue</code>
         * instead
         * </p>
         *
         * @param  name of the parameter
         * @param  value to assigned to the specified parameter name
         *
         */
        function addParameter(name:String, value:*) : void;

        /**
         *
         * Removes an existing parameter from the querystring
         *
         * @param  the name of the parameter which is to b removed
         *
         */
        function removeParameter(name:String) : void;

        /**
         *
         * Determines if the specified parameter has been provided to
         * the query string
         *
         * @param  the paramter to determine
         * @return true if supplied, false if not
         *
         */
        function containsParameter(name:String) : Boolean;

        /**
         *
         * Retrieves the parameter names provided to the application
         *
         * @return each query string parameter name
         *
         */
        function getNames() : Array;

        /**
         *
         * Retrieves a specific parameter name based on the parameters
         * value
         *
         * @param  the value of the parameter which is to be located
         * @return parameter name to which the specified value has been assigned
         *
         */
        function getName(value:String) : String;

        /**
         *
         * Retrieves the parameter values provided to the application
         *
         * @return each query string parameter value
         *
         */
        function getValues() : Array;

        /**
         *
         * Retrieves the value of the specified parameter name. If the
         * parameter does not exist a null value is returned. If the
         * name has not been provided in the querystring then a null
         * value is returned
         *
         * @param  the name of the parameter
         * @return the value of the specified paramter name
         *
         */
        function getValue(name:String) : *;

        /**
         *
         * Assigns a new value to the specified querystring parameter
         *
         * @param  the name of the parameter
         * @param  the value to assigned to the specified parameter name
         *
         */
        function setValue(name:String, value:*) : void;

        /**
         *
         * Determines if the specified value has been provided to the
         * query string
         *
         * @param  the value in which to determine
         * @return true if the value has been provided, false if not
         *
         */
        function containsValue(value:*) : Boolean;

        /**
         *
         * Appends the current state of the <code>querystring</code>
         * to a URL
         *
         * @param  the url to which the querystring is to be appended
         * @param  specifies if the querystring is to be URL decoded /encoded
         * @return the specified url with the querystring appended
         *
         */
        function appendToURL(url:String, decode:Boolean = false) : String;

        /**
         *
         * Determines the length of the query string based on the
         * amount of name value pairs which have been supplied to
         * the QueryString
         *
         * @return the length of the query string
         *
         */
        function length() : int;
    }
}