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