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

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

/**
 * Provides a convenient implementation of the {@link com.silverwrist.dynamo.iface.Request Request} interface
 * that can be subclassed by developers wishing to adapt the request object.  This class implements the Wrapper,
 * or Decorator, pattern.  The default implementation of its methods call the wrapped <CODE>Request</CODE> object.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public class FilterRequest implements Request
{
  /*--------------------------------------------------------------------------------
   * Attributes
   *--------------------------------------------------------------------------------
   */

  private Request m_inner;     // the Request that gets wrapped

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

  /**
   * Creates a new <CODE>FilterRequest</CODE> object.
   *
   * @param inner The {@link com.silverwrist.dynamo.iface.Request Request} to be wrapped by this object.
   */
  public FilterRequest(Request inner)
  {
    m_inner = inner;

  } // end constructor

  /*--------------------------------------------------------------------------------
   * Overrides from class Object
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns a string representation of the object. In general, the <CODE>toString</CODE> method returns a string
   * that "textually represents" this object. 
   *
   * @return A string representation of the object.
   */
  public String toString()
  {
    return "FilterRequest of class " + getClass().getName() + ", wrapping " + m_inner.toString();

  } // end toString

  /*--------------------------------------------------------------------------------
   * Implementations from interface ServiceProvider
   *--------------------------------------------------------------------------------
   */

  /**
   * Queries this object for a specified service.
   *
   * @param klass The class of the object that should be returned as a service.
   * @return A service object.  The service object is guaranteed to be of the class
   *         specified by <CODE>klass</CODE>; that is, if <CODE>queryService(klass)</CODE>
   *         yields some object <CODE>x</CODE>, then the expression <CODE>klass.isInstance(x)</CODE>
   *         is true.
   * @exception com.silverwrist.dynamo.except.NoSuchServiceException If no service is available in
   *            the specified class.
   */
  public Object queryService(Class klass)
  {
    return m_inner.queryService(klass);

  } // end queryService

  /**
   * Queries this object for a specified service.
   *
   * @param klass The class of the object that should be returned as a service.
   * @param serviceid ID for the service to be requested, to further discriminate between requests.
   * @return A service object.  The service object is guaranteed to be of the class
   *         specified by <CODE>klass</CODE>; that is, if <CODE>queryService(klass)</CODE>
   *         yields some object <CODE>x</CODE>, then the expression <CODE>klass.isInstance(x)</CODE>
   *         is true.
   * @exception com.silverwrist.dynamo.except.NoSuchServiceException If no service is available in
   *            the specified class.
   */
  public Object queryService(Class klass, String serviceid)
  {
    return m_inner.queryService(klass,serviceid);

  } // end queryService

  /*--------------------------------------------------------------------------------
   * 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_inner.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_inner.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_inner.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_inner.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_inner.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
   */
  public RequestType getType()
  {
    return m_inner.getType();

  } // 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_inner.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_inner.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_inner.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_inner.getRequestPath();

  } // 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_inner.getExtraPath();

  } // 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.  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()
  {
    return m_inner.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_inner.getVerb();

  } // 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_inner.getSourceAddress();

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

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

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

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

  } // end getLocales

} // end class FilterRequest
