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