View Javadoc

    1
    2
    3   /*
    4    * The contents of this file are subject to the terms
    5    * of the Common Development and Distribution License
    6    * (the "License").  You may not use this file except
    7    * in compliance with the License.
    8    *
    9    * You can obtain a copy of the license at
    10   * glassfish/bootstrap/legal/CDDLv1.0.txt or
    11   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
    12   * See the License for the specific language governing
    13   * permissions and limitations under the License.
    14   *
    15   * When distributing Covered Code, include this CDDL
    16   * HEADER in each file and include the License file at
    17   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable,
    18   * add the following below this CDDL HEADER, with the
    19   * fields enclosed by brackets "[]" replaced with your
    20   * own identifying information: Portions Copyright [yyyy]
    21   * [name of copyright owner]
    22   *
    23   * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
    24   *
    25   * Portions Copyright Apache Software Foundation.
    26   */
    27
    28  package javax.servlet;
    29
    30  import java.io.IOException;
    31  import java.io.PrintWriter;
    32  import java.util.Locale;
    33
    34
    35  /**
    36   * Defines an object to assist a servlet in sending a response to the client.
    37   * The servlet container creates a <code>ServletResponse</code> object and
    38   * passes it as an argument to the servlet's <code>service</code> method.
    39   *
    40   * <p>To send binary data in a MIME body response, use
    41   * the {@link ServletOutputStream} returned by {@link #getOutputStream}.
    42   * To send character data, use the <code>PrintWriter</code> object
    43   * returned by {@link #getWriter}. To mix binary and text data,
    44   * for example, to create a multipart response, use a
    45   * <code>ServletOutputStream</code> and manage the character sections
    46   * manually.
    47   *
    48   * <p>The charset for the MIME body response can be specified
    49   * explicitly using the {@link #setCharacterEncoding} and
    50   * {@link #setContentType} methods, or implicitly
    51   * using the {@link #setLocale} method.
    52   * Explicit specifications take precedence over
    53   * implicit specifications. If no charset is specified, ISO-8859-1 will be
    54   * used. The <code>setCharacterEncoding</code>,
    55   * <code>setContentType</code>, or <code>setLocale</code> method must
    56   * be called before <code>getWriter</code> and before committing
    57   * the response for the character encoding to be used.
    58   *
    59   * <p>See the Internet RFCs such as
    60   * <a href="http://www.ietf.org/rfc/rfc2045.txt">
    61   * RFC 2045</a> for more information on MIME. Protocols such as SMTP
    62   * and HTTP define profiles of MIME, and those standards
    63   * are still evolving.
    64   *
    65   * @author 	Various
    66   *
    67   * @see		ServletOutputStream
    68   *
    69   */
    70
    71  public interface ServletResponse {
    72
    73
    74
    75      /**
    76       * Returns the name of the character encoding (MIME charset)
    77       * used for the body sent in this response.
    78       * The character encoding may have been specified explicitly
    79       * using the {@link #setCharacterEncoding} or
    80       * {@link #setContentType} methods, or implicitly using the
    81       * {@link #setLocale} method. Explicit specifications take
    82       * precedence over implicit specifications. Calls made
    83       * to these methods after <code>getWriter</code> has been
    84       * called or after the response has been committed have no
    85       * effect on the character encoding. If no character encoding
    86       * has been specified, <code>ISO-8859-1</code> is returned.
    87       * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
    88       * for more information about character encoding and MIME.
    89       *
    90       * @return		a <code>String</code> specifying the
    91       *			name of the character encoding, for
    92       *			example, <code>UTF-8</code>
    93       *
    94       */
    95
    96      public String getCharacterEncoding();
    97
    98
    99
    100     /**
    101      * Returns the content type used for the MIME body
    102      * sent in this response. The content type proper must
    103      * have been specified using {@link #setContentType}
    104      * before the response is committed. If no content type
    105      * has been specified, this method returns null.
    106      * If a content type has been specified, and a
    107      * character encoding has been explicitly or implicitly
    108      * specified as described in {@link #getCharacterEncoding}
    109      * or {@link #getWriter} has been called,
    110      * the charset parameter is included in the string returned.
    111      * If no character encoding has been specified, the
    112      * charset parameter is omitted.
    113      *
    114      * @return		a <code>String</code> specifying the
    115      *			content type, for example,
    116      *			<code>text/html; charset=UTF-8</code>,
    117      *			or null
    118      *
    119      * @since 2.4
    120      */
    121
    122     public String getContentType();
    123
    124
    125
    126     /**
    127      * Returns a {@link ServletOutputStream} suitable for writing binary
    128      * data in the response. The servlet container does not encode the
    129      * binary data.
    130
    131      * <p> Calling flush() on the ServletOutputStream commits the response.
    132
    133      * Either this method or {@link #getWriter} may
    134      * be called to write the body, not both.
    135      *
    136      * @return				a {@link ServletOutputStream} for writing binary data
    137      *
    138      * @exception IllegalStateException if the <code>getWriter</code> method
    139      * 					has been called on this response
    140      *
    141      * @exception IOException 		if an input or output exception occurred
    142      *
    143      * @see 				#getWriter
    144      *
    145      */
    146
    147     public ServletOutputStream getOutputStream() throws IOException;
    148
    149
    150
    151     /**
    152      * Returns a <code>PrintWriter</code> object that
    153      * can send character text to the client.
    154      * The <code>PrintWriter</code> uses the character
    155      * encoding returned by {@link #getCharacterEncoding}.
    156      * If the response's character encoding has not been
    157      * specified as described in <code>getCharacterEncoding</code>
    158      * (i.e., the method just returns the default value
    159      * <code>ISO-8859-1</code>), <code>getWriter</code>
    160      * updates it to <code>ISO-8859-1</code>.
    161      * <p>Calling flush() on the <code>PrintWriter</code>
    162      * commits the response.
    163      * <p>Either this method or {@link #getOutputStream} may be called
    164      * to write the body, not both.
    165      *
    166      *
    167      * @return 		a <code>PrintWriter</code> object that
    168      *			can return character data to the client
    169      *
    170      * @exception UnsupportedEncodingException
    171      *			if the character encoding returned
    172      *			by <code>getCharacterEncoding</code> cannot be used
    173      *
    174      * @exception IllegalStateException
    175      *			if the <code>getOutputStream</code>
    176      * 			method has already been called for this
    177      *			response object
    178      *
    179      * @exception IOException
    180      *			if an input or output exception occurred
    181      *
    182      * @see 		#getOutputStream
    183      * @see 		#setCharacterEncoding
    184      *
    185      */
    186
    187     public PrintWriter getWriter() throws IOException;
    188
    189
    190
    191
    192     /**
    193      * Sets the character encoding (MIME charset) of the response
    194      * being sent to the client, for example, to UTF-8.
    195      * If the character encoding has already been set by
    196      * {@link #setContentType} or {@link #setLocale},
    197      * this method overrides it.
    198      * Calling {@link #setContentType} with the <code>String</code>
    199      * of <code>text/html</code> and calling
    200      * this method with the <code>String</code> of <code>UTF-8</code>
    201      * is equivalent with calling
    202      * <code>setContentType</code> with the <code>String</code> of
    203      * <code>text/html; charset=UTF-8</code>.
    204      * <p>This method can be called repeatedly to change the character
    205      * encoding.
    206      * This method has no effect if it is called after
    207      * <code>getWriter</code> has been
    208      * called or after the response has been committed.
    209      * <p>Containers must communicate the character encoding used for
    210      * the servlet response's writer to the client if the protocol
    211      * provides a way for doing so. In the case of HTTP, the character
    212      * encoding is communicated as part of the <code>Content-Type</code>
    213      * header for text media types. Note that the character encoding
    214      * cannot be communicated via HTTP headers if the servlet does not
    215      * specify a content type; however, it is still used to encode text
    216      * written via the servlet response's writer.
    217      *
    218      * @param charset 	a String specifying only the character set
    219      * 			defined by IANA Character Sets
    220      *			(http://www.iana.org/assignments/character-sets)
    221      *
    222      * @see		#setContentType
    223      * 			#setLocale
    224      *
    225      * @since 2.4
    226      *
    227      */
    228
    229     public void setCharacterEncoding(String charset);
    230
    231
    232
    233
    234     /**
    235      * Sets the length of the content body in the response
    236      * In HTTP servlets, this method sets the HTTP Content-Length header.
    237      *
    238      *
    239      * @param len 	an integer specifying the length of the
    240      * 			content being returned to the client; sets
    241      *			the Content-Length header
    242      *
    243      */
    244
    245     public void setContentLength(int len);
    246
    247
    248
    249     /**
    250      * Sets the content type of the response being sent to
    251      * the client, if the response has not been committed yet.
    252      * The given content type may include a character encoding
    253      * specification, for example, <code>text/html;charset=UTF-8</code>.
    254      * The response's character encoding is only set from the given
    255      * content type if this method is called before <code>getWriter</code>
    256      * is called.
    257      * <p>This method may be called repeatedly to change content type and
    258      * character encoding.
    259      * This method has no effect if called after the response
    260      * has been committed. It does not set the response's character
    261      * encoding if it is called after <code>getWriter</code>
    262      * has been called or after the response has been committed.
    263      * <p>Containers must communicate the content type and the character
    264      * encoding used for the servlet response's writer to the client if
    265      * the protocol provides a way for doing so. In the case of HTTP,
    266      * the <code>Content-Type</code> header is used.
    267      *
    268      * @param type 	a <code>String</code> specifying the MIME
    269      *			type of the content
    270      *
    271      * @see 		#setLocale
    272      * @see 		#setCharacterEncoding
    273      * @see 		#getOutputStream
    274      * @see 		#getWriter
    275      *
    276      */
    277
    278     public void setContentType(String type);
    279
    280
    281     /**
    282      * Sets the preferred buffer size for the body of the response.
    283      * The servlet container will use a buffer at least as large as
    284      * the size requested.  The actual buffer size used can be found
    285      * using <code>getBufferSize</code>.
    286      *
    287      * <p>A larger buffer allows more content to be written before anything is
    288      * actually sent, thus providing the servlet with more time to set
    289      * appropriate status codes and headers.  A smaller buffer decreases
    290      * server memory load and allows the client to start receiving data more
    291      * quickly.
    292      *
    293      * <p>This method must be called before any response body content is
    294      * written; if content has been written or the response object has
    295      * been committed, this method throws an
    296      * <code>IllegalStateException</code>.
    297      *
    298      * @param size 	the preferred buffer size
    299      *
    300      * @exception  IllegalStateException  	if this method is called after
    301      *						content has been written
    302      *
    303      * @see 		#getBufferSize
    304      * @see 		#flushBuffer
    305      * @see 		#isCommitted
    306      * @see 		#reset
    307      *
    308      */
    309
    310     public void setBufferSize(int size);
    311
    312
    313
    314     /**
    315      * Returns the actual buffer size used for the response.  If no buffering
    316      * is used, this method returns 0.
    317      *
    318      * @return	 	the actual buffer size used
    319      *
    320      * @see 		#setBufferSize
    321      * @see 		#flushBuffer
    322      * @see 		#isCommitted
    323      * @see 		#reset
    324      *
    325      */
    326
    327     public int getBufferSize();
    328
    329
    330
    331     /**
    332      * Forces any content in the buffer to be written to the client.  A call
    333      * to this method automatically commits the response, meaning the status
    334      * code and headers will be written.
    335      *
    336      * @see 		#setBufferSize
    337      * @see 		#getBufferSize
    338      * @see 		#isCommitted
    339      * @see 		#reset
    340      *
    341      */
    342
    343     public void flushBuffer() throws IOException;
    344
    345
    346
    347     /**
    348      * Clears the content of the underlying buffer in the response without
    349      * clearing headers or status code. If the
    350      * response has been committed, this method throws an
    351      * <code>IllegalStateException</code>.
    352      *
    353      * @see 		#setBufferSize
    354      * @see 		#getBufferSize
    355      * @see 		#isCommitted
    356      * @see 		#reset
    357      *
    358      * @since 2.3
    359      */
    360
    361     public void resetBuffer();
    362
    363
    364     /**
    365      * Returns a boolean indicating if the response has been
    366      * committed.  A committed response has already had its status
    367      * code and headers written.
    368      *
    369      * @return		a boolean indicating if the response has been
    370      *  		committed
    371      *
    372      * @see 		#setBufferSize
    373      * @see 		#getBufferSize
    374      * @see 		#flushBuffer
    375      * @see 		#reset
    376      *
    377      */
    378
    379     public boolean isCommitted();
    380
    381
    382
    383     /**
    384      * Clears any data that exists in the buffer as well as the status code and
    385      * headers.  If the response has been committed, this method throws an
    386      * <code>IllegalStateException</code>.
    387      *
    388      * @exception IllegalStateException  if the response has already been
    389      *                                   committed
    390      *
    391      * @see 		#setBufferSize
    392      * @see 		#getBufferSize
    393      * @see 		#flushBuffer
    394      * @see 		#isCommitted
    395      *
    396      */
    397
    398     public void reset();
    399
    400
    401
    402     /**
    403      * Sets the locale of the response, if the response has not been
    404      * committed yet. It also sets the response's character encoding
    405      * appropriately for the locale, if the character encoding has not
    406      * been explicitly set using {@link #setContentType} or
    407      * {@link #setCharacterEncoding}, <code>getWriter</code> hasn't
    408      * been called yet, and the response hasn't been committed yet.
    409      * If the deployment descriptor contains a
    410      * <code>locale-encoding-mapping-list</code> element, and that
    411      * element provides a mapping for the given locale, that mapping
    412      * is used. Otherwise, the mapping from locale to character
    413      * encoding is container dependent.
    414      * <p>This method may be called repeatedly to change locale and
    415      * character encoding. The method has no effect if called after the
    416      * response has been committed. It does not set the response's
    417      * character encoding if it is called after {@link #setContentType}
    418      * has been called with a charset specification, after
    419      * {@link #setCharacterEncoding} has been called, after
    420      * <code>getWriter</code> has been called, or after the response
    421      * has been committed.
    422      * <p>Containers must communicate the locale and the character encoding
    423      * used for the servlet response's writer to the client if the protocol
    424      * provides a way for doing so. In the case of HTTP, the locale is
    425      * communicated via the <code>Content-Language</code> header,
    426      * the character encoding as part of the <code>Content-Type</code>
    427      * header for text media types. Note that the character encoding
    428      * cannot be communicated via HTTP headers if the servlet does not
    429      * specify a content type; however, it is still used to encode text
    430      * written via the servlet response's writer.
    431      *
    432      * @param loc  the locale of the response
    433      *
    434      * @see 		#getLocale
    435      * @see 		#setContentType
    436      * @see 		#setCharacterEncoding
    437      *
    438      */
    439
    440     public void setLocale(Locale loc);
    441
    442
    443
    444     /**
    445      * Returns the locale specified for this response
    446      * using the {@link #setLocale} method. Calls made to
    447      * <code>setLocale</code> after the response is committed
    448      * have no effect. If no locale has been specified,
    449      * the container's default locale is returned.
    450      *
    451      * @see 		#setLocale
    452      *
    453      */
    454
    455     public Locale getLocale();
    456
    457
    458
    459 }
    460
    461
    462
    463
    464