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