2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 package javax.servlet;
19 import java.io.IOException;
20 import java.io.PrintWriter;
21 import java.util.Locale;
24 * Defines an object to assist a servlet in sending a response to the client.
25 * The servlet container creates a <code>ServletResponse</code> object and
26 * passes it as an argument to the servlet's <code>service</code> method.
28 * To send binary data in a MIME body response, use the
29 * {@link ServletOutputStream} returned by {@link #getOutputStream}. To send
30 * character data, use the <code>PrintWriter</code> object returned by
31 * {@link #getWriter}. To mix binary and text data, for example, to create a
32 * multipart response, use a <code>ServletOutputStream</code> and manage the
33 * character sections manually.
35 * The charset for the MIME body response can be specified explicitly using the
36 * {@link #setCharacterEncoding} and {@link #setContentType} methods, or
37 * implicitly using the {@link #setLocale} method. Explicit specifications take
38 * precedence over implicit specifications. If no charset is specified,
39 * ISO-8859-1 will be used. The <code>setCharacterEncoding</code>,
40 * <code>setContentType</code>, or <code>setLocale</code> method must be called
41 * before <code>getWriter</code> and before committing the response for the
42 * character encoding to be used.
44 * See the Internet RFCs such as <a href="http://www.ietf.org/rfc/rfc2045.txt">
45 * RFC 2045</a> for more information on MIME. Protocols such as SMTP and HTTP
46 * define profiles of MIME, and those standards are still evolving.
48 * @see ServletOutputStream
50 public interface ServletResponse {
53 * Returns the name of the character encoding (MIME charset) used for the
54 * body sent in this response. The character encoding may have been
55 * specified explicitly using the {@link #setCharacterEncoding} or
56 * {@link #setContentType} methods, or implicitly using the
57 * {@link #setLocale} method. Explicit specifications take precedence over
58 * implicit specifications. Calls made to these methods after
59 * <code>getWriter</code> has been called or after the response has been
60 * committed have no effect on the character encoding. If no character
61 * encoding has been specified, <code>ISO-8859-1</code> is returned.
63 * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information
64 * about character encoding and MIME.
66 * @return a <code>String</code> specifying the name of the character
67 * encoding, for example, <code>UTF-8</code>
69 public String getCharacterEncoding();
72 * Returns the content type used for the MIME body sent in this response.
73 * The content type proper must have been specified using
74 * {@link #setContentType} before the response is committed. If no content
75 * type has been specified, this method returns null. If a content type has
76 * been specified and a character encoding has been explicitly or implicitly
77 * specified as described in {@link #getCharacterEncoding}, the charset
78 * parameter is included in the string returned. If no character encoding
79 * has been specified, the charset parameter is omitted.
81 * @return a <code>String</code> specifying the content type, for example,
82 * <code>text/html; charset=UTF-8</code>, or null
85 public String getContentType();
88 * Returns a {@link ServletOutputStream} suitable for writing binary data in
89 * the response. The servlet container does not encode the binary data.
91 * Calling flush() on the ServletOutputStream commits the response. Either
92 * this method or {@link #getWriter} may be called to write the body, not
95 * @return a {@link ServletOutputStream} for writing binary data
96 * @exception IllegalStateException
97 * if the <code>getWriter</code> method has been called on
99 * @exception IOException
100 * if an input or output exception occurred
103 public ServletOutputStream getOutputStream() throws IOException;
106 * Returns a <code>PrintWriter</code> object that can send character text to
107 * the client. The <code>PrintWriter</code> uses the character encoding
108 * returned by {@link #getCharacterEncoding}. If the response's character
109 * encoding has not been specified as described in
110 * <code>getCharacterEncoding</code> (i.e., the method just returns the
111 * default value <code>ISO-8859-1</code>), <code>getWriter</code> updates it
112 * to <code>ISO-8859-1</code>.
114 * Calling flush() on the <code>PrintWriter</code> commits the response.
116 * Either this method or {@link #getOutputStream} may be called to write the
119 * @return a <code>PrintWriter</code> object that can return character data
121 * @exception java.io.UnsupportedEncodingException
122 * if the character encoding returned by
123 * <code>getCharacterEncoding</code> cannot be used
124 * @exception IllegalStateException
125 * if the <code>getOutputStream</code> method has already
126 * been called for this response object
127 * @exception IOException
128 * if an input or output exception occurred
129 * @see #getOutputStream
130 * @see #setCharacterEncoding
132 public PrintWriter getWriter() throws IOException;
135 * Sets the character encoding (MIME charset) of the response being sent to
136 * the client, for example, to UTF-8. If the character encoding has already
137 * been set by {@link #setContentType} or {@link #setLocale}, this method
138 * overrides it. Calling {@link #setContentType} with the
139 * <code>String</code> of <code>text/html</code> and calling this method
140 * with the <code>String</code> of <code>UTF-8</code> is equivalent with
141 * calling <code>setContentType</code> with the <code>String</code> of
142 * <code>text/html; charset=UTF-8</code>.
144 * This method can be called repeatedly to change the character encoding.
145 * This method has no effect if it is called after <code>getWriter</code>
146 * has been called or after the response has been committed.
148 * Containers must communicate the character encoding used for the servlet
149 * response's writer to the client if the protocol provides a way for doing
150 * so. In the case of HTTP, the character encoding is communicated as part
151 * of the <code>Content-Type</code> header for text media types. Note that
152 * the character encoding cannot be communicated via HTTP headers if the
153 * servlet does not specify a content type; however, it is still used to
154 * encode text written via the servlet response's writer.
157 * a String specifying only the character set defined by IANA
159 * (http://www.iana.org/assignments/character-sets)
160 * @see #setContentType #setLocale
163 public void setCharacterEncoding(String charset);
166 * Sets the length of the content body in the response In HTTP servlets,
167 * this method sets the HTTP Content-Length header.
170 * an integer specifying the length of the content being returned
171 * to the client; sets the Content-Length header
173 public void setContentLength(int len);
178 public void setContentLengthLong(long length);
181 * Sets the content type of the response being sent to the client, if the
182 * response has not been committed yet. The given content type may include a
183 * character encoding specification, for example,
184 * <code>text/html;charset=UTF-8</code>. The response's character encoding
185 * is only set from the given content type if this method is called before
186 * <code>getWriter</code> is called.
188 * This method may be called repeatedly to change content type and character
189 * encoding. This method has no effect if called after the response has been
190 * committed. It does not set the response's character encoding if it is
191 * called after <code>getWriter</code> has been called or after the response
192 * has been committed.
194 * Containers must communicate the content type and the character encoding
195 * used for the servlet response's writer to the client if the protocol
196 * provides a way for doing so. In the case of HTTP, the
197 * <code>Content-Type</code> header is used.
200 * a <code>String</code> specifying the MIME type of the content
202 * @see #setCharacterEncoding
203 * @see #getOutputStream
206 public void setContentType(String type);
209 * Sets the preferred buffer size for the body of the response. The servlet
210 * container will use a buffer at least as large as the size requested. The
211 * actual buffer size used can be found using <code>getBufferSize</code>.
213 * A larger buffer allows more content to be written before anything is
214 * actually sent, thus providing the servlet with more time to set
215 * appropriate status codes and headers. A smaller buffer decreases server
216 * memory load and allows the client to start receiving data more quickly.
218 * This method must be called before any response body content is written;
219 * if content has been written or the response object has been committed,
220 * this method throws an <code>IllegalStateException</code>.
223 * the preferred buffer size
224 * @exception IllegalStateException
225 * if this method is called after content has been written
226 * @see #getBufferSize
231 public void setBufferSize(int size);
234 * Returns the actual buffer size used for the response. If no buffering is
235 * used, this method returns 0.
237 * @return the actual buffer size used
238 * @see #setBufferSize
243 public int getBufferSize();
246 * Forces any content in the buffer to be written to the client. A call to
247 * this method automatically commits the response, meaning the status code
248 * and headers will be written.
250 * @see #setBufferSize
251 * @see #getBufferSize
255 public void flushBuffer() throws IOException;
258 * Clears the content of the underlying buffer in the response without
259 * clearing headers or status code. If the response has been committed, this
260 * method throws an <code>IllegalStateException</code>.
262 * @see #setBufferSize
263 * @see #getBufferSize
268 public void resetBuffer();
271 * Returns a boolean indicating if the response has been committed. A
272 * committed response has already had its status code and headers written.
274 * @return a boolean indicating if the response has been committed
275 * @see #setBufferSize
276 * @see #getBufferSize
280 public boolean isCommitted();
283 * Clears any data that exists in the buffer as well as the status code and
284 * headers. If the response has been committed, this method throws an
285 * <code>IllegalStateException</code>.
287 * @exception IllegalStateException
288 * if the response has already been committed
289 * @see #setBufferSize
290 * @see #getBufferSize
297 * Sets the locale of the response, if the response has not been committed
298 * yet. It also sets the response's character encoding appropriately for the
299 * locale, if the character encoding has not been explicitly set using
300 * {@link #setContentType} or {@link #setCharacterEncoding},
301 * <code>getWriter</code> hasn't been called yet, and the response hasn't
302 * been committed yet. If the deployment descriptor contains a
303 * <code>locale-encoding-mapping-list</code> element, and that element
304 * provides a mapping for the given locale, that mapping is used. Otherwise,
305 * the mapping from locale to character encoding is container dependent.
307 * This method may be called repeatedly to change locale and character
308 * encoding. The method has no effect if called after the response has been
309 * committed. It does not set the response's character encoding if it is
310 * called after {@link #setContentType} has been called with a charset
311 * specification, after {@link #setCharacterEncoding} has been called, after
312 * <code>getWriter</code> has been called, or after the response has been
315 * Containers must communicate the locale and the character encoding used
316 * for the servlet response's writer to the client if the protocol provides
317 * a way for doing so. In the case of HTTP, the locale is communicated via
318 * the <code>Content-Language</code> header, the character encoding as part
319 * of the <code>Content-Type</code> header for text media types. Note that
320 * the character encoding cannot be communicated via HTTP headers if the
321 * servlet does not specify a content type; however, it is still used to
322 * encode text written via the servlet response's writer.
325 * the locale of the response
327 * @see #setContentType
328 * @see #setCharacterEncoding
330 public void setLocale(Locale loc);
333 * Returns the locale specified for this response using the
334 * {@link #setLocale} method. Calls made to <code>setLocale</code> after the
335 * response is committed have no effect. If no locale has been specified,
336 * the container's default locale is returned.
340 public Locale getLocale();