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