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