View Javadoc

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