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;
}
}