HttpServletRequestCompat.java

/*
 * $Source$
 * $Revision$
 *
 * Copyright (C) 2001 William Chesters
 *
 * Part of Melati (http://melati.org), a framework for the rapid
 * development of clean, maintainable web applications.
 *
 * Melati is free software; Permission is granted to copy, distribute
 * and/or modify this software under the terms either:
 *
 * a) the GNU General Public License as published by the Free Software
 *    Foundation; either version 2 of the License, or (at your option)
 *    any later version,
 *
 *    or
 *
 * b) any version of the Melati Software License, as published
 *    at http://melati.org
 *
 * You should have received a copy of the GNU General Public License and
 * the Melati Software License along with this program;
 * if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
 * GNU General Public License and visit http://melati.org to obtain the
 * Melati Software License.
 *
 * Feel free to contact the Developers of Melati (http://melati.org),
 * if you would like to work out a different arrangement than the options
 * outlined here.  It is our intention to allow Melati to be used by as
 * wide an audience as possible.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * Contact details for copyright holder:
 *
 *     William Chesters <williamc At paneris.org>
 *     http://paneris.org/~williamc
 *     Obrechtstraat 114, 2517VX Den Haag, The Netherlands
 */

package org.melati.util;

import java.util.Map;
import java.util.Enumeration;
import java.util.Locale;
import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpSession;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.Cookie;
import java.lang.reflect.Method;
import java.lang.reflect.InvocationTargetException;

/**
 * NOTE This is no longer used, but it is so cool it is still around to marvel at
 * 
 * The <code>HttpServletRequestCompat</code> class enables Melati to compile,
 * without warnings, with the Servlet API versions 2.0 to 2.5.
 * 
 * The core methods are those present in the 2.0 API all methods added since 
 * are established as static members. 
 * These are then available to be invoked if present or a RuntimeException is thrown
 * otherwise.
 * 
 * However, if you use a method which is not in your version of the API then you
 * will get a runtime exception.
 * 
 * @see org.melati.util.DelegatedHttpServletRequest
 */

public final class HttpServletRequestCompat {

  private HttpServletRequestCompat() {
  }

  /** Deprecated in Servlet 2.1 API. */
  private static Method isRequestedSessionIdFromUrl, getRealPath;

  /** New in Servlet 2.2 API. */
  private static Method getUserPrincipal, getContextPath, getHeaders,
      getSession, isRequestedSessionIdFromURL, isUserInRole, getAttributeNames,
      getLocale, getLocales, getRequestDispatcher, isSecure, removeAttribute,
      setAttribute;
  /** New in Servlet 2.3 API. */
  private static Method getRequestURL, setCharacterEncoding, getParameterMap;
  /** New in Servlet 2.4 API. */
  private static Method getLocalAddr, getLocalName, getLocalPort, getRemotePort;
  
  private static Method methodOrNull(Class<?> c, String n, String[] pn) {
    try {
      Class<?>[] p = new Class[pn.length];
      for (int i = 0; i < pn.length; ++i)
        p[i] = Class.forName(pn[i]);
      return c.getMethod(n, p);
    } catch (NoSuchMethodException e) {
      return null;
    } catch (ClassNotFoundException e) {
      return null;
    }
  }

  static {
    try {
      String[] noparams = {};

      Class<?> hsr = Class.forName("javax.servlet.http.HttpServletRequest");
      getUserPrincipal = methodOrNull(hsr, "getUserPrincipal", noparams);
      getContextPath = methodOrNull(hsr, "getContextPath", noparams);
      getHeaders = methodOrNull(hsr, "getHeaders",
          new String[] { "java.lang.String" });
      getSession = methodOrNull(hsr, "getSession", noparams);
      isRequestedSessionIdFromURL = methodOrNull(hsr,
          "isRequestedSessionIdFromURL", noparams);
      isUserInRole = methodOrNull(hsr, "isUserInRole",
          new String[] { "java.lang.String" });
      getAttributeNames = methodOrNull(hsr, "getAttributeNames", noparams);
      getLocale = methodOrNull(hsr, "getLocale", noparams);
      getLocales = methodOrNull(hsr, "getLocales", noparams);
      getRequestDispatcher = methodOrNull(hsr, "getRequestDispatcher",
          new String[] { "java.lang.String" });
      isSecure = methodOrNull(hsr, "isSecure", noparams);
      removeAttribute = methodOrNull(hsr, "removeAttribute",
          new String[] { "java.lang.String" });
      setAttribute = methodOrNull(hsr, "setAttribute", new String[] {
          "java.lang.String", "java.lang.Object" });
      
      getLocalAddr = methodOrNull(hsr, "getLocalAddr", noparams);
      getLocalName = methodOrNull(hsr, "getLocalName", noparams);
      getLocalPort = methodOrNull(hsr, "getLocalPort", noparams);
      getRemotePort = methodOrNull(hsr, "getRemotePort", noparams);
      
    } catch (Exception e) {
      e.printStackTrace();
      throw new Error("org.melati.util.servletcompat.HttpServletRequestCompat"
          + "failed to initialize; contact the Melati developers");
    }
  }
  // 
  // ================================
  // Original Servlet API 2.0 methods 
  // ================================
  // 

  /**
   * Returns the name of the authentication scheme used to protect the servlet,
   * for example, "BASIC" or "SSL," or <code>null</code> if the servlet was
   * not protected. <p>Same as the value of the CGI variable AUTH_TYPE.
   * 
   * @param it
   *        the HttpServletRequest
   * @return a <code>String</code> specifying the name of the authentication
   *         scheme, or <code>null</code> if the request was not authenticated
   * @see javax.servlet.http.HttpServletRequest#getAuthType()
   * @since 2.0
   */
  public static String getAuthType(HttpServletRequest it) {
    return it.getAuthType();
  }

  /**
   * Returns an array containing all of the <code>Cookie</code> objects the
   * client sent with this request. This method returns <code>null</code> if
   * no cookies were sent.
   * 
   * @param it
   *        the HttpServletRequest
   * @return an array of all the <code>Cookies</code> included with this
   *         request, or <code>null</code> if the request has no cookies
   * @see javax.servlet.http.HttpServletRequest#getCookies()
   * @since 2.0
   */
  public static Cookie[] getCookies(HttpServletRequest it) {
    return it.getCookies();
  }

  /**
   * Returns the value of the specified request header as a <code>long</code>
   * value that represents a <code>Date</code> object. Use this method with
   * headers that contain dates, such as <code>If-Modified-Since</code>. <p>The
   * date is returned as the number of milliseconds since January 1, 1970 GMT.
   * The header name is case insensitive. <p>If the request did not have a
   * header of the specified name, this method returns -1. If the header can't
   * be converted to a date, the method throws an
   * <code>IllegalArgumentException</code>.
   * 
   * @param it
   *        the HttpServletRequest
   * @return a <code>long</code> value representing the date specified in the
   *         header expressed as the number of milliseconds since January 1,
   *         1970 GMT, or -1 if the named header was not included with the
   *         request
   * @see javax.servlet.http.HttpServletRequest#getDateHeader(String)
   * @since 2.0
   */
  public static long getDateHeader(HttpServletRequest it, String a) {
    return it.getDateHeader(a);
  }

  /**
   * Returns the value of the specified request header as a <code>String</code>.
   * If the request did not include a header of the specified name, this method
   * returns <code>null</code>. The header name is case insensitive. You can
   * use this method with any request header.
   * 
   * @param it
   *        the HttpServletRequest
   * @return a <code>String</code> containing the value of the requested
   *         header, or <code>null</code> if the request does not have a
   *         header of that name
   * @see javax.servlet.http.HttpServletRequest#getHeader(String)
   * @since 2.0
   */
  public static String getHeader(HttpServletRequest it, String a) {
    return it.getHeader(a);
  }

  /**
   * Returns an enumeration of all the header names this request contains. If
   * the request has no headers, this method returns an empty enumeration. <p>Some
   * servlet containers do not allow do not allow servlets to access headers
   * using this method, in which case this method returns <code>null</code>
   * 
   * @param it
   *        the HttpServletRequest
   * @return an enumeration of all the header names sent with this request; if
   *         the request has no headers, an empty enumeration; if the servlet
   *         container does not allow servlets to use this method,
   *         <code>null</code>
   * @see javax.servlet.http.HttpServletRequest#getHeaderNames()
   * @since 2.0
   */
  @SuppressWarnings("unchecked")
  public static Enumeration<String> getHeaderNames(HttpServletRequest it) {
    return it.getHeaderNames();
  }

  /**
   * Returns the value of the specified request header as an <code>int</code>.
   * If the request does not have a header of the specified name, this method
   * returns -1. If the header cannot be converted to an integer, this method
   * throws a <code>NumberFormatException</code>. <p>The header name is case
   * insensitive.
   * 
   * @param it
   *        the HttpServletRequest
   * @return an integer expressing the value of the request header or -1 if the
   *         request doesn't have a header of this name
   * @see javax.servlet.http.HttpServletRequest#getIntHeader(String)
   * @since 2.0
   */
  public static int getIntHeader(HttpServletRequest it, String a) {
    return it.getIntHeader(a);
  }

  /**
   * @param it the HttpServletRequest
   * @return      a <code>String</code> 
   *        specifying the name
   *        of the method with which
   *        this request was made
   * @see javax.servlet.http.HttpServletRequest#getMethod()
   * @since 2.0
   */
  public static String getMethod(HttpServletRequest it) {
    return it.getMethod();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> specifying 
   *      extra path information that comes
   *      after the servlet path but before
   *      the query string in the request URL;
   *      or <code>null</code> if the URL does not have
   *      any extra path information
   * @see javax.servlet.http.HttpServletRequest#getPathInfo()
   * @since 2.0
   */
  public static String getPathInfo(HttpServletRequest it) {
    return it.getPathInfo();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> specifying the
   *      real path, or <code>null</code> if
   *      the URL does not have any extra path
   *      information
   * @see javax.servlet.http.HttpServletRequest#getPathTranslated()
   * @since 2.0
   */
  public static String getPathTranslated(HttpServletRequest it) {
    return it.getPathTranslated();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> containing the query
   *      string or <code>null</code> if the URL 
   *      contains no query string
   * @see javax.servlet.http.HttpServletRequest#getQueryString()
   * @since 2.0
   */
  public static String getQueryString(HttpServletRequest it) {
    return it.getQueryString();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> specifying the login
   *      of the user making this request, or <code>null</code>
   *      if the user login is not known
   * @see javax.servlet.http.HttpServletRequest#getRemoteUser()
   * @since 2.0
   */
  public static String getRemoteUser(HttpServletRequest it) {
    return it.getRemoteUser();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> containing
   *      the part of the URL from the 
   *      protocol name up to the query string
   * @see javax.servlet.http.HttpServletRequest#getRequestURI()
   * @since 2.0
   */
  public static String getRequestURI(HttpServletRequest it) {
    return it.getRequestURI();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> specifying the session
   *      ID, or <code>null</code> if the request did
   *      not specify a session ID
   * @see javax.servlet.http.HttpServletRequest#getRequestedSessionId()
   * @since 2.0
   */
  public static String getRequestedSessionId(HttpServletRequest it) {
    return it.getRequestedSessionId();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return    a <code>String</code> containing
   *      the name or path of the servlet being
   *      called, as specified in the request URL 
   * @see javax.servlet.http.HttpServletRequest#getServletPath()
   * @since 2.0
   */
  public static String getServletPath(HttpServletRequest it) {
    return it.getServletPath();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @param a
   * @return    the <code>HttpSession</code> associated
   *      with this request
   * @see javax.servlet.http.HttpServletRequest#getSession()
   * @since 2.0
   */
  public static HttpSession getSession(HttpServletRequest it, boolean a) {
    return it.getSession(a);
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return      <code>true</code> if this
   *        request has an id for a valid session
   *        in the current session context;
   *        <code>false</code> otherwise
   * @see javax.servlet.http.HttpServletRequest#isRequestedSessionIdValid()
   * @since 2.0
   */
  public static boolean isRequestedSessionIdValid(HttpServletRequest it) {
    return it.isRequestedSessionIdValid();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return      <code>true</code> if the session ID
   *        came in as a
   *        cookie; otherwise, <code>false</code>
   * @see javax.servlet.http.HttpServletRequest#isRequestedSessionIdFromCookie()
   * @since 2.0
   */
  public static boolean isRequestedSessionIdFromCookie(HttpServletRequest it) {
    return it.isRequestedSessionIdFromCookie();
  }
  
  //======================
  // Invocation machinery
  //======================
  
  /**
   * Thrown when a method that is not available is invoked.
   */
  public static class MissingMethodError extends NoSuchMethodError {
    private static final long serialVersionUID = 1L;

    /**
     * {@inheritDoc}
     * 
     * @see java.lang.Throwable#getMessage()
     */
    public String getMessage() {
      return "The application tried to use a method from the "
          + "Servlet API which is not present in the version it running against.";
    }
  }

  private static Object invoke(Method method, HttpServletRequest it,
      Object[] args) {
    if (method == null)
      throw new MissingMethodError();
    else {
      try {
        return method.invoke(it, args);
      } catch (InvocationTargetException e) {
        Throwable f = e.getTargetException();
        if (f instanceof RuntimeException) // they all should be
          throw (RuntimeException)f;
        else if (f instanceof Exception)
          throw new RuntimeException("while invoking a Servlet API method",
                                     f);
        else if (f instanceof Error)
          throw (Error)f;
        else {
          f.printStackTrace();
          throw new Error("totally unexpected kind of throwable in "
              + "org.melati.util.servletcompat.HttpServletRequestCompat");
        }
      } catch (IllegalAccessException e) {
        e.printStackTrace();
        throw new Error(
                        "org.melati.util.servletcompat.HttpServletRequestCompat"
                            + "got an unexpected IllegalAccessException trying to "
                            + "invoke a method; contact the Melati developers");
      }
    }
  }

  private static final Object[] noargs = {};

  // 
  // ============================
  // Servlet API 2.1 deprecatons
  // ============================
  // 

  /**
   * @param it
   *        the HttpServletRequest
   * @param arg
   *        url String
   * @return the real path
   * @deprecated Servlet API 2.1
   * @see javax.servlet.ServletRequest#getRealPath(String)
   * @since 2.0
   */
  public static String getRealPath(HttpServletRequest it, String arg) {
    return (String)invoke(getRealPath, it, new Object[] { arg });
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return whether id is from url
   * @deprecated Servlet API 2.1 
   * @see javax.servlet.http.HttpServletRequest#isRequestedSessionIdFromUrl()
   * @since 2.0
   */
  public static boolean isRequestedSessionIdFromUrl(HttpServletRequest it) {
    return ((Boolean)invoke(isRequestedSessionIdFromUrl, it, noargs))
        .booleanValue();
  }

  // 
  // ============================
  // Servlet API 2.1 extensions
  // ============================
  // 

  /**
   * Returns the empty string when run against 2.0 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @return the Context path or empty string
   * @see javax.servlet.http.HttpServletRequest#getContextPath()
   * @since 2.1
   */
  public static String getContextPath(HttpServletRequest it) {
    if (getContextPath == null)
      return "";
    else
      return (String)invoke(getContextPath, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @return    a <code>java.security.Principal</code> containing
   *      the name of the user making this request;
   *      <code>null</code> if the user has not been 
   *      authenticated
   * @see javax.servlet.http.HttpServletRequest#getUserPrincipal()
   * @since 2.1
   */
  public static java.security.Principal getUserPrincipal(HttpServletRequest it) {
    return (java.security.Principal)invoke(getUserPrincipal, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg
   * @return      a <code>Enumeration</code> containing the
   *        values of the requested
   *        header, or <code>null</code>
   *        if the request does not
   *        have any headers of that name
   * @see javax.servlet.http.HttpServletRequest#getHeaders(java.lang.String)
   * @since 2.1
   */
  @SuppressWarnings("unchecked")
  public static Enumeration<String> getHeaders(HttpServletRequest it, String arg) {
    return (Enumeration<String>)invoke(getHeaders, it, new Object[] { arg });
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API, 
   * introduced in 2.1.
   * 
   * @param it
   *        the HttpServletRequest
   * @return    the <code>HttpSession</code> associated
   *      with this request
   * @see javax.servlet.http.HttpServletRequest#getSession()
   * @since 2.1
   */
  public static HttpSession getSession(HttpServletRequest it) {
    return (HttpSession)invoke(getSession, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API, 
   * introduced in 2.1.
   * 
   * @param it
   *        the HttpServletRequest
   * @return      <code>true</code> if the session ID
   *        came in as part of a URL; otherwise,
   *        <code>false</code>
   * @see javax.servlet.http.HttpServletRequest#isRequestedSessionIdFromURL()
   * @since 2.1
   */
  public static boolean isRequestedSessionIdFromURL(HttpServletRequest it) {
    return ((Boolean)invoke(isRequestedSessionIdFromURL, it, noargs))
        .booleanValue();
  }

  // 
  // ============================
  // Servlet API 2.2 extensions
  // ============================
  // 

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg
   * @return    a <code>boolean</code> indicating whether
   *      the user making this request belongs to a given role;
   *      <code>false</code> if the user has not been 
   *      authenticated
   * @see javax.servlet.http.HttpServletRequest#isUserInRole(java.lang.String)
   * @since 2.2
   */
  public static boolean isUserInRole(HttpServletRequest it, String arg) {
    return ((Boolean)invoke(isUserInRole, it, new Object[] { arg }))
        .booleanValue();
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Returns an
   * <code>Enumeration</code> containing the names of the attributes available
   * to this request. This method returns an empty <code>Enumeration</code> if
   * the request has no attributes available to it.
   * 
   * @param it
   *        the HttpServletRequest
   * @return an <code>Enumeration</code> of strings containing the names of
   *         the request's attributes
   * @see javax.servlet.http.HttpServletRequest#getAttributeNames()
   * @since 2.2
   */
  @SuppressWarnings("unchecked")
public static Enumeration<String> getAttributeNames(HttpServletRequest it) {
    return (Enumeration<String>)invoke(getAttributeNames, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Returns the
   * preferred <code>Locale</code> that the client will accept content in,
   * based on the Accept-Language header. If the client request doesn't provide
   * an Accept-Language header, this method returns the default locale for the
   * server.
   * 
   * @param it
   *        the HttpServletRequest
   * @return the preferred <code>Locale</code> for the client
   * @see javax.servlet.http.HttpServletRequest#getLocale()
   * @since 2.2
   */
  public static Locale getLocale(HttpServletRequest it) {
    return (Locale)invoke(getLocale, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Returns an
   * <code>Enumeration</code> of <code>Locale</code> objects indicating, in
   * decreasing order starting with the preferred locale, the locales that are
   * acceptable to the client based on the Accept-Language header. If the client
   * request doesn't provide an Accept-Language header, this method returns an
   * <code>Enumeration</code> containing one <code>Locale</code>, the
   * default locale for the server.
   * 
   * @param it
   *        the HttpServletRequest
   * @return an <code>Enumeration</code> of preferred <code>Locale</code>
   *         objects for the client
   * @see javax.servlet.http.HttpServletRequest#getLocales()
   * @since 2.2
   */
  @SuppressWarnings("unchecked")
  public static Enumeration<String> getLocales(HttpServletRequest it) {
    return (Enumeration<String>)invoke(getLocales, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. If you get
   * compile errors for this method, it's probably because (a) you are compiling
   * against the 2.0 servlet API.
   * 
   * Returns a {@link RequestDispatcher} object that acts as a wrapper for the
   * resource located at the given path. A <code>RequestDispatcher</code>
   * object can be used to forward a request to the resource or to include the
   * resource in a response. The resource can be dynamic or static. 
   * 
   * The
   * pathname specified may be relative, although it cannot extend outside the
   * current servlet context. If the path begins with a "/" it is interpreted as
   * relative to the current context root. This method returns <code>null</code>
   * if the servlet container cannot return a <code>RequestDispatcher</code>.
   * 
   * The difference between this method and 
   * {@link javax.servlet.ServletContext#getRequestDispatcher} is that this method can take a
   * relative path.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg
   *        a <code>String</code> specifying the pathname to the resource
   * @return a <code>RequestDispatcher</code> object that acts as a wrapper
   *         for the resource at the specified path
   * @see RequestDispatcher
   * @see javax.servlet.http.HttpServletRequest#getRequestDispatcher(String)
   * @since 2.2
   */
  public static RequestDispatcher getRequestDispatcher(HttpServletRequest it,
      String arg) {
    return (RequestDispatcher)invoke(getRequestDispatcher, it,
        new Object[] { arg });
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Returns a
   * boolean indicating whether this request was made using a secure channel,
   * such as HTTPS.
   * 
   * @param it
   *        the HttpServletRequest
   * @return a boolean indicating if the request was made using a secure channel
   * @see javax.servlet.http.HttpServletRequest#isSecure()
   * @since 2.2
   */
  public static boolean isSecure(HttpServletRequest it) {
    return ((Boolean)invoke(isSecure, it, noargs)).booleanValue();
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Removes an
   * attribute from this request. This method is not generally needed as
   * attributes only persist as long as the request is being handled. <p>Attribute
   * names should follow the same conventions as package names. Names beginning
   * with <code>java.*</code>, <code>javax.*</code>, and
   * <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg
   *        a <code>String</code> specifying the name of the attribute to
   *        remove
   * @see javax.servlet.http.HttpServletRequest#removeAttribute
   * @since 2.2
   */
  public static void removeAttribute(HttpServletRequest it, String arg) {
    invoke(removeAttribute, it, new Object[] { arg });
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.0 API. Stores an
   * attribute in this request. Attributes are reset between requests. This
   * method is most often used in conjunction with {@link RequestDispatcher}.
   * <p>Attribute names should follow the same conventions as package names.
   * Names beginning with <code>java.*</code>, <code>javax.*</code>, and
   * <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg1
   *        a <code>String</code> specifying the name of the attribute
   * @param arg2
   *        the <code>Object</code> to be stored
   * @see javax.servlet.http.HttpServletRequest#setAttribute
   * @since 2.2
   */
  public static void setAttribute(HttpServletRequest it, String arg1,
      Object arg2) {
    invoke(setAttribute, it, new Object[] { arg1, arg2 });
  }

  // 
  // ============================
  // Servlet API 2.3 extensions
  // ============================
  // 

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.2 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @return request url as a String buffer
   * @see javax.servlet.http.HttpServletRequest#getRequestURL()
   * @since 2.3
   */
  public static StringBuffer getRequestURL(HttpServletRequest it) {
    return (StringBuffer)invoke(getRequestURL, it, noargs);
  }

  /**
   * Throws <TT>MissingMethodError</TT> when run against 2.2 API.
   * 
   * @param it
   *        the HttpServletRequest
   * @param arg
   *        encoding name
   * @see javax.servlet.http.HttpServletRequest#setCharacterEncoding(String)
   * @since 2.3
   */
  public static void setCharacterEncoding(HttpServletRequest it, String arg) {
    invoke(setCharacterEncoding, it, new Object[] { arg });
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return map of parameters
   * @see javax.servlet.http.HttpServletRequest#getParameterMap()
   * @since 2.3
   */
  @SuppressWarnings("unchecked")
  public static Map<String, String[]> getParameterMap(HttpServletRequest it) {
    return (Map<String, String[]>)invoke(getParameterMap, it, noargs);
  }


  // 
  // ============================
  // Servlet API 2.4 extensions
  // ============================
  // 

  /**
   * @param it
   *        the HttpServletRequest
   * @return the remote address
   * @see javax.servlet.http.HttpServletRequest#getRemotePort()
   */
  public static int getRemotePort(HttpServletRequest it) {
    return ((Integer)invoke(getRemotePort, it, noargs)).intValue();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return the receiving local port
   * @see javax.servlet.http.HttpServletRequest#getLocalPort()
   */
  public static int getLocalPort(HttpServletRequest it) {
    return ((Integer)invoke(getLocalPort, it, noargs)).intValue();
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return the local host name
   * @see javax.servlet.http.HttpServletRequest#getLocalName()
   */
  public static String getLocalName(HttpServletRequest it) {
    return (String)invoke(getLocalName, it, noargs);    
  }

  /**
   * @param it
   *        the HttpServletRequest
   * @return the receiving, local, IP address
   * @see javax.servlet.http.HttpServletRequest#getLocalAddr()
   */
  public static String getLocalAddr(HttpServletRequest it) {
    return (String)invoke(getLocalAddr, it, noargs);
  }

}