/*
 * 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.servlet;

import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
import com.silverwrist.dynamo.RequestType;
import com.silverwrist.dynamo.Verb;
import com.silverwrist.dynamo.except.*;
import com.silverwrist.dynamo.iface.*;
import com.silverwrist.dynamo.util.*;

/**
 * The base class for standard HTTP requests.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
abstract class RequestImplBase extends BaseDelegatingServiceProvider implements Request
{
  /*--------------------------------------------------------------------------------
   * Static data members
   *--------------------------------------------------------------------------------
   */

  private static final String CONTEXT = "Servlet RequestImpl";

  private static final Locale[] LOCALE_TEMPLATE = new Locale[0];

  /*--------------------------------------------------------------------------------
   * Attributes
   *--------------------------------------------------------------------------------
   */

  /**
   * The <CODE>HttpServletRequest</CODE> encapsulated by this object.
   */
  protected HttpServletRequest m_req;

  private Verb m_verb;                  // the verb
  private Locale[] m_locales;           // the locales array
  private MemoryObjectStore m_attrs;    // request attributes

  /*--------------------------------------------------------------------------------
   * Constructor
   *--------------------------------------------------------------------------------
   */

  /**
   * Creates a new <CODE>RequestImplBase</CODE>.
   *
   * @param req The original <CODE>HttpServletRequest</CODE> passed to the servlet.
   * @param verb The verb associated with this request.
   * @param services A {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} object controlling
   *                 access to request services.
   * @param prev The previous {@link com.silverwrist.dynamo.iface.Request Request} object.  May be <CODE>null</CODE>.
   */
  protected RequestImplBase(HttpServletRequest req, Verb verb, ServiceProvider services, Request prev)
  {
    super(CONTEXT,services);
    m_req = req;
    m_verb = verb;

    ArrayList tmp = new ArrayList();
    Enumeration enum = req.getLocales();
    while (enum.hasMoreElements())
      tmp.add(enum.nextElement());
    m_locales = (Locale[])(tmp.toArray(LOCALE_TEMPLATE));
    m_attrs = new MemoryObjectStore(RequestImplBase.class.getName(),prev);

  } // end constructor

  /*--------------------------------------------------------------------------------
   * Implementations from interface ObjectProvider
   *--------------------------------------------------------------------------------
   */

  /**
   * Retrieves an object from this <CODE>ObjectProvider</CODE>.
   *
   * @param namespace The namespace to interpret the name relative to.
   * @param name The name of the object to be retrieved.
   * @return The object reference specified.
   */
  public Object getObject(String namespace, String name)
  {
    return m_attrs.getObject(namespace,name);

  } // end getObject

  /*--------------------------------------------------------------------------------
   * Implementations from interface ObjectStore
   *--------------------------------------------------------------------------------
   */

  /**
   * Sets an object into this <CODE>ObjectStore</CODE>.
   *
   * @param namespace The namespace to interpret the name relative to.
   * @param name The name of the object to be set.
   * @param value The object to set into the <CODE>ObjectStore</CODE>.
   * @return The previous object that was set into the <CODE>ObjectStore</CODE> under this namespace and name, or
   *         <CODE>null</CODE> if there was no such object.
   */
  public Object setObject(String namespace, String name, Object value)
  {
    return m_attrs.setObject(namespace,name,value);

  } // end setObject

  /**
   * Removes an object from this <CODE>ObjectStore</CODE>.
   *
   * @param namespace The namespace to interpret the name relative to.
   * @param name The name of the object to be removed.
   * @return The previous object that was set into the <CODE>ObjectStore</CODE> under this namespace and name, or
   *         <CODE>null</CODE> if there was no such object.
   */
  public Object removeObject(String namespace, String name)
  {
    return m_attrs.removeObject(namespace,name);

  } // end removeObject

  /**
   * Returns a collection of all object namespaces that have been set into this <CODE>ObjectStore</CODE>.
   *
   * @return A <CODE>java.util.Collection</CODE> containing <CODE>String</CODE> objects specifying all the
   *         object namespaces.
   */
  public Collection getNamespaces()
  {
    return m_attrs.getNamespaces();

  } // end getNamespaces

  /**
   * Returns a collection of all object names that have been set into this <CODE>ObjectStore</CODE> under a given
   * namespace.
   *
   * @param namespace The namespace to look for names under.
   * @return A <CODE>java.util.Collection</CODE> containing <CODE>String</CODE> objects specifying all the
   *         object names for this namespace.
   */
  public Collection getNamesForNamespace(String namespace)
  {
    return m_attrs.getNamesForNamespace(namespace);

  } // end getNamesForNamespace

  /*--------------------------------------------------------------------------------
   * Implementations from interface Request
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns a value indicating the type of this request.
   *
   * @return The type of this request.
   * @see com.silverwrist.dynamo.RequestType#HTTP
   */
  public RequestType getType()
  {
    return RequestType.HTTP;

  } // end 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()
  {
    return m_req.getServerName();

  } // end 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()
  {
    return m_req.getServerPort();

  } // end 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()
  {
    return m_req.getContextPath();

  } // end 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()
  {
    return m_req.getServletPath();

  } // end 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()
  {
    return m_req.getPathInfo();

  } // end 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.
   *
   * @return The query string associated with this request.  If there is no query string, returns <CODE>null</CODE>.
   */
  public String getQueryString()
  {
    return m_req.getQueryString();

  } // end 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()
  {
    return m_verb;

  } // end 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()
  {
    return m_req.getRemoteAddr();

  } // end getSourceAddress

  /**
   * 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()
  {
    return m_locales;

  } // end getLocales

  /*--------------------------------------------------------------------------------
   * Abstract methods from interface Request
   *--------------------------------------------------------------------------------
   */

  /**
   * 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.
   * <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()}.
   *
   * @return The parameter map, as specified above.  This map is read-only.
   */
  public abstract 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 abstract 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.  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 abstract Map getDataItems();

} // end class RequestImplBase
