View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
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.
16   */
17  
18  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet;
25  
26  import java.io.IOException;
27  import java.io.PrintWriter;
28  import java.util.Locale;
29  
30  
31  /**
32   * Defines an object to assist a servlet in sending a response to the client.
33   * The servlet container creates a <code>ServletResponse</code> object and
34   * passes it as an argument to the servlet's <code>service</code> method.
35   *
36   * <p>To send binary data in a MIME body response, use
37   * the {@link ServletOutputStream} returned by {@link #getOutputStream}.
38   * To send character data, use the <code>PrintWriter</code> object
39   * returned by {@link #getWriter}. To mix binary and text data,
40   * for example, to create a multipart response, use a
41   * <code>ServletOutputStream</code> and manage the character sections
42   * manually.
43   *
44   * <p>The charset for the MIME body response can be specified
45   * explicitly using the {@link #setCharacterEncoding} and
46   * {@link #setContentType} methods, or implicitly
47   * using the {@link #setLocale} method.
48   * Explicit specifications take precedence over
49   * implicit specifications. If no charset is specified, ISO-8859-1 will be
50   * used. The <code>setCharacterEncoding</code>,
51   * <code>setContentType</code>, or <code>setLocale</code> method must
52   * be called before <code>getWriter</code> and before committing
53   * the response for the character encoding to be used.
54   *
55   * <p>See the Internet RFCs such as
56   * <a href="http://www.ietf.org/rfc/rfc2045.txt">
57   * RFC 2045</a> for more information on MIME. Protocols such as SMTP
58   * and HTTP define profiles of MIME, and those standards
59   * are still evolving.
60   *
61   * @see ServletOutputStream
62   *
63   * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
64   */
65  public interface ServletResponse {
66      /**
67       * Returns the name of the character encoding (MIME charset)
68       * used for the body sent in this response.
69       * The character encoding may have been specified explicitly
70       * using the {@link #setCharacterEncoding} or
71       * {@link #setContentType} methods, or implicitly using the
72       * {@link #setLocale} method. Explicit specifications take
73       * precedence over implicit specifications. Calls made
74       * to these methods after <code>getWriter</code> has been
75       * called or after the response has been committed have no
76       * effect on the character encoding. If no character encoding
77       * has been specified, <code>ISO-8859-1</code> is returned.
78       * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
79       * for more information about character encoding and MIME.
80       *
81       * @return a <code>String</code> specifying the
82       * name of the character encoding, for example, <code>UTF-8</code>
83       */
84      public String getCharacterEncoding();
85  
86      /**
87       * Returns the content type used for the MIME body
88       * sent in this response. The content type proper must
89       * have been specified using {@link #setContentType}
90       * before the response is committed. If no content type
91       * has been specified, this method returns null.
92       * If a content type has been specified and a
93       * character encoding has been explicitly or implicitly
94       * specified as described in {@link #getCharacterEncoding},
95       * the charset parameter is included in the string returned.
96       * If no character encoding has been specified, the
97       * charset parameter is omitted.
98       *
99       * @return a <code>String</code> specifying the
100      *
101      * content type, for example, <code>text/html; charset=UTF-8</code>,
102      * or null
103      *
104      * @since Servlet 2.4
105      */
106     public String getContentType();
107 
108     /**
109      * Returns a {@link ServletOutputStream} suitable for writing binary
110      * data in the response. The servlet container does not encode the
111      * binary data.
112      *
113      * <p> Calling flush() on the ServletOutputStream commits the response.
114      *
115      * Either this method or {@link #getWriter} may
116      * be called to write the body, not both.
117      *
118      * @return a {@link ServletOutputStream} for writing binary data
119      *
120      * @exception IllegalStateException if the <code>getWriter</code> method
121      * has been called on this response
122      *
123      * @exception IOException if an input or output exception occurred
124      *
125      * @see #getWriter
126      */
127     public ServletOutputStream getOutputStream() throws IOException;
128 
129     /**
130      * Returns a <code>PrintWriter</code> object that
131      * can send character text to the client.
132      * The <code>PrintWriter</code> uses the character
133      * encoding returned by {@link #getCharacterEncoding}.
134      * If the response's character encoding has not been
135      * specified as described in <code>getCharacterEncoding</code>
136      * (i.e., the method just returns the default value
137      * <code>ISO-8859-1</code>), <code>getWriter</code>
138      * updates it to <code>ISO-8859-1</code>.
139      * <p>Calling flush() on the <code>PrintWriter</code>
140      * commits the response.
141      * <p>Either this method or {@link #getOutputStream} may be called
142      * to write the body, not both.
143      *
144      * @return a <code>PrintWriter</code> object that
145      * can return character data to the client
146      *
147      * @exception UnsupportedEncodingException if the character encoding
148      * returned by <code>getCharacterEncoding</code> cannot be used
149      *
150      * @exception IllegalStateException if the <code>getOutputStream</code>
151      * method has already been called for this response object
152      *
153      * @exception IOException if an input or output exception occurred
154      *
155      * @see #getOutputStream
156      * @see #setCharacterEncoding
157      */
158     public PrintWriter getWriter() throws IOException;
159 
160 
161     /**
162      * Sets the character encoding (MIME charset) of the response
163      * being sent to the client, for example, to UTF-8.
164      * If the character encoding has already been set by
165      * {@link #setContentType} or {@link #setLocale},
166      * this method overrides it.
167      * Calling {@link #setContentType} with the <code>String</code>
168      * of <code>text/html</code> and calling
169      * this method with the <code>String</code> of <code>UTF-8</code>
170      * is equivalent with calling
171      * <code>setContentType</code> with the <code>String</code> of
172      * <code>text/html; charset=UTF-8</code>.
173      * <p>This method can be called repeatedly to change the character
174      * encoding.
175      * This method has no effect if it is called after
176      * <code>getWriter</code> has been
177      * called or after the response has been committed.
178      * <p>Containers must communicate the character encoding used for
179      * the servlet response's writer to the client if the protocol
180      * provides a way for doing so. In the case of HTTP, the character
181      * encoding is communicated as part of the <code>Content-Type</code>
182      * header for text media types. Note that the character encoding
183      * cannot be communicated via HTTP headers if the servlet does not
184      * specify a content type; however, it is still used to encode text
185      * written via the servlet response's writer.
186      *
187      * @param charset a String specifying only the character set
188      * defined by IANA Character Sets
189      * (http://www.iana.org/assignments/character-sets)
190      *
191      * @see #setContentType
192      * @see #setLocale
193      *
194      * @since Servlet 2.4
195      */
196     public void setCharacterEncoding(String charset);
197 
198     /**
199      * Sets the length of the content body in the response
200      * In HTTP servlets, this method sets the HTTP Content-Length header.
201      *
202      * @param len an integer specifying the length of the
203      * content being returned to the client; sets
204      * the Content-Length header
205      */
206     public void setContentLength(int len);
207 
208     /**
209      * Sets the content type of the response being sent to
210      * the client, if the response has not been committed yet.
211      * The given content type may include a character encoding
212      * specification, for example, <code>text/html;charset=UTF-8</code>.
213      * The response's character encoding is only set from the given
214      * content type if this method is called before <code>getWriter</code>
215      * is called.
216      * <p>This method may be called repeatedly to change content type and
217      * character encoding.
218      * This method has no effect if called after the response
219      * has been committed. It does not set the response's character
220      * encoding if it is called after <code>getWriter</code>
221      * has been called or after the response has been committed.
222      * <p>Containers must communicate the content type and the character
223      * encoding used for the servlet response's writer to the client if
224      * the protocol provides a way for doing so. In the case of HTTP,
225      * the <code>Content-Type</code> header is used.
226      *
227      * @param type a <code>String</code> specifying the MIME
228      * type of the content
229      *
230      * @see #setLocale
231      * @see #setCharacterEncoding
232      * @see #getOutputStream
233      * @see #getWriter
234      */
235     public void setContentType(String type);
236 
237     /**
238      * Sets the preferred buffer size for the body of the response.
239      * The servlet container will use a buffer at least as large as
240      * the size requested.  The actual buffer size used can be found
241      * using <code>getBufferSize</code>.
242      *
243      * <p>A larger buffer allows more content to be written before anything is
244      * actually sent, thus providing the servlet with more time to set
245      * appropriate status codes and headers.  A smaller buffer decreases
246      * server memory load and allows the client to start receiving data more
247      * quickly.
248      *
249      * <p>This method must be called before any response body content is
250      * written; if content has been written or the response object has
251      * been committed, this method throws an
252      * <code>IllegalStateException</code>.
253      *
254      * @param size the preferred buffer size
255      *
256      * @exception IllegalStateException if this method is called after
257      * content has been written
258      *
259      * @see #getBufferSize
260      * @see #flushBuffer
261      * @see #isCommitted
262      * @see #reset
263      */
264     public void setBufferSize(int size);
265 
266     /**
267      * Returns the actual buffer size used for the response.  If no buffering
268      * is used, this method returns 0.
269      *
270      * @return the actual buffer size used
271      *
272      * @see #setBufferSize
273      * @see #flushBuffer
274      * @see #isCommitted
275      * @see #reset
276      */
277     public int getBufferSize();
278 
279     /**
280      * Forces any content in the buffer to be written to the client.  A call
281      * to this method automatically commits the response, meaning the status
282      * code and headers will be written.
283      *
284      * @see #setBufferSize
285      * @see #getBufferSize
286      * @see #isCommitted
287      * @see #reset
288      */
289     public void flushBuffer() throws IOException;
290 
291     /**
292      * Clears the content of the underlying buffer in the response without
293      * clearing headers or status code. If the
294      * response has been committed, this method throws an
295      * <code>IllegalStateException</code>.
296      *
297      * @see #setBufferSize
298      * @see #getBufferSize
299      * @see #isCommitted
300      * @see #reset
301      *
302      * @since Servlet 2.3
303      */
304     public void resetBuffer();
305 
306     /**
307      * Returns a boolean indicating if the response has been
308      * committed.  A commited response has already had its status
309      * code and headers written.
310      *
311      * @return a boolean indicating if the response has been committed
312      *
313      * @see #setBufferSize
314      * @see #getBufferSize
315      * @see #flushBuffer
316      * @see #reset
317      */
318     public boolean isCommitted();
319 
320     /**
321      * Clears any data that exists in the buffer as well as the status code and
322      * headers.  If the response has been committed, this method throws an
323      * <code>IllegalStateException</code>.
324      *
325      * @exception IllegalStateException if the response has already been
326      * committed
327      *
328      * @see #setBufferSize
329      * @see #getBufferSize
330      * @see #flushBuffer
331      * @see #isCommitted
332      */
333     public void reset();
334 
335     /**
336      * Sets the locale of the response, if the response has not been
337      * committed yet. It also sets the response's character encoding
338      * appropriately for the locale, if the character encoding has not
339      * been explicitly set using {@link #setContentType} or
340      * {@link #setCharacterEncoding}, <code>getWriter</code> hasn't
341      * been called yet, and the response hasn't been committed yet.
342      * If the deployment descriptor contains a
343      * <code>locale-encoding-mapping-list</code> element, and that
344      * element provides a mapping for the given locale, that mapping
345      * is used. Otherwise, the mapping from locale to character
346      * encoding is container dependent.
347      * <p>This method may be called repeatedly to change locale and
348      * character encoding. The method has no effect if called after the
349      * response has been committed. It does not set the response's
350      * character encoding if it is called after {@link #setContentType}
351      * has been called with a charset specification, after
352      * {@link #setCharacterEncoding} has been called, after
353      * <code>getWriter</code> has been called, or after the response
354      * has been committed.
355      * <p>Containers must communicate the locale and the character encoding
356      * used for the servlet response's writer to the client if the protocol
357      * provides a way for doing so. In the case of HTTP, the locale is
358      * communicated via the <code>Content-Language</code> header,
359      * the character encoding as part of the <code>Content-Type</code>
360      * header for text media types. Note that the character encoding
361      * cannot be communicated via HTTP headers if the servlet does not
362      * specify a content type; however, it is still used to encode text
363      * written via the servlet response's writer.
364      *
365      * @param loc the locale of the response
366      *
367      * @see #getLocale
368      * @see #setContentType
369      * @see #setCharacterEncoding
370      */
371     public void setLocale(Locale loc);
372 
373     /**
374      * Returns the locale specified for this response
375      * using the {@link #setLocale} method. Calls made to
376      * <code>setLocale</code> after the response is committed
377      * have no effect. If no locale has been specified,
378      * the container's default locale is returned.
379      *
380      * @see #setLocale
381      */
382     public Locale getLocale();
383 }
384 
385 
386 
387 
388