home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 September / PCWorld_2000-09_cd.bin / Komunik / sambar / _setup.1 / javaeng.jar / javax / servlet / ServletRequest.java < prev    next >
Text File  |  2000-04-03  |  8KB  |  300 lines
  1. /*
  2.  * ServletRequest.java -- Holds servlets request data
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20.  
  21. package javax.servlet;
  22.  
  23. import java.io.BufferedReader;
  24. import java.io.IOException;
  25. import java.util.Enumeration;
  26.  
  27. /**
  28.  * Whenever the server receives a request it creates a ServletRequest object,
  29.  * puts all the request information in it and passes this along with
  30.  * a ServletResponse object to the approriate servlet.
  31.  *
  32. #ifdef SERVLET_2_0
  33.  * @version Servlet API 2.0 
  34. #endif
  35. #ifdef SERVLET_2_1
  36.  * @version Servlet API 2.1
  37. #endif
  38. #ifdef SERVLET_2_2
  39.  * @version Servlet API 2.2
  40. #endif
  41.  * @since Servlet API 1.0
  42.  * @author Paul Siegmann (pauls@euronet.nl)
  43.  */
  44. public interface ServletRequest
  45. {
  46.  
  47.     /**
  48.      * Gets the size in bytes of the request
  49.      *
  50.      * @since Servlet API 1.0
  51.      *
  52.      * @return the number of bytes in the request
  53.      * or -1 if not known
  54.      */
  55.     int getContentLength();
  56.  
  57.     /**
  58.      * Gets the mime type of the request
  59.      *
  60.      * @since Servlet API 1.0
  61.      *
  62.      * @return a String containing the mime type of the request
  63.      * or null if not known
  64.      */
  65.     String getContentType();
  66.  
  67.     /**
  68.      * Gets the protocol of the request as Proto/Major.Minor
  69.      * ("HTTP/1.1").
  70.      *
  71.      * @since Servlet API 1.0
  72.      *
  73.      * @return A string containing the protocol name
  74.      */
  75.     String getProtocol();
  76.  
  77.  
  78.     /**
  79.      * Gets the scheme of the request as defined by RFC 1783
  80.      * ("ftp", "http", "gopher", "news").
  81.      *
  82.      * @since Servlet API 1.0
  83.      *
  84.      * @return A String containing the scheme
  85.      */
  86.     String getScheme();
  87.  
  88.     /**
  89.      * Get the name of the server receiving the request
  90.      *
  91.      * @since Servlet API 1.0
  92.      *
  93.      * @return The name of the server.
  94.      */
  95.     String getServerName();
  96.  
  97.     /**
  98.      * Gets the portnumber the server reveiving the request is running on.
  99.      *
  100.      * @since Servlet API 1.0
  101.      *
  102.      * @return the portnumber
  103.      */
  104.     int getServerPort();
  105.  
  106.     /**
  107.      * Gets the ip address of the client that sent the request
  108.      *
  109.      * @since Servlet API 1.0
  110.      *
  111.      * @return the client's ip address
  112.      */
  113.     String getRemoteAddr();
  114.  
  115.     /**
  116.      * Gets the hostname of the client that sent the request.
  117.      * This is either a fully qualified host name or a string representing
  118.      * the remote IP address.
  119.      *
  120.      * @since Servlet API 1.0
  121.      *
  122.      * @return the client's hostname
  123.      */
  124.     String getRemoteHost();
  125.  
  126.  
  127.     /**
  128.      * Translates the given path to the real path on the servers
  129.      * filesystem, using the servers documentroot.
  130.      *
  131. #ifdef SERVLET_2_0
  132. #else
  133.      * @deprecated Should use getRealPath from the current ServletContext.
  134.      * @see javax.servlet.ServletContext#getRealPath(java.lang.String)
  135.      *
  136. #endif
  137.      * @since Servlet API 1.0
  138.      *
  139.      * @param path the path which requires translating
  140.      * @return the translated path
  141.      */
  142.     String getRealPath(String path);
  143.  
  144.     /**
  145.      * Creates an inputstream for servlets to read client request data from.
  146.      * @see javax.servlet.ServletRequest#getReader()
  147.      *
  148.      * @since Servlet API 1.0
  149.      *
  150.      * @return The created InputStreams
  151.      * @exception IOException if an i/o related error occured
  152.      * @exception IllegalStateException if <code>getReader</code> was already
  153.      * called on this request.
  154.      */
  155.     ServletInputStream getInputStream() throws IOException;
  156.  
  157.     /**
  158.      * Gets the value of a named requestparameter.
  159.      * If the parameter can have more than one value
  160.      * <code>getParameterValues</code> should be used.
  161.      * If there are more than one values associated with the parameter this
  162.      * method will only return the first value as return by
  163.      * <code>getParameterValues</code> is returned.
  164.      * see javax.servlet.ServletRequest.getParameterValues()
  165.      *
  166. #ifdef SERVLET_2_0
  167.      * @deprecated But undepricated in Servlet API 2.1!
  168. #endif
  169.      * @since Servlet API 1.0
  170.      *
  171.      * @param name the name of the parameter whose value we want
  172.      * @return the (first) value of the parameter or null if not present
  173.      */
  174.     String getParameter(String name);
  175.  
  176.     /**
  177.      * Gets an array of Strings containing all the request parameter's
  178.      * values whose name matches <CODE>name</CODE>.
  179.      *
  180.      * @since Servlet API 1.0
  181.      *
  182.      * @return the array containing all the values or null if not present
  183.      */
  184.     String[] getParameterValues(String name);
  185.  
  186.     /**
  187.      * Gets all parameter names.
  188.      * <p>
  189.      * Note that the Servlet API 2.1 documentation says that this returns
  190.      * an empty Enumeration if the input stream is empty, but this is not
  191.      * mandated by the Servlet Spec.
  192.      *
  193.      * @since Servlet API 1.0
  194.      *
  195.      * @return an enumeration containing all parameter names
  196.      */
  197.     Enumeration getParameterNames();
  198.  
  199.  
  200.     /**
  201.      * Gets a named attribute's value.
  202.      * This gives one of the initialization attribute values.
  203.      * <p>
  204.      * Note that the Servlet 2.1 API Documentation mentions some predefined
  205.      * attribute names, but the Servlet Spec does not mention them.
  206.      * I (MJW) am not sure if they are platform specific (JWS) or not.
  207.      *
  208.      * @since Servlet API 1.0
  209.      *
  210.      * @return The value of the attribute, null if not found.
  211.      */
  212.     Object getAttribute(String name);
  213.  
  214.  
  215. #ifdef SERVLET_2_0
  216. #else
  217.     /**
  218.      * Puts a named object into the <code>ServletRequest</code>.
  219.      * Can be used to communicate with other servlets if this
  220.      * <code>ServletRequest</code> is passed to another servlet through a
  221.      * <code>RequestDispatcher</code>.
  222.      * The names used must follow the conventions used for naming java
  223.      * packages.
  224.      *
  225.      * @since Servlet API 2.1
  226.      *
  227.      * @see javax.servlet.ServletRequest#getAttribute(java.lang.String)
  228.      * @see javax.servlet.RequestDispatcher
  229.      *
  230.      * @param name - which is used to refer to this object
  231.      * @param object - which should be returned when somebody calls
  232.      * <code>getAttribute(name)</code>
  233.      */
  234.     void setAttribute(String name, Object o);
  235.  
  236.     /**
  237.      * Gets an Enumeration of all the attribute names.
  238.      *
  239.      * @since Servlet API 2.1
  240.      *
  241.      * @return The Enumeration of all attribute names set in this request.
  242.      */
  243.     Enumeration getAttributeNames();
  244. #endif
  245.  
  246. #ifdef SERVLET_2_2
  247.     
  248.     /**
  249.      * XXX
  250.      */
  251.     Locale getLocale();
  252.  
  253.  
  254.     /**
  255.      * XXX
  256.      */
  257.     Enumeration getLocales();
  258.  
  259. #endif
  260.     /**
  261.      * Creates an BufferedReader for servlets to read client request
  262.      * data from.
  263.      * @see javax.servlet.ServletRequest#getInputStream()
  264.      *
  265.      * @since Servlet API 2.0
  266.      *
  267.      * @return The created BufferedReader
  268.      * @exception IOException if an i/o related error occured
  269.      * @exception IllegalStateException if <code>getInputStream</code> was
  270.      * already called on this request.
  271.      */
  272.     BufferedReader getReader() throws IOException;
  273.  
  274.  
  275.     /**
  276.      * Gets the character encoding of the request data.
  277.      *
  278.      * @since Servlet API 2.0
  279.      *
  280.      * @return Character encoding or null if the encoding is unavailable
  281.      */
  282.     String getCharacterEncoding();
  283.  
  284. #ifdef SERVLET_2_2
  285.  
  286.     /**
  287.      * XXX
  288.      */
  289.     boolean isSecure();
  290.  
  291.  
  292.     /**
  293.      * XXX
  294.      */
  295.      RequestDispatcher getRequestDispatcher(String path);
  296. #endif
  297. }
  298.  
  299.  
  300.