/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.dynamo.iface;

import java.util.Locale;
import java.util.Map;
import com.silverwrist.dynamo.RequestType;
import com.silverwrist.dynamo.Verb;

/**
 * Represents a request made to the Dynamo framework.  Each request contains several pieces of data:
 * <OL>
 * <LI>A {@link com.silverwrist.dynamo.RequestType RequestType}, which indicates the specific type of the request.</LI>
 * <LI>A {@link com.silverwrist.dynamo.Verb Verb}, which indicates the action that should be perfomed by the
 * request. It corresponds roughly to an HTTP method.</LI>
 * <LI>A request URI, split up into a server name and port, <EM>context path</EM> (the top level of the URI path,
 * corresponding to the application itself), <EM>request path</EM> (corresponding to the specific request made
 * within the application), and <EM>extra path</EM> (unparsed path information passed verbatim to the target servlet
 * or other entry point).</LI>
 * <LI>Other request attributes, such as the IP address of the person making the request.</LI>
 * <LI>Zero or more <EM>parameters</EM>, which are names that map to ordered sets (arrays) of values.  These are
 * usually simple parameter types, such as strings.</LI>
 * <LI>Zero or more <EM>data items</EM>, which are names that map to ordered sets (arrays) of
 * {@link com.silverwrist.dynamo.iface.DataItem DataItem} objects.  These are usually entire uploaded files or
 * other large data streams, which generally have a MIME type and name associated with them.</LI>
 * <LI>A set of <EM>request services</EM>, accessible through the
 * {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface.  These represent services exposed
 * by the Dynamo framework or components within it as being suitable for use within a request context.</LI>
 * <LI>A private instance of {@link com.silverwrist.dynamo.iface.ObjectStore ObjectStore} which acts as a
 * <EM>scratch pad</EM> for the request.  The lifetime of the objects stored in this <CODE>ObjectStore</CODE> are
 * exactly that of the <CODE>Request</CODE> object itself.</LI>
 * </OL>
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface Request extends ServiceProvider, ObjectStore
{
  /**
   * Returns a value indicating the type of this request.
   *
   * @return The type of this request.
   * @see com.silverwrist.dynamo.RequestType
   */
  public RequestType getType();

  /**
   * Returns the DNS name or IP address of the server to which the request was made.
   * 
   * @return The server name to which the request was name.
   */
  public String getServerName();

  /**
   * Returns the number of the port on which this request was made.
   *
   * @return The port number on which the request was made, or -1 if it could not be determined.
   */
  public int getServerPort();

  /**
   * Returns the portion of the request URI that indicates the context of the request. The context path always comes
   * first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets
   * in the default (root) context, this method returns "". The servlet container does not decode this string.
   *
   * @return The context path of the request.
   */
  public String getContextPath();

  /**
   * Returns the part of this request's URL that calls the endpoint. This includes either the endpoint name or a path
   * to the endpoint, but does not include any extra path information or a query string.
   *
   * @return The request path of this request.
   */
  public String getRequestPath();

  /**
   * Returns any extra path information associated with the URL the client sent when it made this request. The extra
   * path information follows the request path but precedes the query string. This method returns <CODE>null</CODE>
   * if there was no extra path information.
   *
   * @return The "extra path" of this request.  If there is no "extra path," returns <CODE>null</CODE>.
   */
  public String getExtraPath();

  /**
   * Returns the query string that is contained in the request URL after the path. This method returns
   * <CODE>null</CODE> if the URL does not have a query string.  For XML-RPC requests, this is the name of the
   * method that was called.
   *
   * @return The query string associated with this request.  If there is no query string, returns <CODE>null</CODE>.
   */
  public String getQueryString();

  /**
   * Returns a value indicating the action associated with this request.
   *
   * @return The action associated with this request.
   * @see com.silverwrist.dynamo.Verb
   */
  public Verb getVerb();

  /**
   * Returns a string representation of the IP address of the client that made this request.
   *
   * @return The address of the client making the request.
   */
  public String getSourceAddress();

  /**
   * Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with
   * the request.  For HTTP requests, these parameters are passed in the query string or POST data.  For XML-RPC
   * requests, these parameters are passed as an array associated with the method call.
   * <P>The keys of the map are <CODE>String</CODE> objects; the values of the map are arrays of the type specified
   * by the return value of {@link #getParametersEntryClass() getParametersEntryClass()}.  For XML-RPC, the keys
   * are printable-string equivalents of integers representing the parameters' position.
   *
   * @return The parameter map, as specified above.  This map is read-only.
   */
  public Map getParameters();

  /**
   * Returns a class specifying the fundamental type of objects contained in the arrays acting as the values of
   * the map returned by {@link #getParameters() getParameters()}.  This class may be <CODE>Object</CODE>, indicating
   * that the contained objects may be of any type.
   *
   * @return The class of array elements within the parameter map.
   */
  public Class getParametersEntryClass();

  /**
   * Returns a java.util.Map of the data items of this request.  Data items are lengthy streams of data associated
   * with a request.  XML-RPC requests, and HTTP requests with verbs GET or DELETE, have no data items associated
   * with them.  HTTP PUT requests have one data item, named "_body", which contains the data in the body of the
   * request.  HTTP POST requests, if they were sent with MIME type "multpart/form-data", may have one or more 
   * data items, with a variety of names.
   * <P>The keys of the map are <CODE>String</CODE> objects; the values of the map are arrays of
   * {@link com.silverwrist.dynamo.iface.DataItem DataItem} objects.
   *
   * @return The data item map, as specified above.  This map is read-only.
   */
  public Map getDataItems();

  /**
   * Returns an array of <CODE>Locale</CODE> objects indicating, in decreasing order starting with the preferred
   * locale, the locales that are acceptable to the client based on an <CODE>Accept-Language</CODE> header or similar.
   * method.  If the client request doesn't provide an <CODE>Accept-Language</CODE> header or similar indication,
   * this method returns an array containing one <CODE>Locale</CODE>, the default locale for the server.
   *
   * @return An array of preferred <CODE>Locale</CODE> objects for the client.
   */
  public Locale[] getLocales();

} // end interface Request
