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