home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / ServletResponse.java < prev    next >
Text File  |  1998-04-21  |  5KB  |  125 lines
  1. /*
  2.  * @(#)ServletResponse.java    1.25 97/11/21
  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;
  23.  
  24. import java.io.IOException;
  25. import java.io.PrintWriter;
  26. import java.io.UnsupportedEncodingException;
  27.  
  28.  
  29. /**
  30.  * Interface for sending MIME data from the servlet's service method
  31.  * to the client.  Network service developers implement this interface;
  32.  * its methods are then used by servlets when the service method is
  33.  * run, to return data to clients.  The ServletResponse object is passed
  34.  * as an argument to the service method.
  35.  *
  36.  * <P> To write MIME bodies which consist of binary data, use the
  37.  * output stream returned by <code><em>getOutputStream</em></code>.  To
  38.  * write MIME bodies consisting of text data, use the writer returned
  39.  * by <code><em>getWriter</em></code>.  If you need to mix binary and
  40.  * text data, for example because you're creating a multipart response,
  41.  * use the output stream to write the multipart headers, and use that
  42.  * to build your own text bodies.
  43.  * 
  44.  * <p>If you don't explicitly set the character set in your MIME media
  45.  * type, with <code><em>setContentType</em></code>, one will be
  46.  * selected and the content type will be modified accordingly.  If you
  47.  * will be using a writer, and want to call the
  48.  * <code>setContentType</code> method, you must do so before calling
  49.  * the <code>getWriter</code> method. If you will be using the output
  50.  * stream, and want to call <code>setContentType</code>, you must do so
  51.  * before using the output stream to write the MIME body.
  52.  *
  53.  * <P> For more information about MIME, see the Internet RFCs such as
  54.  * <a href="http://info.internet.isi.edu/in-notes/rfc/files/rfc2045.txt">
  55.  * RFC 2045</a>, the first in a series which defines MIME.  Note that
  56.  * protocols such SMTP and HTTP define application-specific profiles of
  57.  * MIME, and that standards in this area are evolving.
  58.  * 
  59.  * @version 1.25, 11/21/97 */
  60.  
  61. public
  62. interface ServletResponse {
  63.     /**
  64.      * Sets the content length for this response.
  65.      *
  66.      * @param len the content length
  67.      */
  68.     public void setContentLength(int len);
  69.  
  70.     /**
  71.      * Sets the content type for this response.  This type may later
  72.      * be implicitly modified by addition of properties such as the MIME
  73.      * <em>charset=<value></em> if the service finds it necessary,
  74.      * and the appropriate media type property has not been set.
  75.      *
  76.      * <p>This response property may only be assigned one time.  If a
  77.      * writer is to be used to write a text response, this method must
  78.      * be called before the method <code>getWriter</code>.  If an
  79.      * output stream will be used to write a response, this method must
  80.      * be called before the output stream is used to write response
  81.      * data.
  82.      *
  83.      * @param type the content's MIME type
  84.      * @see getOutputStream
  85.      * @see getWriter */
  86.     public void setContentType(String type);
  87.  
  88.     /**
  89.      * Returns an output stream for writing binary response data.
  90.      *
  91.      * @see getWriter
  92.      * @exception IllegalStateException if getWriter has been
  93.      *    called on this same request.
  94.      * @exception IOException if an I/O exception has occurred
  95.      */
  96.     public ServletOutputStream getOutputStream() throws IOException;
  97.  
  98.     /**
  99.      * Returns a print writer for writing formatted text responses.  The
  100.      * MIME type of the response will be modified, if necessary, to reflect
  101.      * the character encoding used, through the <em>charset=...</em>
  102.      * property.  This means that the content type must be set before
  103.      * calling this method.
  104.      *
  105.      * @see getOutputStream
  106.      * @see setContentType
  107.      *
  108.      * @exception UnsupportedEncodingException if no such encoding can
  109.      * be provided
  110.      * @exception IllegalStateException if getOutputStream has been
  111.      *    called on this same request.
  112.      * @exception IOException on other errors.
  113.      */
  114.     public PrintWriter getWriter () throws IOException;
  115.  
  116.     /**
  117.      * Returns the character set encoding used for this MIME body.
  118.      * The character encoding is either the one specified in the
  119.      * assigned content type, or one which the client understands.
  120.      * If no content type has yet been assigned, it is implicitly
  121.      * set to <em>text/plain</em>
  122.      */
  123.     public String getCharacterEncoding ();
  124. }
  125.