Home » apache-tomcat-6.0.26-src » javax » servlet » http » [javadoc | source]

    1   /*
    2   * Licensed to the Apache Software Foundation (ASF) under one or more
    3   * contributor license agreements.  See the NOTICE file distributed with
    4   * this work for additional information regarding copyright ownership.
    5   * The ASF licenses this file to You under the Apache License, Version 2.0
    6   * (the "License"); you may not use this file except in compliance with
    7   * the License.  You may obtain a copy of the License at
    8   *
    9   *     http://www.apache.org/licenses/LICENSE-2.0
   10   *
   11   * Unless required by applicable law or agreed to in writing, software
   12   * distributed under the License is distributed on an "AS IS" BASIS,
   13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14   * See the License for the specific language governing permissions and
   15   * limitations under the License.
   16   */
   17   package javax.servlet.http;
   18   
   19   import java.io.IOException;
   20   
   21   import javax.servlet.ServletResponse;
   22   
   23   /**
   24    *
   25    * Extends the {@link ServletResponse} interface to provide HTTP-specific
   26    * functionality in sending a response.  For example, it has methods
   27    * to access HTTP headers and cookies.
   28    *
   29    * <p>The servlet container creates an <code>HttpServletResponse</code> object
   30    * and passes it as an argument to the servlet's service methods
   31    * (<code>doGet</code>, <code>doPost</code>, etc).
   32    *
   33    * 
   34    * @author	Various
   35    * @version	$Version$
   36    *
   37    * @see		javax.servlet.ServletResponse
   38    *
   39    */
   40   
   41   
   42   
   43   public interface HttpServletResponse extends ServletResponse {
   44   
   45       /**
   46        * Adds the specified cookie to the response.  This method can be called
   47        * multiple times to set more than one cookie.
   48        *
   49        * @param cookie the Cookie to return to the client
   50        *
   51        */
   52   
   53       public void addCookie(Cookie cookie);
   54   
   55       /**
   56        * Returns a boolean indicating whether the named response header 
   57        * has already been set.
   58        * 
   59        * @param	name	the header name
   60        * @return		<code>true</code> if the named response header 
   61        *			has already been set; 
   62        * 			<code>false</code> otherwise
   63        */
   64   
   65       public boolean containsHeader(String name);
   66   
   67       /**
   68        * Encodes the specified URL by including the session ID in it,
   69        * or, if encoding is not needed, returns the URL unchanged.
   70        * The implementation of this method includes the logic to
   71        * determine whether the session ID needs to be encoded in the URL.
   72        * For example, if the browser supports cookies, or session
   73        * tracking is turned off, URL encoding is unnecessary.
   74        * 
   75        * <p>For robust session tracking, all URLs emitted by a servlet 
   76        * should be run through this
   77        * method.  Otherwise, URL rewriting cannot be used with browsers
   78        * which do not support cookies.
   79        *
   80        * @param	url	the url to be encoded.
   81        * @return		the encoded URL if encoding is needed;
   82        * 			the unchanged URL otherwise.
   83        */
   84   
   85       public String encodeURL(String url);
   86   
   87       /**
   88        * Encodes the specified URL for use in the
   89        * <code>sendRedirect</code> method or, if encoding is not needed,
   90        * returns the URL unchanged.  The implementation of this method
   91        * includes the logic to determine whether the session ID
   92        * needs to be encoded in the URL.  Because the rules for making
   93        * this determination can differ from those used to decide whether to
   94        * encode a normal link, this method is separated from the
   95        * <code>encodeURL</code> method.
   96        * 
   97        * <p>All URLs sent to the <code>HttpServletResponse.sendRedirect</code>
   98        * method should be run through this method.  Otherwise, URL
   99        * rewriting cannot be used with browsers which do not support
  100        * cookies.
  101        *
  102        * @param	url	the url to be encoded.
  103        * @return		the encoded URL if encoding is needed;
  104        * 			the unchanged URL otherwise.
  105        *
  106        * @see #sendRedirect
  107        * @see #encodeUrl
  108        */
  109   
  110       public String encodeRedirectURL(String url);
  111   
  112       /**
  113        * @deprecated	As of version 2.1, use encodeURL(String url) instead
  114        *
  115        * @param	url	the url to be encoded.
  116        * @return		the encoded URL if encoding is needed; 
  117        * 			the unchanged URL otherwise.
  118        */
  119   
  120       public String encodeUrl(String url);
  121       
  122       /**
  123        * @deprecated	As of version 2.1, use 
  124        *			encodeRedirectURL(String url) instead
  125        *
  126        * @param	url	the url to be encoded.
  127        * @return		the encoded URL if encoding is needed; 
  128        * 			the unchanged URL otherwise.
  129        */
  130   
  131       public String encodeRedirectUrl(String url);
  132   
  133       /**
  134        * Sends an error response to the client using the specified
  135        * status.  The server defaults to creating the
  136        * response to look like an HTML-formatted server error page
  137        * containing the specified message, setting the content type
  138        * to "text/html", leaving cookies and other headers unmodified.
  139        *
  140        * If an error-page declaration has been made for the web application
  141        * corresponding to the status code passed in, it will be served back in 
  142        * preference to the suggested msg parameter. 
  143        *
  144        * <p>If the response has already been committed, this method throws 
  145        * an IllegalStateException.
  146        * After using this method, the response should be considered
  147        * to be committed and should not be written to.
  148        *
  149        * @param	sc	the error status code
  150        * @param	msg	the descriptive message
  151        * @exception	IOException	If an input or output exception occurs
  152        * @exception	IllegalStateException	If the response was committed
  153        */
  154      
  155       public void sendError(int sc, String msg) throws IOException;
  156   
  157       /**
  158        * Sends an error response to the client using the specified status
  159        * code and clearing the buffer. 
  160        * <p>If the response has already been committed, this method throws 
  161        * an IllegalStateException.
  162        * After using this method, the response should be considered
  163        * to be committed and should not be written to.
  164        *
  165        * @param	sc	the error status code
  166        * @exception	IOException	If an input or output exception occurs
  167        * @exception	IllegalStateException	If the response was committed
  168        *						before this method call
  169        */
  170   
  171       public void sendError(int sc) throws IOException;
  172   
  173       /**
  174        * Sends a temporary redirect response to the client using the
  175        * specified redirect location URL.  This method can accept relative URLs;
  176        * the servlet container must convert the relative URL to an absolute URL
  177        * before sending the response to the client. If the location is relative 
  178        * without a leading '/' the container interprets it as relative to
  179        * the current request URI. If the location is relative with a leading
  180        * '/' the container interprets it as relative to the servlet container root.
  181        *
  182        * <p>If the response has already been committed, this method throws 
  183        * an IllegalStateException.
  184        * After using this method, the response should be considered
  185        * to be committed and should not be written to.
  186        *
  187        * @param		location	the redirect location URL
  188        * @exception	IOException	If an input or output exception occurs
  189        * @exception	IllegalStateException	If the response was committed or
  190    if a partial URL is given and cannot be converted into a valid URL
  191        */
  192   
  193       public void sendRedirect(String location) throws IOException;
  194       
  195       /**
  196        * 
  197        * Sets a response header with the given name and
  198        * date-value.  The date is specified in terms of
  199        * milliseconds since the epoch.  If the header had already
  200        * been set, the new value overwrites the previous one.  The
  201        * <code>containsHeader</code> method can be used to test for the
  202        * presence of a header before setting its value.
  203        * 
  204        * @param	name	the name of the header to set
  205        * @param	date	the assigned date value
  206        * 
  207        * @see #containsHeader
  208        * @see #addDateHeader
  209        */
  210   
  211       public void setDateHeader(String name, long date);
  212       
  213       /**
  214        * 
  215        * Adds a response header with the given name and
  216        * date-value.  The date is specified in terms of
  217        * milliseconds since the epoch.  This method allows response headers 
  218        * to have multiple values.
  219        * 
  220        * @param	name	the name of the header to set
  221        * @param	date	the additional date value
  222        * 
  223        * @see #setDateHeader
  224        */
  225   
  226       public void addDateHeader(String name, long date);
  227       
  228       /**
  229        *
  230        * Sets a response header with the given name and value.
  231        * If the header had already been set, the new value overwrites the
  232        * previous one.  The <code>containsHeader</code> method can be
  233        * used to test for the presence of a header before setting its
  234        * value.
  235        * 
  236        * @param	name	the name of the header
  237        * @param	value	the header value  If it contains octet string,
  238        *		it should be encoded according to RFC 2047
  239        *		(http://www.ietf.org/rfc/rfc2047.txt)
  240        *
  241        * @see #containsHeader
  242        * @see #addHeader
  243        */
  244   
  245       public void setHeader(String name, String value);
  246       
  247       /**
  248        * Adds a response header with the given name and value.
  249        * This method allows response headers to have multiple values.
  250        * 
  251        * @param	name	the name of the header
  252        * @param	value	the additional header value   If it contains
  253        *		octet string, it should be encoded
  254        *		according to RFC 2047
  255        *		(http://www.ietf.org/rfc/rfc2047.txt)
  256        *
  257        * @see #setHeader
  258        */
  259   
  260       public void addHeader(String name, String value);
  261   
  262       /**
  263        * Sets a response header with the given name and
  264        * integer value.  If the header had already been set, the new value
  265        * overwrites the previous one.  The <code>containsHeader</code>
  266        * method can be used to test for the presence of a header before
  267        * setting its value.
  268        *
  269        * @param	name	the name of the header
  270        * @param	value	the assigned integer value
  271        *
  272        * @see #containsHeader
  273        * @see #addIntHeader
  274        */
  275   
  276       public void setIntHeader(String name, int value);
  277   
  278       /**
  279        * Adds a response header with the given name and
  280        * integer value.  This method allows response headers to have multiple
  281        * values.
  282        *
  283        * @param	name	the name of the header
  284        * @param	value	the assigned integer value
  285        *
  286        * @see #setIntHeader
  287        */
  288   
  289       public void addIntHeader(String name, int value);
  290   
  291   
  292       
  293       /**
  294        * Sets the status code for this response.  This method is used to
  295        * set the return status code when there is no error (for example,
  296        * for the status codes SC_OK or SC_MOVED_TEMPORARILY).  If there
  297        * is an error, and the caller wishes to invoke an error-page defined
  298        * in the web application, the <code>sendError</code> method should be used
  299        * instead.
  300        * <p> The container clears the buffer and sets the Location header, preserving
  301        * cookies and other headers.
  302        *
  303        * @param	sc	the status code
  304        *
  305        * @see #sendError
  306        */
  307   
  308       public void setStatus(int sc);
  309     
  310       /**
  311        * @deprecated As of version 2.1, due to ambiguous meaning of the 
  312        * message parameter. To set a status code 
  313        * use <code>setStatus(int)</code>, to send an error with a description
  314        * use <code>sendError(int, String)</code>.
  315        *
  316        * Sets the status code and message for this response.
  317        * 
  318        * @param	sc	the status code
  319        * @param	sm	the status message
  320        */
  321   
  322       public void setStatus(int sc, String sm);
  323   
  324       
  325       /*
  326        * Server status codes; see RFC 2068.
  327        */
  328   
  329       /**
  330        * Status code (100) indicating the client can continue.
  331        */
  332   
  333       public static final int SC_CONTINUE = 100;
  334   
  335       
  336       /**
  337        * Status code (101) indicating the server is switching protocols
  338        * according to Upgrade header.
  339        */
  340   
  341       public static final int SC_SWITCHING_PROTOCOLS = 101;
  342   
  343       /**
  344        * Status code (200) indicating the request succeeded normally.
  345        */
  346   
  347       public static final int SC_OK = 200;
  348   
  349       /**
  350        * Status code (201) indicating the request succeeded and created
  351        * a new resource on the server.
  352        */
  353   
  354       public static final int SC_CREATED = 201;
  355   
  356       /**
  357        * Status code (202) indicating that a request was accepted for
  358        * processing, but was not completed.
  359        */
  360   
  361       public static final int SC_ACCEPTED = 202;
  362   
  363       /**
  364        * Status code (203) indicating that the meta information presented
  365        * by the client did not originate from the server.
  366        */
  367   
  368       public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
  369   
  370       /**
  371        * Status code (204) indicating that the request succeeded but that
  372        * there was no new information to return.
  373        */
  374   
  375       public static final int SC_NO_CONTENT = 204;
  376   
  377       /**
  378        * Status code (205) indicating that the agent <em>SHOULD</em> reset
  379        * the document view which caused the request to be sent.
  380        */
  381   
  382       public static final int SC_RESET_CONTENT = 205;
  383   
  384       /**
  385        * Status code (206) indicating that the server has fulfilled
  386        * the partial GET request for the resource.
  387        */
  388   
  389       public static final int SC_PARTIAL_CONTENT = 206;
  390   
  391       /**
  392        * Status code (300) indicating that the requested resource
  393        * corresponds to any one of a set of representations, each with
  394        * its own specific location.
  395        */
  396   
  397       public static final int SC_MULTIPLE_CHOICES = 300;
  398   
  399       /**
  400        * Status code (301) indicating that the resource has permanently
  401        * moved to a new location, and that future references should use a
  402        * new URI with their requests.
  403        */
  404   
  405       public static final int SC_MOVED_PERMANENTLY = 301;
  406   
  407       /**
  408        * Status code (302) indicating that the resource has temporarily
  409        * moved to another location, but that future references should
  410        * still use the original URI to access the resource.
  411        *
  412        * This definition is being retained for backwards compatibility.
  413        * SC_FOUND is now the preferred definition.
  414        */
  415   
  416       public static final int SC_MOVED_TEMPORARILY = 302;
  417   
  418       /**
  419       * Status code (302) indicating that the resource reside
  420       * temporarily under a different URI. Since the redirection might
  421       * be altered on occasion, the client should continue to use the
  422       * Request-URI for future requests.(HTTP/1.1) To represent the
  423       * status code (302), it is recommended to use this variable.
  424       */
  425   
  426       public static final int SC_FOUND = 302;
  427   
  428       /**
  429        * Status code (303) indicating that the response to the request
  430        * can be found under a different URI.
  431        */
  432   
  433       public static final int SC_SEE_OTHER = 303;
  434   
  435       /**
  436        * Status code (304) indicating that a conditional GET operation
  437        * found that the resource was available and not modified.
  438        */
  439   
  440       public static final int SC_NOT_MODIFIED = 304;
  441   
  442       /**
  443        * Status code (305) indicating that the requested resource
  444        * <em>MUST</em> be accessed through the proxy given by the
  445        * <code><em>Location</em></code> field.
  446        */
  447   
  448       public static final int SC_USE_PROXY = 305;
  449   
  450        /**
  451        * Status code (307) indicating that the requested resource 
  452        * resides temporarily under a different URI. The temporary URI
  453        * <em>SHOULD</em> be given by the <code><em>Location</em></code> 
  454        * field in the response.
  455        */
  456   
  457        public static final int SC_TEMPORARY_REDIRECT = 307;
  458   
  459       /**
  460        * Status code (400) indicating the request sent by the client was
  461        * syntactically incorrect.
  462        */
  463   
  464       public static final int SC_BAD_REQUEST = 400;
  465   
  466       /**
  467        * Status code (401) indicating that the request requires HTTP
  468        * authentication.
  469        */
  470   
  471       public static final int SC_UNAUTHORIZED = 401;
  472   
  473       /**
  474        * Status code (402) reserved for future use.
  475        */
  476   
  477       public static final int SC_PAYMENT_REQUIRED = 402;
  478   
  479       /**
  480        * Status code (403) indicating the server understood the request
  481        * but refused to fulfill it.
  482        */
  483   
  484       public static final int SC_FORBIDDEN = 403;
  485   
  486       /**
  487        * Status code (404) indicating that the requested resource is not
  488        * available.
  489        */
  490   
  491       public static final int SC_NOT_FOUND = 404;
  492   
  493       /**
  494        * Status code (405) indicating that the method specified in the
  495        * <code><em>Request-Line</em></code> is not allowed for the resource
  496        * identified by the <code><em>Request-URI</em></code>.
  497        */
  498   
  499       public static final int SC_METHOD_NOT_ALLOWED = 405;
  500   
  501       /**
  502        * Status code (406) indicating that the resource identified by the
  503        * request is only capable of generating response entities which have
  504        * content characteristics not acceptable according to the accept
  505        * headers sent in the request.
  506        */
  507   
  508       public static final int SC_NOT_ACCEPTABLE = 406;
  509   
  510       /**
  511        * Status code (407) indicating that the client <em>MUST</em> first
  512        * authenticate itself with the proxy.
  513        */
  514   
  515       public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
  516   
  517       /**
  518        * Status code (408) indicating that the client did not produce a
  519        * request within the time that the server was prepared to wait.
  520        */
  521   
  522       public static final int SC_REQUEST_TIMEOUT = 408;
  523   
  524       /**
  525        * Status code (409) indicating that the request could not be
  526        * completed due to a conflict with the current state of the
  527        * resource.
  528        */
  529   
  530       public static final int SC_CONFLICT = 409;
  531   
  532       /**
  533        * Status code (410) indicating that the resource is no longer
  534        * available at the server and no forwarding address is known.
  535        * This condition <em>SHOULD</em> be considered permanent.
  536        */
  537   
  538       public static final int SC_GONE = 410;
  539   
  540       /**
  541        * Status code (411) indicating that the request cannot be handled
  542        * without a defined <code><em>Content-Length</em></code>.
  543        */
  544   
  545       public static final int SC_LENGTH_REQUIRED = 411;
  546   
  547       /**
  548        * Status code (412) indicating that the precondition given in one
  549        * or more of the request-header fields evaluated to false when it
  550        * was tested on the server.
  551        */
  552   
  553       public static final int SC_PRECONDITION_FAILED = 412;
  554   
  555       /**
  556        * Status code (413) indicating that the server is refusing to process
  557        * the request because the request entity is larger than the server is
  558        * willing or able to process.
  559        */
  560   
  561       public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
  562   
  563       /**
  564        * Status code (414) indicating that the server is refusing to service
  565        * the request because the <code><em>Request-URI</em></code> is longer
  566        * than the server is willing to interpret.
  567        */
  568   
  569       public static final int SC_REQUEST_URI_TOO_LONG = 414;
  570   
  571       /**
  572        * Status code (415) indicating that the server is refusing to service
  573        * the request because the entity of the request is in a format not
  574        * supported by the requested resource for the requested method.
  575        */
  576   
  577       public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
  578   
  579       /**
  580        * Status code (416) indicating that the server cannot serve the
  581        * requested byte range.
  582        */
  583   
  584       public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
  585   
  586       /**
  587        * Status code (417) indicating that the server could not meet the
  588        * expectation given in the Expect request header.
  589        */
  590   
  591       public static final int SC_EXPECTATION_FAILED = 417;
  592   
  593       /**
  594        * Status code (500) indicating an error inside the HTTP server
  595        * which prevented it from fulfilling the request.
  596        */
  597   
  598       public static final int SC_INTERNAL_SERVER_ERROR = 500;
  599   
  600       /**
  601        * Status code (501) indicating the HTTP server does not support
  602        * the functionality needed to fulfill the request.
  603        */
  604   
  605       public static final int SC_NOT_IMPLEMENTED = 501;
  606   
  607       /**
  608        * Status code (502) indicating that the HTTP server received an
  609        * invalid response from a server it consulted when acting as a
  610        * proxy or gateway.
  611        */
  612   
  613       public static final int SC_BAD_GATEWAY = 502;
  614   
  615       /**
  616        * Status code (503) indicating that the HTTP server is
  617        * temporarily overloaded, and unable to handle the request.
  618        */
  619   
  620       public static final int SC_SERVICE_UNAVAILABLE = 503;
  621   
  622       /**
  623        * Status code (504) indicating that the server did not receive
  624        * a timely response from the upstream server while acting as
  625        * a gateway or proxy.
  626        */
  627   
  628       public static final int SC_GATEWAY_TIMEOUT = 504;
  629   
  630       /**
  631        * Status code (505) indicating that the server does not support
  632        * or refuses to support the HTTP protocol version that was used
  633        * in the request message.
  634        */
  635   
  636       public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
  637   }

Home » apache-tomcat-6.0.26-src » javax » servlet » http » [javadoc | source]