HttpServletResponse.java
上传用户:tanyanyong
上传日期:2013-06-23
资源大小:1355k
文件大小:21k
源码类别:

电子政务应用

开发平台:

MultiPlatform

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer. 
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution, if
  20.  *    any, must include the following acknowlegement:  
  21.  *       "This product includes software developed by the 
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowlegement may appear in the software itself,
  24.  *    if and wherever such third-party acknowlegements normally appear.
  25.  *
  26.  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  27.  *    Foundation" must not be used to endorse or promote products derived
  28.  *    from this software without prior written permission. For written 
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache"
  32.  *    nor may "Apache" appear in their names without prior written
  33.  *    permission of the Apache Group.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  *
  54.  * ====================================================================
  55.  *
  56.  * This source code implements specifications defined by the Java
  57.  * Community Process. In order to remain compliant with the specification
  58.  * DO NOT add / change / or delete method signatures!
  59.  */ 
  60. package javax.servlet.http;
  61. import javax.servlet.ServletResponse;
  62. import javax.servlet.ServletException;
  63. import java.io.IOException;
  64. /**
  65.  *
  66.  * Extends the {@link ServletResponse} interface to provide HTTP-specific
  67.  * functionality in sending a response.  For example, it has methods
  68.  * to access HTTP headers and cookies.
  69.  *
  70.  * <p>The servlet container creates an <code>HttpServletRequest</code> object
  71.  * and passes it as an argument to the servlet's service methods
  72.  * (<code>doGet</code>, <code>doPost</code>, etc).
  73.  *
  74.  * 
  75.  * @author Various
  76.  * @version $Version$
  77.  *
  78.  * @see javax.servlet.ServletResponse
  79.  *
  80.  */
  81. public interface HttpServletResponse extends ServletResponse {
  82.     /**
  83.      * Adds the specified cookie to the response.  This method can be called
  84.      * multiple times to set more than one cookie.
  85.      *
  86.      * @param cookie the Cookie to return to the client
  87.      *
  88.      */
  89.     public void addCookie(Cookie cookie);
  90.     /**
  91.      * Returns a boolean indicating whether the named response header 
  92.      * has already been set.
  93.      * 
  94.      * @param name the header name
  95.      * @return <code>true</code> if the named response header 
  96.      * has already been set; 
  97.      *  <code>false</code> otherwise
  98.      */
  99.     public boolean containsHeader(String name);
  100.     /**
  101.      * Encodes the specified URL by including the session ID in it,
  102.      * or, if encoding is not needed, returns the URL unchanged.
  103.      * The implementation of this method includes the logic to
  104.      * determine whether the session ID needs to be encoded in the URL.
  105.      * For example, if the browser supports cookies, or session
  106.      * tracking is turned off, URL encoding is unnecessary.
  107.      * 
  108.      * <p>For robust session tracking, all URLs emitted by a servlet 
  109.      * should be run through this
  110.      * method.  Otherwise, URL rewriting cannot be used with browsers
  111.      * which do not support cookies.
  112.      *
  113.      * @param url the url to be encoded.
  114.      * @return the encoded URL if encoding is needed;
  115.      *  the unchanged URL otherwise.
  116.      */
  117.     public String encodeURL(String url);
  118.     /**
  119.      * Encodes the specified URL for use in the
  120.      * <code>sendRedirect</code> method or, if encoding is not needed,
  121.      * returns the URL unchanged.  The implementation of this method
  122.      * includes the logic to determine whether the session ID
  123.      * needs to be encoded in the URL.  Because the rules for making
  124.      * this determination can differ from those used to decide whether to
  125.      * encode a normal link, this method is seperate from the
  126.      * <code>encodeURL</code> method.
  127.      * 
  128.      * <p>All URLs sent to the <code>HttpServletResponse.sendRedirect</code>
  129.      * method should be run through this method.  Otherwise, URL
  130.      * rewriting cannot be used with browsers which do not support
  131.      * cookies.
  132.      *
  133.      * @param url the url to be encoded.
  134.      * @return the encoded URL if encoding is needed;
  135.      *  the unchanged URL otherwise.
  136.      *
  137.      * @see #sendRedirect
  138.      * @see #encodeUrl
  139.      */
  140.     public String encodeRedirectURL(String url);
  141.     /**
  142.      * @deprecated As of version 2.1, use encodeURL(String url) instead
  143.      *
  144.      * @param url the url to be encoded.
  145.      * @return the encoded URL if encoding is needed; 
  146.      *  the unchanged URL otherwise.
  147.      */
  148.     public String encodeUrl(String url);
  149.     
  150.     /**
  151.      * @deprecated As of version 2.1, use 
  152.      * encodeRedirectURL(String url) instead
  153.      *
  154.      * @param url the url to be encoded.
  155.      * @return the encoded URL if encoding is needed; 
  156.      *  the unchanged URL otherwise.
  157.      */
  158.     public String encodeRedirectUrl(String url);
  159.     /**
  160.      * Sends an error response to the client using the specified status
  161.      * code and descriptive message.  The server generally creates the 
  162.      * response to look like a normal server error page.
  163.      *
  164.      * <p>If the response has already been committed, this method throws 
  165.      * an IllegalStateException.
  166.      * After using this method, the response should be considered
  167.      * to be committed and should not be written to.
  168.      *
  169.      * @param sc the error status code
  170.      * @param msg the descriptive message
  171.      * @exception IOException If an input or output exception occurs
  172.      * @exception IllegalStateException If the response was committed
  173.      * before this method call
  174.      */
  175.     public void sendError(int sc, String msg) throws IOException;
  176.     /**
  177.      * Sends an error response to the client using the specified
  178.      * status.  The server generally creates the 
  179.      * response to look like a normal server error page.
  180.      *
  181.      * <p>If the response has already been committed, this method throws 
  182.      * an IllegalStateException.
  183.      * After using this method, the response should be considered
  184.      * to be committed and should not be written to.
  185.      *
  186.      * @param sc the error status code
  187.      * @exception IOException If an input or output exception occurs
  188.      * @exception IllegalStateException If the response was committed
  189.      */
  190.     public void sendError(int sc) throws IOException;
  191.     /**
  192.      * Sends a temporary redirect response to the client using the
  193.      * specified redirect location URL.  This method can accept relative URLs;
  194.      * the servlet container will convert the relative URL to an absolute URL
  195.      * before sending the response to the client.
  196.      *
  197.      * <p>If the response has already been committed, this method throws 
  198.      * an IllegalStateException.
  199.      * After using this method, the response should be considered
  200.      * to be committed and should not be written to.
  201.      *
  202.      * @param location the redirect location URL
  203.      * @exception IOException If an input or output exception occurs
  204.      * @exception IllegalStateException If the response was committed
  205.      */
  206.     public void sendRedirect(String location) throws IOException;
  207.     
  208.     /**
  209.      * 
  210.      * Sets a response header with the given name and
  211.      * date-value.  The date is specified in terms of
  212.      * milliseconds since the epoch.  If the header had already
  213.      * been set, the new value overwrites the previous one.  The
  214.      * <code>containsHeader</code> method can be used to test for the
  215.      * presence of a header before setting its value.
  216.      * 
  217.      * @param name the name of the header to set
  218.      * @param value the assigned date value
  219.      * 
  220.      * @see #containsHeader
  221.      * @see #addDateHeader
  222.      */
  223.     public void setDateHeader(String name, long date);
  224.     
  225.     /**
  226.      * 
  227.      * Adds a response header with the given name and
  228.      * date-value.  The date is specified in terms of
  229.      * milliseconds since the epoch.  This method allows response headers 
  230.      * to have multiple values.
  231.      * 
  232.      * @param name the name of the header to set
  233.      * @param value the additional date value
  234.      * 
  235.      * @see #setDateHeader
  236.      */
  237.     public void addDateHeader(String name, long date);
  238.     
  239.     /**
  240.      *
  241.      * Sets a response header with the given name and value.
  242.      * If the header had already been set, the new value overwrites the
  243.      * previous one.  The <code>containsHeader</code> method can be
  244.      * used to test for the presence of a header before setting its
  245.      * value.
  246.      * 
  247.      * @param name the name of the header
  248.      * @param value the header value
  249.      *
  250.      * @see #containsHeader
  251.      * @see #addHeader
  252.      */
  253.     public void setHeader(String name, String value);
  254.     
  255.     /**
  256.      * Adds a response header with the given name and value.
  257.      * This method allows response headers to have multiple values.
  258.      * 
  259.      * @param name the name of the header
  260.      * @param value the additional header value
  261.      *
  262.      * @see #setHeader
  263.      */
  264.     public void addHeader(String name, String value);
  265.     /**
  266.      * Sets a response header with the given name and
  267.      * integer value.  If the header had already been set, the new value
  268.      * overwrites the previous one.  The <code>containsHeader</code>
  269.      * method can be used to test for the presence of a header before
  270.      * setting its value.
  271.      *
  272.      * @param name the name of the header
  273.      * @param value the assigned integer value
  274.      *
  275.      * @see #containsHeader
  276.      * @see #addIntHeader
  277.      */
  278.     public void setIntHeader(String name, int value);
  279.     /**
  280.      * Adds a response header with the given name and
  281.      * integer value.  This method allows response headers to have multiple
  282.      * values.
  283.      *
  284.      * @param name the name of the header
  285.      * @param value the assigned integer value
  286.      *
  287.      * @see #setIntHeader
  288.      */
  289.     public void addIntHeader(String name, int value);
  290.     
  291.     /**
  292.      * Sets the status code for this response.  This method is used to
  293.      * set the return status code when there is no error (for example,
  294.      * for the status codes SC_OK or SC_MOVED_TEMPORARILY).  If there
  295.      * is an error, the <code>sendError</code> method should be used
  296.      * instead.
  297.      *
  298.      * @param sc the status code
  299.      *
  300.      * @see #sendError
  301.      */
  302.     public void setStatus(int sc);
  303.   
  304.     /**
  305.      * @deprecated As of version 2.1, due to ambiguous meaning of the 
  306.      * message parameter. To set a status code 
  307.      * use <code>setStatus(int)</code>, to send an error with a description
  308.      * use <code>sendError(int, String)</code>.
  309.      *
  310.      * Sets the status code and message for this response.
  311.      * 
  312.      * @param sc the status code
  313.      * @param sm the status message
  314.      */
  315.     public void setStatus(int sc, String sm);
  316.     
  317.     /*
  318.      * Server status codes; see RFC 2068.
  319.      */
  320.     /**
  321.      * Status code (100) indicating the client can continue.
  322.      */
  323.     public static final int SC_CONTINUE = 100;
  324.     
  325.     /**
  326.      * Status code (101) indicating the server is switching protocols
  327.      * according to Upgrade header.
  328.      */
  329.     public static final int SC_SWITCHING_PROTOCOLS = 101;
  330.     /**
  331.      * Status code (200) indicating the request succeeded normally.
  332.      */
  333.     public static final int SC_OK = 200;
  334.     /**
  335.      * Status code (201) indicating the request succeeded and created
  336.      * a new resource on the server.
  337.      */
  338.     public static final int SC_CREATED = 201;
  339.     /**
  340.      * Status code (202) indicating that a request was accepted for
  341.      * processing, but was not completed.
  342.      */
  343.     public static final int SC_ACCEPTED = 202;
  344.     /**
  345.      * Status code (203) indicating that the meta information presented
  346.      * by the client did not originate from the server.
  347.      */
  348.     public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
  349.     /**
  350.      * Status code (204) indicating that the request succeeded but that
  351.      * there was no new information to return.
  352.      */
  353.     public static final int SC_NO_CONTENT = 204;
  354.     /**
  355.      * Status code (205) indicating that the agent <em>SHOULD</em> reset
  356.      * the document view which caused the request to be sent.
  357.      */
  358.     public static final int SC_RESET_CONTENT = 205;
  359.     /**
  360.      * Status code (206) indicating that the server has fulfilled
  361.      * the partial GET request for the resource.
  362.      */
  363.     public static final int SC_PARTIAL_CONTENT = 206;
  364.     /**
  365.      * Status code (300) indicating that the requested resource
  366.      * corresponds to any one of a set of representations, each with
  367.      * its own specific location.
  368.      */
  369.     public static final int SC_MULTIPLE_CHOICES = 300;
  370.     /**
  371.      * Status code (301) indicating that the resource has permanently
  372.      * moved to a new location, and that future references should use a
  373.      * new URI with their requests.
  374.      */
  375.     public static final int SC_MOVED_PERMANENTLY = 301;
  376.     /**
  377.      * Status code (302) indicating that the resource has temporarily
  378.      * moved to another location, but that future references should
  379.      * still use the original URI to access the resource.
  380.      */
  381.     public static final int SC_MOVED_TEMPORARILY = 302;
  382.     /**
  383.      * Status code (303) indicating that the response to the request
  384.      * can be found under a different URI.
  385.      */
  386.     public static final int SC_SEE_OTHER = 303;
  387.     /**
  388.      * Status code (304) indicating that a conditional GET operation
  389.      * found that the resource was available and not modified.
  390.      */
  391.     public static final int SC_NOT_MODIFIED = 304;
  392.     /**
  393.      * Status code (305) indicating that the requested resource
  394.      * <em>MUST</em> be accessed through the proxy given by the
  395.      * <code><em>Location</em></code> field.
  396.      */
  397.     public static final int SC_USE_PROXY = 305;
  398.     // Status code 306 is officially "Unused"
  399.     /**
  400.      * Status code (307) indicating that the requested resource
  401.      * resides temporarily under a different URI.
  402.      */
  403.     public static final int SC_TEMPORARY_REDIRECT = 307;
  404.     /**
  405.      * Status code (400) indicating the request sent by the client was
  406.      * syntactically incorrect.
  407.      */
  408.     public static final int SC_BAD_REQUEST = 400;
  409.     /**
  410.      * Status code (401) indicating that the request requires HTTP
  411.      * authentication.
  412.      */
  413.     public static final int SC_UNAUTHORIZED = 401;
  414.     /**
  415.      * Status code (402) reserved for future use.
  416.      */
  417.     public static final int SC_PAYMENT_REQUIRED = 402;
  418.     /**
  419.      * Status code (403) indicating the server understood the request
  420.      * but refused to fulfill it.
  421.      */
  422.     public static final int SC_FORBIDDEN = 403;
  423.     /**
  424.      * Status code (404) indicating that the requested resource is not
  425.      * available.
  426.      */
  427.     public static final int SC_NOT_FOUND = 404;
  428.     /**
  429.      * Status code (405) indicating that the method specified in the
  430.      * <code><em>Request-Line</em></code> is not allowed for the resource
  431.      * identified by the <code><em>Request-URI</em></code>.
  432.      */
  433.     public static final int SC_METHOD_NOT_ALLOWED = 405;
  434.     /**
  435.      * Status code (406) indicating that the resource identified by the
  436.      * request is only capable of generating response entities which have
  437.      * content characteristics not acceptable according to the accept
  438.      * headerssent in the request.
  439.      */
  440.     public static final int SC_NOT_ACCEPTABLE = 406;
  441.     /**
  442.      * Status code (407) indicating that the client <em>MUST</em> first
  443.      * authenticate itself with the proxy.
  444.      */
  445.     public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
  446.     /**
  447.      * Status code (408) indicating that the client did not produce a
  448.      * requestwithin the time that the server was prepared to wait.
  449.      */
  450.     public static final int SC_REQUEST_TIMEOUT = 408;
  451.     /**
  452.      * Status code (409) indicating that the request could not be
  453.      * completed due to a conflict with the current state of the
  454.      * resource.
  455.      */
  456.     public static final int SC_CONFLICT = 409;
  457.     /**
  458.      * Status code (410) indicating that the resource is no longer
  459.      * available at the server and no forwarding address is known.
  460.      * This condition <em>SHOULD</em> be considered permanent.
  461.      */
  462.     public static final int SC_GONE = 410;
  463.     /**
  464.      * Status code (411) indicating that the request cannot be handled
  465.      * without a defined <code><em>Content-Length</em></code>.
  466.      */
  467.     public static final int SC_LENGTH_REQUIRED = 411;
  468.     /**
  469.      * Status code (412) indicating that the precondition given in one
  470.      * or more of the request-header fields evaluated to false when it
  471.      * was tested on the server.
  472.      */
  473.     public static final int SC_PRECONDITION_FAILED = 412;
  474.     /**
  475.      * Status code (413) indicating that the server is refusing to process
  476.      * the request because the request entity is larger than the server is
  477.      * willing or able to process.
  478.      */
  479.     public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
  480.     /**
  481.      * Status code (414) indicating that the server is refusing to service
  482.      * the request because the <code><em>Request-URI</em></code> is longer
  483.      * than the server is willing to interpret.
  484.      */
  485.     public static final int SC_REQUEST_URI_TOO_LONG = 414;
  486.     /**
  487.      * Status code (415) indicating that the server is refusing to service
  488.      * the request because the entity of the request is in a format not
  489.      * supported by the requested resource for the requested method.
  490.      */
  491.     public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
  492.     /**
  493.      * Status code (416) indicating that the server cannot serve the
  494.      * requested byte range.
  495.      */
  496.     public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
  497.     /**
  498.      * Status code (417) indicating that the server could not meet the
  499.      * expectation given in the Expect request header.
  500.      */
  501.     public static final int SC_EXPECTATION_FAILED = 417;
  502.     /**
  503.      * Status code (500) indicating an error inside the HTTP server
  504.      * which prevented it from fulfilling the request.
  505.      */
  506.     public static final int SC_INTERNAL_SERVER_ERROR = 500;
  507.     /**
  508.      * Status code (501) indicating the HTTP server does not support
  509.      * the functionality needed to fulfill the request.
  510.      */
  511.     public static final int SC_NOT_IMPLEMENTED = 501;
  512.     /**
  513.      * Status code (502) indicating that the HTTP server received an
  514.      * invalid response from a server it consulted when acting as a
  515.      * proxy or gateway.
  516.      */
  517.     public static final int SC_BAD_GATEWAY = 502;
  518.     /**
  519.      * Status code (503) indicating that the HTTP server is
  520.      * temporarily overloaded, and unable to handle the request.
  521.      */
  522.     public static final int SC_SERVICE_UNAVAILABLE = 503;
  523.     /**
  524.      * Status code (504) indicating that the server did not receive
  525.      * a timely response from the upstream server while acting as
  526.      * a gateway or proxy.
  527.      */
  528.     public static final int SC_GATEWAY_TIMEOUT = 504;
  529.     /**
  530.      * Status code (505) indicating that the server does not support
  531.      * or refuses to support the HTTP protocol version that was used
  532.      * in the request message.
  533.      */
  534.     public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
  535. }