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-25 06:01:51 +0200 (Mi, 25. Okt 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