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