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

电子政务应用

开发平台:

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;
  61. import java.io.IOException;
  62. import java.io.PrintWriter;
  63. import java.io.UnsupportedEncodingException;
  64. import java.util.Locale;
  65. /**
  66.  * Defines an object to assist a servlet in sending a response to the client.
  67.  * The servlet container creates a <code>ServletResponse</code> object and
  68.  * passes it as an argument to the servlet's <code>service</code> method.
  69.  *
  70.  * <p>To send binary data in a MIME body response, use
  71.  * the {@link ServletOutputStream} returned by {@link #getOutputStream}.
  72.  * To send character data, use the <code>PrintWriter</code> object 
  73.  * returned by {@link #getWriter}. To mix binary and text data,
  74.  * for example, to create a multipart response, use a
  75.  * <code>ServletOutputStream</code> and manage the character sections
  76.  * manually.
  77.  *
  78.  * <p>The charset for the MIME body response can be specified with 
  79.  * {@link #setContentType}.  For example, "text/html; charset=Shift_JIS".
  80.  * The charset can alternately be set using {@link #setLocale}.
  81.  * If no charset is specified, ISO-8859-1 will be used.  
  82.  * The <code>setContentType</code> or <code>setLocale</code> method 
  83.  * must be called before <code>getWriter</code> for the charset to 
  84.  * affect the construction of the writer.
  85.  * 
  86.  * <p>See the Internet RFCs such as 
  87.  * <a href="http://info.internet.isi.edu/in-notes/rfc/files/rfc2045.txt">
  88.  * RFC 2045</a> for more information on MIME. Protocols such as SMTP
  89.  * and HTTP define profiles of MIME, and those standards
  90.  * are still evolving.
  91.  *
  92.  * @author  Various
  93.  * @version  $Version$
  94.  *
  95.  * @see ServletOutputStream
  96.  *
  97.  */
  98.  
  99. public interface ServletResponse {
  100.     
  101.     /**
  102.      * Returns the name of the charset used for
  103.      * the MIME body sent in this response.
  104.      *
  105.      * <p>If no charset has been assigned, it is implicitly
  106.      * set to <code>ISO-8859-1</code> (<code>Latin-1</code>).
  107.      *
  108.      * <p>See RFC 2047 (http://ds.internic.net/rfc/rfc2045.txt)
  109.      * for more information about character encoding and MIME.
  110.      *
  111.      * @return a <code>String</code> specifying the
  112.      * name of the charset, for
  113.      * example, <code>ISO-8859-1</code>
  114.      *
  115.      */
  116.   
  117.     public String getCharacterEncoding();
  118.     
  119.     
  120.     /**
  121.      * Returns a {@link ServletOutputStream} suitable for writing binary 
  122.      * data in the response. The servlet container does not encode the
  123.      * binary data.  Either this method or {@link #getWriter} may 
  124.      * be called to write the body, not both.
  125.      *
  126.      * @return a {@link ServletOutputStream} for writing binary data
  127.      *
  128.      * @exception IllegalStateException if the <code>getWriter</code> method
  129.      *  has been called on this response
  130.      *
  131.      * @exception IOException  if an input or output exception occurred
  132.      *
  133.      * @see  #getWriter
  134.      *
  135.      */
  136.     public ServletOutputStream getOutputStream() throws IOException;
  137.     
  138.     
  139.     /**
  140.      * Returns a <code>PrintWriter</code> object that 
  141.      * can send character text to the client. 
  142.      * The character encoding used is the one specified 
  143.      * in the <code>charset=</code> property of the
  144.      * {@link #setContentType} method, which must be called
  145.      * <i>before</i> calling this method for the charset to take effect. 
  146.      *
  147.      * <p>If necessary, the MIME type of the response is 
  148.      * modified to reflect the character encoding used.
  149.      *
  150.      * <p>Either this method or {@link #getOutputStream} may be called
  151.      * to write the body, not both.
  152.      *
  153.      * 
  154.      * @return  a <code>PrintWriter</code> object that 
  155.      * can return character data to the client 
  156.      *
  157.      * @exception UnsupportedEncodingException  if the charset specified in
  158.      * <code>setContentType</code> cannot be
  159.      * used
  160.      *
  161.      * @exception IllegalStateException     if the <code>getOutputStream</code>
  162.      *  method has already been called for this 
  163.      * response object
  164.      *
  165.      * @exception IOException    if an input or output exception occurred
  166.      *
  167.      * @see  #getOutputStream
  168.      * @see  #setContentType
  169.      *
  170.      */
  171.     public PrintWriter getWriter() throws IOException;
  172.     
  173.     
  174.     
  175.     
  176.     /**
  177.      * Sets the length of the content body in the response
  178.      * In HTTP servlets, this method sets the HTTP Content-Length header.
  179.      *
  180.      *
  181.      * @param len  an integer specifying the length of the 
  182.      *  content being returned to the client; sets
  183.      * the Content-Length header
  184.      *
  185.      */
  186.     public void setContentLength(int len);
  187.     
  188.     
  189.     /**
  190.      * Sets the content type of the response being sent to
  191.      * the client. The content type may include the type of character
  192.      * encoding used, for example, <code>text/html; charset=ISO-8859-4</code>.
  193.      *
  194.      * <p>If obtaining a <code>PrintWriter</code>, this method should be 
  195.      * called first.
  196.      *
  197.      *
  198.      * @param type  a <code>String</code> specifying the MIME 
  199.      * type of the content
  200.      *
  201.      * @see  #getOutputStream
  202.      * @see  #getWriter
  203.      *
  204.      */
  205.     public void setContentType(String type);
  206.     
  207.     /**
  208.      * Sets the preferred buffer size for the body of the response.  
  209.      * The servlet container will use a buffer at least as large as 
  210.      * the size requested.  The actual buffer size used can be found
  211.      * using <code>getBufferSize</code>.
  212.      *
  213.      * <p>A larger buffer allows more content to be written before anything is
  214.      * actually sent, thus providing the servlet with more time to set
  215.      * appropriate status codes and headers.  A smaller buffer decreases 
  216.      * server memory load and allows the client to start receiving data more
  217.      * quickly.
  218.      *
  219.      * <p>This method must be called before any response body content is
  220.      * written; if content has been written, this method throws an 
  221.      * <code>IllegalStateException</code>.
  222.      *
  223.      * @param size  the preferred buffer size
  224.      *
  225.      * @exception  IllegalStateException   if this method is called after
  226.      * content has been written
  227.      *
  228.      * @see  #getBufferSize
  229.      * @see  #flushBuffer
  230.      * @see  #isCommitted
  231.      * @see  #reset
  232.      *
  233.      */
  234.     public void setBufferSize(int size);
  235.     
  236.     
  237.     /**
  238.      * Returns the actual buffer size used for the response.  If no buffering
  239.      * is used, this method returns 0.
  240.      *
  241.      * @return   the actual buffer size used
  242.      *
  243.      * @see  #setBufferSize
  244.      * @see  #flushBuffer
  245.      * @see  #isCommitted
  246.      * @see  #reset
  247.      *
  248.      */
  249.     public int getBufferSize();
  250.     
  251.     
  252.     /**
  253.      * Forces any content in the buffer to be written to the client.  A call
  254.      * to this method automatically commits the response, meaning the status 
  255.      * code and headers will be written.
  256.      *
  257.      * @see  #setBufferSize
  258.      * @see  #getBufferSize
  259.      * @see  #isCommitted
  260.      * @see  #reset
  261.      *
  262.      */
  263.     public void flushBuffer() throws IOException;
  264.     
  265.     
  266.     /**
  267.      * Returns a boolean indicating if the response has been
  268.      * committed.  A commited response has already had its status 
  269.      * code and headers written.
  270.      *
  271.      * @return a boolean indicating if the response has been
  272.      *   committed
  273.      *
  274.      * @see  #setBufferSize
  275.      * @see  #getBufferSize
  276.      * @see  #flushBuffer
  277.      * @see  #reset
  278.      *
  279.      */
  280.     public boolean isCommitted();
  281.     
  282.     
  283.     /**
  284.      * Clears any data that exists in the buffer as well as the status code and
  285.      * headers.  If the response has been committed, this method throws an 
  286.      * <code>IllegalStateException</code>.
  287.      *
  288.      * @exception IllegalStateException  if the response has already been
  289.      *                                   committed
  290.      *
  291.      * @see  #setBufferSize
  292.      * @see  #getBufferSize
  293.      * @see  #flushBuffer
  294.      * @see  #isCommitted
  295.      *
  296.      */
  297.     public void reset();
  298.     
  299.     
  300.     /**
  301.      * Sets the locale of the response, setting the headers (including the
  302.      * Content-Type's charset) as appropriate.  This method should be called
  303.      * before a call to {@link #getWriter}.  By default, the response locale
  304.      * is the default locale for the server.
  305.      * 
  306.      * @param loc  the locale of the response
  307.      *
  308.      * @see  #getLocale
  309.      *
  310.      */
  311.     public void setLocale(Locale loc);
  312.     
  313.     
  314.     /**
  315.      * Returns the locale assigned to the response.
  316.      * 
  317.      * 
  318.      * @see  #setLocale
  319.      *
  320.      */
  321.     public Locale getLocale();
  322. }