001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet; 027 028 import java.io.IOException; 029 import java.io.PrintWriter; 030 import java.util.Locale; 031 032 033 /** 034 * Defines an object to assist a servlet in sending a response to the client. 035 * The servlet container creates a <code>ServletResponse</code> object and 036 * passes it as an argument to the servlet's <code>service</code> method. 037 * 038 * <p>To send binary data in a MIME body response, use 039 * the {@link ServletOutputStream} returned by {@link #getOutputStream}. 040 * To send character data, use the <code>PrintWriter</code> object 041 * returned by {@link #getWriter}. To mix binary and text data, 042 * for example, to create a multipart response, use a 043 * <code>ServletOutputStream</code> and manage the character sections 044 * manually. 045 * 046 * <p>The charset for the MIME body response can be specified 047 * explicitly using the {@link #setCharacterEncoding} and 048 * {@link #setContentType} methods, or implicitly 049 * using the {@link #setLocale} method. 050 * Explicit specifications take precedence over 051 * implicit specifications. If no charset is specified, ISO-8859-1 will be 052 * used. The <code>setCharacterEncoding</code>, 053 * <code>setContentType</code>, or <code>setLocale</code> method must 054 * be called before <code>getWriter</code> and before committing 055 * the response for the character encoding to be used. 056 * 057 * <p>See the Internet RFCs such as 058 * <a href="http://www.ietf.org/rfc/rfc2045.txt"> 059 * RFC 2045</a> for more information on MIME. Protocols such as SMTP 060 * and HTTP define profiles of MIME, and those standards 061 * are still evolving. 062 * 063 * @see ServletOutputStream 064 * 065 * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $ 066 */ 067 public interface ServletResponse { 068 /** 069 * Returns the name of the character encoding (MIME charset) 070 * used for the body sent in this response. 071 * The character encoding may have been specified explicitly 072 * using the {@link #setCharacterEncoding} or 073 * {@link #setContentType} methods, or implicitly using the 074 * {@link #setLocale} method. Explicit specifications take 075 * precedence over implicit specifications. Calls made 076 * to these methods after <code>getWriter</code> has been 077 * called or after the response has been committed have no 078 * effect on the character encoding. If no character encoding 079 * has been specified, <code>ISO-8859-1</code> is returned. 080 * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) 081 * for more information about character encoding and MIME. 082 * 083 * @return a <code>String</code> specifying the 084 * name of the character encoding, for example, <code>UTF-8</code> 085 */ 086 public String getCharacterEncoding(); 087 088 /** 089 * Returns the content type used for the MIME body 090 * sent in this response. The content type proper must 091 * have been specified using {@link #setContentType} 092 * before the response is committed. If no content type 093 * has been specified, this method returns null. 094 * If a content type has been specified and a 095 * character encoding has been explicitly or implicitly 096 * specified as described in {@link #getCharacterEncoding}, 097 * the charset parameter is included in the string returned. 098 * If no character encoding has been specified, the 099 * charset parameter is omitted. 100 * 101 * @return a <code>String</code> specifying the 102 * 103 * content type, for example, <code>text/html; charset=UTF-8</code>, 104 * or null 105 * 106 * @since Servlet 2.4 107 */ 108 public String getContentType(); 109 110 /** 111 * Returns a {@link ServletOutputStream} suitable for writing binary 112 * data in the response. The servlet container does not encode the 113 * binary data. 114 * 115 * <p> Calling flush() on the ServletOutputStream commits the response. 116 * 117 * Either this method or {@link #getWriter} may 118 * be called to write the body, not both. 119 * 120 * @return a {@link ServletOutputStream} for writing binary data 121 * 122 * @exception IllegalStateException if the <code>getWriter</code> method 123 * has been called on this response 124 * 125 * @exception IOException if an input or output exception occurred 126 * 127 * @see #getWriter 128 */ 129 public ServletOutputStream getOutputStream() throws IOException; 130 131 /** 132 * Returns a <code>PrintWriter</code> object that 133 * can send character text to the client. 134 * The <code>PrintWriter</code> uses the character 135 * encoding returned by {@link #getCharacterEncoding}. 136 * If the response's character encoding has not been 137 * specified as described in <code>getCharacterEncoding</code> 138 * (i.e., the method just returns the default value 139 * <code>ISO-8859-1</code>), <code>getWriter</code> 140 * updates it to <code>ISO-8859-1</code>. 141 * <p>Calling flush() on the <code>PrintWriter</code> 142 * commits the response. 143 * <p>Either this method or {@link #getOutputStream} may be called 144 * to write the body, not both. 145 * 146 * @return a <code>PrintWriter</code> object that 147 * can return character data to the client 148 * 149 * @exception UnsupportedEncodingException if the character encoding 150 * returned by <code>getCharacterEncoding</code> cannot be used 151 * 152 * @exception IllegalStateException if the <code>getOutputStream</code> 153 * method has already been called for this response object 154 * 155 * @exception IOException if an input or output exception occurred 156 * 157 * @see #getOutputStream 158 * @see #setCharacterEncoding 159 */ 160 public PrintWriter getWriter() throws IOException; 161 162 163 /** 164 * Sets the character encoding (MIME charset) of the response 165 * being sent to the client, for example, to UTF-8. 166 * If the character encoding has already been set by 167 * {@link #setContentType} or {@link #setLocale}, 168 * this method overrides it. 169 * Calling {@link #setContentType} with the <code>String</code> 170 * of <code>text/html</code> and calling 171 * this method with the <code>String</code> of <code>UTF-8</code> 172 * is equivalent with calling 173 * <code>setContentType</code> with the <code>String</code> of 174 * <code>text/html; charset=UTF-8</code>. 175 * <p>This method can be called repeatedly to change the character 176 * encoding. 177 * This method has no effect if it is called after 178 * <code>getWriter</code> has been 179 * called or after the response has been committed. 180 * <p>Containers must communicate the character encoding used for 181 * the servlet response's writer to the client if the protocol 182 * provides a way for doing so. In the case of HTTP, the character 183 * encoding is communicated as part of the <code>Content-Type</code> 184 * header for text media types. Note that the character encoding 185 * cannot be communicated via HTTP headers if the servlet does not 186 * specify a content type; however, it is still used to encode text 187 * written via the servlet response's writer. 188 * 189 * @param charset a String specifying only the character set 190 * defined by IANA Character Sets 191 * (http://www.iana.org/assignments/character-sets) 192 * 193 * @see #setContentType 194 * @see #setLocale 195 * 196 * @since Servlet 2.4 197 */ 198 public void setCharacterEncoding(String charset); 199 200 /** 201 * Sets the length of the content body in the response 202 * In HTTP servlets, this method sets the HTTP Content-Length header. 203 * 204 * @param len an integer specifying the length of the 205 * content being returned to the client; sets 206 * the Content-Length header 207 */ 208 public void setContentLength(int len); 209 210 /** 211 * Sets the content type of the response being sent to 212 * the client, if the response has not been committed yet. 213 * The given content type may include a character encoding 214 * specification, for example, <code>text/html;charset=UTF-8</code>. 215 * The response's character encoding is only set from the given 216 * content type if this method is called before <code>getWriter</code> 217 * is called. 218 * <p>This method may be called repeatedly to change content type and 219 * character encoding. 220 * This method has no effect if called after the response 221 * has been committed. It does not set the response's character 222 * encoding if it is called after <code>getWriter</code> 223 * has been called or after the response has been committed. 224 * <p>Containers must communicate the content type and the character 225 * encoding used for the servlet response's writer to the client if 226 * the protocol provides a way for doing so. In the case of HTTP, 227 * the <code>Content-Type</code> header is used. 228 * 229 * @param type a <code>String</code> specifying the MIME 230 * type of the content 231 * 232 * @see #setLocale 233 * @see #setCharacterEncoding 234 * @see #getOutputStream 235 * @see #getWriter 236 */ 237 public void setContentType(String type); 238 239 /** 240 * Sets the preferred buffer size for the body of the response. 241 * The servlet container will use a buffer at least as large as 242 * the size requested. The actual buffer size used can be found 243 * using <code>getBufferSize</code>. 244 * 245 * <p>A larger buffer allows more content to be written before anything is 246 * actually sent, thus providing the servlet with more time to set 247 * appropriate status codes and headers. A smaller buffer decreases 248 * server memory load and allows the client to start receiving data more 249 * quickly. 250 * 251 * <p>This method must be called before any response body content is 252 * written; if content has been written or the response object has 253 * been committed, this method throws an 254 * <code>IllegalStateException</code>. 255 * 256 * @param size the preferred buffer size 257 * 258 * @exception IllegalStateException if this method is called after 259 * content has been written 260 * 261 * @see #getBufferSize 262 * @see #flushBuffer 263 * @see #isCommitted 264 * @see #reset 265 */ 266 public void setBufferSize(int size); 267 268 /** 269 * Returns the actual buffer size used for the response. If no buffering 270 * is used, this method returns 0. 271 * 272 * @return the actual buffer size used 273 * 274 * @see #setBufferSize 275 * @see #flushBuffer 276 * @see #isCommitted 277 * @see #reset 278 */ 279 public int getBufferSize(); 280 281 /** 282 * Forces any content in the buffer to be written to the client. A call 283 * to this method automatically commits the response, meaning the status 284 * code and headers will be written. 285 * 286 * @see #setBufferSize 287 * @see #getBufferSize 288 * @see #isCommitted 289 * @see #reset 290 */ 291 public void flushBuffer() throws IOException; 292 293 /** 294 * Clears the content of the underlying buffer in the response without 295 * clearing headers or status code. If the 296 * response has been committed, this method throws an 297 * <code>IllegalStateException</code>. 298 * 299 * @see #setBufferSize 300 * @see #getBufferSize 301 * @see #isCommitted 302 * @see #reset 303 * 304 * @since Servlet 2.3 305 */ 306 public void resetBuffer(); 307 308 /** 309 * Returns a boolean indicating if the response has been 310 * committed. A commited response has already had its status 311 * code and headers written. 312 * 313 * @return a boolean indicating if the response has been committed 314 * 315 * @see #setBufferSize 316 * @see #getBufferSize 317 * @see #flushBuffer 318 * @see #reset 319 */ 320 public boolean isCommitted(); 321 322 /** 323 * Clears any data that exists in the buffer as well as the status code and 324 * headers. If the response has been committed, this method throws an 325 * <code>IllegalStateException</code>. 326 * 327 * @exception IllegalStateException if the response has already been 328 * committed 329 * 330 * @see #setBufferSize 331 * @see #getBufferSize 332 * @see #flushBuffer 333 * @see #isCommitted 334 */ 335 public void reset(); 336 337 /** 338 * Sets the locale of the response, if the response has not been 339 * committed yet. It also sets the response's character encoding 340 * appropriately for the locale, if the character encoding has not 341 * been explicitly set using {@link #setContentType} or 342 * {@link #setCharacterEncoding}, <code>getWriter</code> hasn't 343 * been called yet, and the response hasn't been committed yet. 344 * If the deployment descriptor contains a 345 * <code>locale-encoding-mapping-list</code> element, and that 346 * element provides a mapping for the given locale, that mapping 347 * is used. Otherwise, the mapping from locale to character 348 * encoding is container dependent. 349 * <p>This method may be called repeatedly to change locale and 350 * character encoding. The method has no effect if called after the 351 * response has been committed. It does not set the response's 352 * character encoding if it is called after {@link #setContentType} 353 * has been called with a charset specification, after 354 * {@link #setCharacterEncoding} has been called, after 355 * <code>getWriter</code> has been called, or after the response 356 * has been committed. 357 * <p>Containers must communicate the locale and the character encoding 358 * used for the servlet response's writer to the client if the protocol 359 * provides a way for doing so. In the case of HTTP, the locale is 360 * communicated via the <code>Content-Language</code> header, 361 * the character encoding as part of the <code>Content-Type</code> 362 * header for text media types. Note that the character encoding 363 * cannot be communicated via HTTP headers if the servlet does not 364 * specify a content type; however, it is still used to encode text 365 * written via the servlet response's writer. 366 * 367 * @param loc the locale of the response 368 * 369 * @see #getLocale 370 * @see #setContentType 371 * @see #setCharacterEncoding 372 */ 373 public void setLocale(Locale loc); 374 375 /** 376 * Returns the locale specified for this response 377 * using the {@link #setLocale} method. Calls made to 378 * <code>setLocale</code> after the response is committed 379 * have no effect. If no locale has been specified, 380 * the container's default locale is returned. 381 * 382 * @see #setLocale 383 */ 384 public Locale getLocale(); 385 } 386 387 388 389 390