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