home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / HttpServletResponse.java < prev    next >
Text File  |  1998-04-21  |  16KB  |  442 lines
  1. /*
  2.  * @(#)HttpServletResponse.java    1.26 97/10/20
  3.  * 
  4.  * Copyright (c) 1995-1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.0
  20.  */
  21.  
  22. package javax.servlet.http;
  23.  
  24. import javax.servlet.ServletResponse;
  25. import java.io.IOException;
  26.  
  27. /**
  28.  * An HTTP servlet response.  This interface allows a servlet's
  29.  * <code>service</code> method to manipulate HTTP-protocol specified
  30.  * header information and return data to its client.  It is implemented
  31.  * by network service developers for use within servlets.
  32.  * 
  33.  *
  34.  * @version 1.26, 10/20/97
  35.  */
  36. public
  37. interface HttpServletResponse extends ServletResponse {
  38.  
  39.     /**
  40.      * Adds the specified cookie to the response.  It can be called
  41.      * multiple times to set more than one cookie.
  42.      *
  43.      * @param cookie the Cookie to return to the client
  44.      */
  45.     public void addCookie(Cookie cookie);
  46.  
  47.     /**
  48.      * Checks whether the response message header has a field with
  49.      * the specified name.
  50.      * 
  51.      * @param name the header field name
  52.      * @return true if the response message header has a field with
  53.      * the specified name; false otherwise
  54.      */
  55.     public boolean containsHeader(String name);
  56.  
  57.     /**
  58.      * Sets the status code and message for this response.  If the
  59.      * field had already been set, the new value overwrites the
  60.      * previous one.  The message is sent as the body of an HTML
  61.      * page, which is returned to the user to describe the problem.
  62.      * The page is sent with a default HTML header; the message
  63.      * is enclosed in simple body tags (<body></body>).
  64.      * 
  65.      * @param sc the status code
  66.      * @param sm the status message
  67.      */
  68.     public void setStatus(int sc, String sm);
  69.  
  70.     /**
  71.      * Sets the status code for this response.  This method is used to
  72.      * set the return status code when there is no error (for example,
  73.      * for the status codes SC_OK or SC_MOVED_TEMPORARILY).  If there
  74.      * is an error, the <code>sendError</code> method should be used
  75.      * instead.
  76.      *
  77.      * @param sc the status code
  78.      *
  79.      * @see #sendError
  80.      */
  81.     public void setStatus(int sc);
  82.  
  83.     /**
  84.      *
  85.      * Adds a field to the response header with the given name and value.
  86.      * If the field had already been set, the new value overwrites the
  87.      * previous one.  The <code>containsHeader</code> method can be
  88.      * used to test for the presence of a header before setting its
  89.      * value.
  90.      * 
  91.      * @param name the name of the header field
  92.      * @param value the header field's value
  93.      *
  94.      * @see #containsHeader
  95.      */
  96.     public void setHeader(String name, String value);
  97.  
  98.     /**
  99.      * Adds a field to the response header with the given name and
  100.      * integer value.  If the field had already been set, the new value
  101.      * overwrites the previous one.  The <code>containsHeader</code>
  102.      * method can be used to test for the presence of a header before
  103.      * setting its value.
  104.      *
  105.      * @param name the name of the header field
  106.      * @param value the header field's integer value
  107.      *
  108.      * @see #containsHeader
  109.      */
  110.     public void setIntHeader(String name, int value);
  111.  
  112.     /**
  113.      * 
  114.      * Adds a field to the response header with the given name and
  115.      * date-valued field.  The date is specified in terms of
  116.      * milliseconds since the epoch.  If the date field had already
  117.      * been set, the new value overwrites the previous one.  The
  118.      * <code>containsHeader</code> method can be used to test for the
  119.      * presence of a header before setting its value.
  120.      * 
  121.      * @param name the name of the header field
  122.      * @param value the header field's date value
  123.      * 
  124.      * @see #containsHeader
  125.      */
  126.     public void setDateHeader(String name, long date);
  127.  
  128.     /**
  129.      * Sends an error response to the client using the specified status
  130.      * code and descriptive message.  If setStatus has previously been
  131.      * called, it is reset to the error status code.  The message is
  132.      * sent as the body of an HTML page, which is returned to the user
  133.      * to describe the problem.  The page is sent with a default HTML
  134.      * header; the message is enclosed in simple body tags
  135.      * (<body></body>).
  136.      * 
  137.      * @param sc the status code
  138.      * @param msg the detail message
  139.      * @exception IOException If an I/O error has occurred.  */
  140.     public void sendError(int sc, String msg) throws IOException;
  141.  
  142.     /**
  143.      * Sends an error response to the client using the specified
  144.      * status code and a default message.
  145.      * @param sc the status code
  146.      * @exception IOException If an I/O error has occurred.
  147.      */
  148.     public void sendError(int sc) throws IOException;
  149.  
  150.     /**
  151.      * Sends a temporary redirect response to the client using the
  152.      * specified redirect location URL.  The URL must be absolute (for
  153.      * example, <code><em>https://hostname/path/file.html</em></code>).
  154.      * Relative URLs are not permitted here.
  155.      *
  156.      * @param location the redirect location URL
  157.      * @exception IOException If an I/O error has occurred.
  158.      */
  159.     public void sendRedirect(String location) throws IOException;
  160.  
  161.     /**
  162.      * Encodes the specified URL by including the session ID in it,
  163.      * or, if encoding is not needed, returns the URL unchanged.
  164.      * The implementation of this method should include the logic to
  165.      * determine whether the session ID needs to be encoded in the URL.
  166.      * For example, if the browser supports cookies, or session
  167.      * tracking is turned off, URL encoding is unnecessary.
  168.      * 
  169.      * <p>All URLs emitted by a Servlet should be run through this
  170.      * method.  Otherwise, URL rewriting cannot be used with browsers
  171.      * which do not support cookies.
  172.      *
  173.      * @param url the url to be encoded.
  174.      * @return the encoded URL if encoding is needed; the unchanged URL
  175.      * otherwise.
  176.      */
  177.     public String encodeUrl (String url);
  178.  
  179.     /**
  180.      * Encodes the specified URL for use in the
  181.      * <code>sendRedirect</code> method or, if encoding is not needed,
  182.      * returns the URL unchanged.  The implementation of this method
  183.      * should include the logic to determine whether the session ID
  184.      * needs to be encoded in the URL.  Because the rules for making
  185.      * this determination differ from those used to decide whether to
  186.      * encode a normal link, this method is seperate from the
  187.      * <code>encodeUrl</code> method.
  188.      * 
  189.      * <p>All URLs sent to the HttpServletResponse.sendRedirect
  190.      * method should be run through this method.  Otherwise, URL
  191.      * rewriting canont be used with browsers which do not support
  192.      * cookies.
  193.      *
  194.      * @param url the url to be encoded.
  195.      * @return the encoded URL if encoding is needed; the unchanged URL
  196.      * otherwise.
  197.      *
  198.      * @see #sendRedirect
  199.      * @see #encodeUrl
  200.      */
  201.     public String encodeRedirectUrl (String url);
  202.  
  203.     /*
  204.      * Server status codes; see RFC 2068.
  205.      */
  206.  
  207.     /**
  208.      * Status code (100) indicating the client can continue.
  209.      */
  210.     public static final int SC_CONTINUE = 100;
  211.  
  212.     /**
  213.      * Status code (101) indicating the server is switching protocols
  214.      * according to Upgrade header.
  215.      */
  216.     public static final int SC_SWITCHING_PROTOCOLS = 101;
  217.  
  218.     /**
  219.      * Status code (200) indicating the request succeeded normally.
  220.      */
  221.     public static final int SC_OK = 200;
  222.  
  223.     /**
  224.      * Status code (201) indicating the request succeeded and created
  225.      * a new resource on the server.
  226.      */
  227.     public static final int SC_CREATED = 201;
  228.  
  229.     /**
  230.      * Status code (202) indicating that a request was accepted for
  231.      * processing, but was not completed.
  232.      */
  233.     public static final int SC_ACCEPTED = 202;
  234.  
  235.     /**
  236.      * Status code (203) indicating that the meta information presented
  237.      * by the client did not originate from the server.
  238.      */
  239.     public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
  240.  
  241.     /**
  242.      * Status code (204) indicating that the request succeeded but that
  243.      * there was no new information to return.
  244.      */
  245.     public static final int SC_NO_CONTENT = 204;
  246.  
  247.     /**
  248.      * Status code (205) indicating that the agent <em>SHOULD</em> reset
  249.      * the document view which caused the request to be sent.
  250.      */
  251.     public static final int SC_RESET_CONTENT = 205;
  252.  
  253.     /**
  254.      * Status code (206) indicating that the server has fulfilled
  255.      * the partial GET request for the resource.
  256.      */
  257.     public static final int SC_PARTIAL_CONTENT = 206;
  258.  
  259.     /**
  260.      * Status code (300) indicating that the requested resource
  261.      * corresponds to any one of a set of representations, each with
  262.      * its own specific location.
  263.      */
  264.     public static final int SC_MULTIPLE_CHOICES = 300;
  265.  
  266.     /**
  267.      * Status code (301) indicating that the resource has permanently
  268.      * moved to a new location, and that future references should use a
  269.      * new URI with their requests.
  270.      */
  271.     public static final int SC_MOVED_PERMANENTLY = 301;
  272.  
  273.     /**
  274.      * Status code (302) indicating that the resource has temporarily
  275.      * moved to another location, but that future references should
  276.      * still use the original URI to access the resource.
  277.      */
  278.     public static final int SC_MOVED_TEMPORARILY = 302;
  279.  
  280.     /**
  281.      * Status code (303) indicating that the response to the request
  282.      * can be found under a different URI.
  283.      */
  284.     public static final int SC_SEE_OTHER = 303;
  285.  
  286.     /**
  287.      * Status code (304) indicating that a conditional GET operation
  288.      * found that the resource was available and not modified.
  289.      */
  290.     public static final int SC_NOT_MODIFIED = 304;
  291.  
  292.     /**
  293.      * Status code (305) indicating that the requested resource
  294.      * <em>MUST</em> be accessed through the proxy given by the
  295.      * <code><em>Location</em></code> field.
  296.      */
  297.     public static final int SC_USE_PROXY = 305;
  298.  
  299.     /**
  300.      * Status code (400) indicating the request sent by the client was
  301.      * syntactically incorrect.
  302.      */
  303.     public static final int SC_BAD_REQUEST = 400;
  304.  
  305.     /**
  306.      * Status code (401) indicating that the request requires HTTP
  307.      * authentication.
  308.      */
  309.     public static final int SC_UNAUTHORIZED = 401;
  310.  
  311.     /**
  312.      * Status code (402) reserved for future use.
  313.      */
  314.     public static final int SC_PAYMENT_REQUIRED = 402;
  315.  
  316.     /**
  317.      * Status code (403) indicating the server understood the request
  318.      * but refused to fulfill it.
  319.      */
  320.     public static final int SC_FORBIDDEN = 403;
  321.  
  322.     /**
  323.      * Status code (404) indicating that the requested resource is not
  324.      * available.
  325.      */
  326.     public static final int SC_NOT_FOUND = 404;
  327.  
  328.     /**
  329.      * Status code (405) indicating that the method specified in the
  330.      * <code><em>Request-Line</em></code> is not allowed for the resource
  331.      * identified by the <code><em>Request-URI</em></code>.
  332.      */
  333.     public static final int SC_METHOD_NOT_ALLOWED = 405;
  334.  
  335.     /**
  336.      * Status code (406) indicating that the resource identified by the
  337.      * request is only capable of generating response entities which have
  338.      * content characteristics not acceptable according to the accept
  339.      * headerssent in the request.
  340.      */
  341.     public static final int SC_NOT_ACCEPTABLE = 406;
  342.  
  343.     /**
  344.      * Status code (407) indicating that the client <em>MUST</em> first
  345.      * authenticate itself with the proxy.
  346.      */
  347.     public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
  348.  
  349.     /**
  350.      * Status code (408) indicating that the client did not produce a
  351.      * requestwithin the time that the server was prepared to wait.
  352.      */
  353.     public static final int SC_REQUEST_TIMEOUT = 408;
  354.  
  355.     /**
  356.      * Status code (409) indicating that the request could not be
  357.      * completed due to a conflict with the current state of the
  358.      * resource.
  359.      */
  360.     public static final int SC_CONFLICT = 409;
  361.  
  362.     /**
  363.      * Status code (410) indicating that the resource is no longer
  364.      * available at the server and no forwarding address is known.
  365.      * This condition <em>SHOULD</em> be considered permanent.
  366.      */
  367.     public static final int SC_GONE = 410;
  368.  
  369.     /**
  370.      * Status code (411) indicating that the request cannot be handled
  371.      * without a defined <code><em>Content-Length</em></code>.
  372.      */
  373.     public static final int SC_LENGTH_REQUIRED = 411;
  374.  
  375.     /**
  376.      * Status code (412) indicating that the precondition given in one
  377.      * or more of the request-header fields evaluated to false when it
  378.      * was tested on the server.
  379.      */
  380.     public static final int SC_PRECONDITION_FAILED = 412;
  381.  
  382.     /**
  383.      * Status code (413) indicating that the server is refusing to process
  384.      * the request because the request entity is larger than the server is
  385.      * willing or able to process.
  386.      */
  387.     public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
  388.  
  389.     /**
  390.      * Status code (414) indicating that the server is refusing to service
  391.      * the request because the <code><em>Request-URI</em></code> is longer
  392.      * than the server is willing to interpret.
  393.      */
  394.     public static final int SC_REQUEST_URI_TOO_LONG = 414;
  395.  
  396.     /**
  397.      * Status code (415) indicating that the server is refusing to service
  398.      * the request because the entity of the request is in a format not
  399.      * supported by the requested resource for the requested method.
  400.      */
  401.     public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
  402.  
  403.     /**
  404.      * Status code (500) indicating an error inside the HTTP server
  405.      * which prevented it from fulfilling the request.
  406.      */
  407.     public static final int SC_INTERNAL_SERVER_ERROR = 500;
  408.  
  409.     /**
  410.      * Status code (501) indicating the HTTP server does not support
  411.      * the functionality needed to fulfill the request.
  412.      */
  413.     public static final int SC_NOT_IMPLEMENTED = 501;
  414.  
  415.     /**
  416.      * Status code (502) indicating that the HTTP server received an
  417.      * invalid response from a server it consulted when acting as a
  418.      * proxy or gateway.
  419.      */
  420.     public static final int SC_BAD_GATEWAY = 502;
  421.  
  422.     /**
  423.      * Status code (503) indicating that the HTTP server is
  424.      * temporarily overloaded, and unable to handle the request.
  425.      */
  426.     public static final int SC_SERVICE_UNAVAILABLE = 503;
  427.  
  428.     /**
  429.      * Status code (504) indicating that the server did not receive
  430.      * a timely response from the upstream server while acting as
  431.      * a gateway or proxy.
  432.      */
  433.     public static final int SC_GATEWAY_TIMEOUT = 504;
  434.  
  435.     /**
  436.      * Status code (505) indicating that the server does not support
  437.      * or refuses to support the HTTP protocol version that was used
  438.      * in the request message.
  439.      */
  440.     public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
  441. }
  442.