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