home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 November / PCWorld_2000-11_cd.bin / Komunik / sambar444 / _SETUP.1 / javaeng.jar / javax / servlet / ServletRequest.java < prev    next >
Text File  |  2000-08-09  |  7KB  |  283 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.  * @version Servlet API 2.2
  33.  * @since Servlet API 1.0
  34.  * @author Paul Siegmann (pauls@euronet.nl)
  35.  */
  36. public interface ServletRequest
  37. {
  38.  
  39.     /**
  40.      * Gets the size in bytes of the request
  41.      *
  42.      * @since Servlet API 1.0
  43.      *
  44.      * @return the number of bytes in the request
  45.      * or -1 if not known
  46.      */
  47.     int getContentLength();
  48.  
  49.     /**
  50.      * Gets the mime type of the request
  51.      *
  52.      * @since Servlet API 1.0
  53.      *
  54.      * @return a String containing the mime type of the request
  55.      * or null if not known
  56.      */
  57.     String getContentType();
  58.  
  59.     /**
  60.      * Gets the protocol of the request as Proto/Major.Minor
  61.      * ("HTTP/1.1").
  62.      *
  63.      * @since Servlet API 1.0
  64.      *
  65.      * @return A string containing the protocol name
  66.      */
  67.     String getProtocol();
  68.  
  69.  
  70.     /**
  71.      * Gets the scheme of the request as defined by RFC 1783
  72.      * ("ftp", "http", "gopher", "news").
  73.      *
  74.      * @since Servlet API 1.0
  75.      *
  76.      * @return A String containing the scheme
  77.      */
  78.     String getScheme();
  79.  
  80.     /**
  81.      * Get the name of the server receiving the request
  82.      *
  83.      * @since Servlet API 1.0
  84.      *
  85.      * @return The name of the server.
  86.      */
  87.     String getServerName();
  88.  
  89.     /**
  90.      * Gets the portnumber the server reveiving the request is running on.
  91.      *
  92.      * @since Servlet API 1.0
  93.      *
  94.      * @return the portnumber
  95.      */
  96.     int getServerPort();
  97.  
  98.     /**
  99.      * Gets the ip address of the client that sent the request
  100.      *
  101.      * @since Servlet API 1.0
  102.      *
  103.      * @return the client's ip address
  104.      */
  105.     String getRemoteAddr();
  106.  
  107.     /**
  108.      * Gets the hostname of the client that sent the request.
  109.      * This is either a fully qualified host name or a string representing
  110.      * the remote IP address.
  111.      *
  112.      * @since Servlet API 1.0
  113.      *
  114.      * @return the client's hostname
  115.      */
  116.     String getRemoteHost();
  117.  
  118.  
  119.     /**
  120.      * Translates the given path to the real path on the servers
  121.      * filesystem, using the servers documentroot.
  122.      *
  123.      * @deprecated Should use getRealPath from the current ServletContext.
  124.      * @see javax.servlet.ServletContext#getRealPath(java.lang.String)
  125.      *
  126.      * @since Servlet API 1.0
  127.      *
  128.      * @param path the path which requires translating
  129.      * @return the translated path
  130.      */
  131.     String getRealPath(String path);
  132.  
  133.     /**
  134.      * Creates an inputstream for servlets to read client request data from.
  135.      * @see javax.servlet.ServletRequest#getReader()
  136.      *
  137.      * @since Servlet API 1.0
  138.      *
  139.      * @return The created InputStreams
  140.      * @exception IOException if an i/o related error occured
  141.      * @exception IllegalStateException if <code>getReader</code> was already
  142.      * called on this request.
  143.      */
  144.     ServletInputStream getInputStream() throws IOException;
  145.  
  146.     /**
  147.      * Gets the value of a named requestparameter.
  148.      * If the parameter can have more than one value
  149.      * <code>getParameterValues</code> should be used.
  150.      * If there are more than one values associated with the parameter this
  151.      * method will only return the first value as return by
  152.      * <code>getParameterValues</code> is returned.
  153.      * see javax.servlet.ServletRequest.getParameterValues()
  154.      *
  155.      * @since Servlet API 1.0
  156.      *
  157.      * @param name the name of the parameter whose value we want
  158.      * @return the (first) value of the parameter or null if not present
  159.      */
  160.     String getParameter(String name);
  161.  
  162.     /**
  163.      * Gets an array of Strings containing all the request parameter's
  164.      * values whose name matches <CODE>name</CODE>.
  165.      *
  166.      * @since Servlet API 1.0
  167.      *
  168.      * @return the array containing all the values or null if not present
  169.      */
  170.     String[] getParameterValues(String name);
  171.  
  172.     /**
  173.      * Gets all parameter names.
  174.      * <p>
  175.      * Note that the Servlet API 2.1 documentation says that this returns
  176.      * an empty Enumeration if the input stream is empty, but this is not
  177.      * mandated by the Servlet Spec.
  178.      *
  179.      * @since Servlet API 1.0
  180.      *
  181.      * @return an enumeration containing all parameter names
  182.      */
  183.     Enumeration getParameterNames();
  184.  
  185.  
  186.     /**
  187.      * Gets a named attribute's value.
  188.      * This gives one of the initialization attribute values.
  189.      * <p>
  190.      * Note that the Servlet 2.1 API Documentation mentions some predefined
  191.      * attribute names, but the Servlet Spec does not mention them.
  192.      * I (MJW) am not sure if they are platform specific (JWS) or not.
  193.      *
  194.      * @since Servlet API 1.0
  195.      *
  196.      * @return The value of the attribute, null if not found.
  197.      */
  198.     Object getAttribute(String name);
  199.  
  200.  
  201.     /**
  202.      * Puts a named object into the <code>ServletRequest</code>.
  203.      * Can be used to communicate with other servlets if this
  204.      * <code>ServletRequest</code> is passed to another servlet through a
  205.      * <code>RequestDispatcher</code>.
  206.      * The names used must follow the conventions used for naming java
  207.      * packages.
  208.      *
  209.      * @since Servlet API 2.1
  210.      *
  211.      * @see javax.servlet.ServletRequest#getAttribute(java.lang.String)
  212.      * @see javax.servlet.RequestDispatcher
  213.      *
  214.      * @param name - which is used to refer to this object
  215.      * @param object - which should be returned when somebody calls
  216.      * <code>getAttribute(name)</code>
  217.      */
  218.     void setAttribute(String name, Object o);
  219.  
  220.     /**
  221.      * Gets an Enumeration of all the attribute names.
  222.      *
  223.      * @since Servlet API 2.1
  224.      *
  225.      * @return The Enumeration of all attribute names set in this request.
  226.      */
  227.     Enumeration getAttributeNames();
  228.  
  229.     /**
  230.      * XXX
  231.      */
  232.     void removeAttribute(String name);
  233.  
  234.  
  235.     /**
  236.      * XXX
  237.      */
  238.     java.util.Locale getLocale();
  239.  
  240.  
  241.     /**
  242.      * XXX
  243.      */
  244.     Enumeration getLocales();
  245.  
  246.     /**
  247.      * Creates an BufferedReader for servlets to read client request
  248.      * data from.
  249.      * @see javax.servlet.ServletRequest#getInputStream()
  250.      *
  251.      * @since Servlet API 2.0
  252.      *
  253.      * @return The created BufferedReader
  254.      * @exception IOException if an i/o related error occured
  255.      * @exception IllegalStateException if <code>getInputStream</code> was
  256.      * already called on this request.
  257.      */
  258.     BufferedReader getReader() throws IOException;
  259.  
  260.  
  261.     /**
  262.      * Gets the character encoding of the request data.
  263.      *
  264.      * @since Servlet API 2.0
  265.      *
  266.      * @return Character encoding or null if the encoding is unavailable
  267.      */
  268.     String getCharacterEncoding();
  269.  
  270.     /**
  271.      * XXX
  272.      */
  273.     boolean isSecure();
  274.  
  275.  
  276.     /**
  277.      * XXX
  278.      */
  279.      RequestDispatcher getRequestDispatcher(String path);
  280. }
  281.  
  282.  
  283.