001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package javax.servlet;
018:
019: import java.io.IOException;
020: import java.io.PrintWriter;
021: import java.util.Locale;
022:
023: /**
024: * Defines an object to assist a servlet in sending a response to the client.
025: * The servlet container creates a <code>ServletResponse</code> object and
026: * passes it as an argument to the servlet's <code>service</code> method.
027: *
028: * <p>To send binary data in a MIME body response, use
029: * the {@link ServletOutputStream} returned by {@link #getOutputStream}.
030: * To send character data, use the <code>PrintWriter</code> object
031: * returned by {@link #getWriter}. To mix binary and text data,
032: * for example, to create a multipart response, use a
033: * <code>ServletOutputStream</code> and manage the character sections
034: * manually.
035: *
036: * <p>The charset for the MIME body response can be specified
037: * explicitly using the {@link #setCharacterEncoding} and
038: * {@link #setContentType} methods, or implicitly
039: * using the {@link #setLocale} method.
040: * Explicit specifications take precedence over
041: * implicit specifications. If no charset is specified, ISO-8859-1 will be
042: * used. The <code>setCharacterEncoding</code>,
043: * <code>setContentType</code>, or <code>setLocale</code> method must
044: * be called before <code>getWriter</code> and before committing
045: * the response for the character encoding to be used.
046: *
047: * <p>See the Internet RFCs such as
048: * <a href="http://www.ietf.org/rfc/rfc2045.txt">
049: * RFC 2045</a> for more information on MIME. Protocols such as SMTP
050: * and HTTP define profiles of MIME, and those standards
051: * are still evolving.
052: *
053: * @author Various
054: * @version $Version$
055: *
056: * @see ServletOutputStream
057: *
058: */
059:
060: public interface ServletResponse {
061:
062: /**
063: * Returns the name of the character encoding (MIME charset)
064: * used for the body sent in this response.
065: * The character encoding may have been specified explicitly
066: * using the {@link #setCharacterEncoding} or
067: * {@link #setContentType} methods, or implicitly using the
068: * {@link #setLocale} method. Explicit specifications take
069: * precedence over implicit specifications. Calls made
070: * to these methods after <code>getWriter</code> has been
071: * called or after the response has been committed have no
072: * effect on the character encoding. If no character encoding
073: * has been specified, <code>ISO-8859-1</code> is returned.
074: * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
075: * for more information about character encoding and MIME.
076: *
077: * @return a <code>String</code> specifying the
078: * name of the character encoding, for
079: * example, <code>UTF-8</code>
080: *
081: */
082:
083: public String getCharacterEncoding();
084:
085: /**
086: * Returns the content type used for the MIME body
087: * sent in this response. The content type proper must
088: * have been specified using {@link #setContentType}
089: * before the response is committed. If no content type
090: * has been specified, this method returns null.
091: * If a content type has been specified and a
092: * character encoding has been explicitly or implicitly
093: * specified as described in {@link #getCharacterEncoding},
094: * the charset parameter is included in the string returned.
095: * If no character encoding has been specified, the
096: * charset parameter is omitted.
097: *
098: * @return a <code>String</code> specifying the
099: * content type, for example,
100: * <code>text/html; charset=UTF-8</code>,
101: * or null
102: *
103: * @since 2.4
104: */
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: */
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: *
147: * @return a <code>PrintWriter</code> object that
148: * can return character data to the client
149: *
150: * @exception UnsupportedEncodingException
151: * if the character encoding returned
152: * by <code>getCharacterEncoding</code> cannot be used
153: *
154: * @exception IllegalStateException
155: * if the <code>getOutputStream</code>
156: * method has already been called for this
157: * response object
158: *
159: * @exception IOException
160: * if an input or output exception occurred
161: *
162: * @see #getOutputStream
163: * @see #setCharacterEncoding
164: *
165: */
166:
167: public PrintWriter getWriter() throws IOException;
168:
169: /**
170: * Sets the character encoding (MIME charset) of the response
171: * being sent to the client, for example, to UTF-8.
172: * If the character encoding has already been set by
173: * {@link #setContentType} or {@link #setLocale},
174: * this method overrides it.
175: * Calling {@link #setContentType} with the <code>String</code>
176: * of <code>text/html</code> and calling
177: * this method with the <code>String</code> of <code>UTF-8</code>
178: * is equivalent with calling
179: * <code>setContentType</code> with the <code>String</code> of
180: * <code>text/html; charset=UTF-8</code>.
181: * <p>This method can be called repeatedly to change the character
182: * encoding.
183: * This method has no effect if it is called after
184: * <code>getWriter</code> has been
185: * called or after the response has been committed.
186: * <p>Containers must communicate the character encoding used for
187: * the servlet response's writer to the client if the protocol
188: * provides a way for doing so. In the case of HTTP, the character
189: * encoding is communicated as part of the <code>Content-Type</code>
190: * header for text media types. Note that the character encoding
191: * cannot be communicated via HTTP headers if the servlet does not
192: * specify a content type; however, it is still used to encode text
193: * written via the servlet response's writer.
194: *
195: * @param charset a String specifying only the character set
196: * defined by IANA Character Sets
197: * (http://www.iana.org/assignments/character-sets)
198: *
199: * @see #setContentType
200: * #setLocale
201: *
202: * @since 2.4
203: *
204: */
205:
206: public void setCharacterEncoding(String charset);
207:
208: /**
209: * Sets the length of the content body in the response
210: * In HTTP servlets, this method sets the HTTP Content-Length header.
211: *
212: *
213: * @param len an integer specifying the length of the
214: * content being returned to the client; sets
215: * the Content-Length header
216: *
217: */
218:
219: public void setContentLength(int len);
220:
221: /**
222: * Sets the content type of the response being sent to
223: * the client, if the response has not been committed yet.
224: * The given content type may include a character encoding
225: * specification, for example, <code>text/html;charset=UTF-8</code>.
226: * The response's character encoding is only set from the given
227: * content type if this method is called before <code>getWriter</code>
228: * is called.
229: * <p>This method may be called repeatedly to change content type and
230: * character encoding.
231: * This method has no effect if called after the response
232: * has been committed. It does not set the response's character
233: * encoding if it is called after <code>getWriter</code>
234: * has been called or after the response has been committed.
235: * <p>Containers must communicate the content type and the character
236: * encoding used for the servlet response's writer to the client if
237: * the protocol provides a way for doing so. In the case of HTTP,
238: * the <code>Content-Type</code> header is used.
239: *
240: * @param type a <code>String</code> specifying the MIME
241: * type of the content
242: *
243: * @see #setLocale
244: * @see #setCharacterEncoding
245: * @see #getOutputStream
246: * @see #getWriter
247: *
248: */
249:
250: public void setContentType(String type);
251:
252: /**
253: * Sets the preferred buffer size for the body of the response.
254: * The servlet container will use a buffer at least as large as
255: * the size requested. The actual buffer size used can be found
256: * using <code>getBufferSize</code>.
257: *
258: * <p>A larger buffer allows more content to be written before anything is
259: * actually sent, thus providing the servlet with more time to set
260: * appropriate status codes and headers. A smaller buffer decreases
261: * server memory load and allows the client to start receiving data more
262: * quickly.
263: *
264: * <p>This method must be called before any response body content is
265: * written; if content has been written or the response object has
266: * been committed, this method throws an
267: * <code>IllegalStateException</code>.
268: *
269: * @param size the preferred buffer size
270: *
271: * @exception IllegalStateException if this method is called after
272: * content has been written
273: *
274: * @see #getBufferSize
275: * @see #flushBuffer
276: * @see #isCommitted
277: * @see #reset
278: *
279: */
280:
281: public void setBufferSize(int size);
282:
283: /**
284: * Returns the actual buffer size used for the response. If no buffering
285: * is used, this method returns 0.
286: *
287: * @return the actual buffer size used
288: *
289: * @see #setBufferSize
290: * @see #flushBuffer
291: * @see #isCommitted
292: * @see #reset
293: *
294: */
295:
296: public int getBufferSize();
297:
298: /**
299: * Forces any content in the buffer to be written to the client. A call
300: * to this method automatically commits the response, meaning the status
301: * code and headers will be written.
302: *
303: * @see #setBufferSize
304: * @see #getBufferSize
305: * @see #isCommitted
306: * @see #reset
307: *
308: */
309:
310: public void flushBuffer() throws IOException;
311:
312: /**
313: * Clears the content of the underlying buffer in the response without
314: * clearing headers or status code. If the
315: * response has been committed, this method throws an
316: * <code>IllegalStateException</code>.
317: *
318: * @see #setBufferSize
319: * @see #getBufferSize
320: * @see #isCommitted
321: * @see #reset
322: *
323: * @since 2.3
324: */
325:
326: public void resetBuffer();
327:
328: /**
329: * Returns a boolean indicating if the response has been
330: * committed. A committed response has already had its status
331: * code and headers written.
332: *
333: * @return a boolean indicating if the response has been
334: * committed
335: *
336: * @see #setBufferSize
337: * @see #getBufferSize
338: * @see #flushBuffer
339: * @see #reset
340: *
341: */
342:
343: public boolean isCommitted();
344:
345: /**
346: * Clears any data that exists in the buffer as well as the status code and
347: * headers. If the response has been committed, this method throws an
348: * <code>IllegalStateException</code>.
349: *
350: * @exception IllegalStateException if the response has already been
351: * committed
352: *
353: * @see #setBufferSize
354: * @see #getBufferSize
355: * @see #flushBuffer
356: * @see #isCommitted
357: *
358: */
359:
360: public void reset();
361:
362: /**
363: * Sets the locale of the response, if the response has not been
364: * committed yet. It also sets the response's character encoding
365: * appropriately for the locale, if the character encoding has not
366: * been explicitly set using {@link #setContentType} or
367: * {@link #setCharacterEncoding}, <code>getWriter</code> hasn't
368: * been called yet, and the response hasn't been committed yet.
369: * If the deployment descriptor contains a
370: * <code>locale-encoding-mapping-list</code> element, and that
371: * element provides a mapping for the given locale, that mapping
372: * is used. Otherwise, the mapping from locale to character
373: * encoding is container dependent.
374: * <p>This method may be called repeatedly to change locale and
375: * character encoding. The method has no effect if called after the
376: * response has been committed. It does not set the response's
377: * character encoding if it is called after {@link #setContentType}
378: * has been called with a charset specification, after
379: * {@link #setCharacterEncoding} has been called, after
380: * <code>getWriter</code> has been called, or after the response
381: * has been committed.
382: * <p>Containers must communicate the locale and the character encoding
383: * used for the servlet response's writer to the client if the protocol
384: * provides a way for doing so. In the case of HTTP, the locale is
385: * communicated via the <code>Content-Language</code> header,
386: * the character encoding as part of the <code>Content-Type</code>
387: * header for text media types. Note that the character encoding
388: * cannot be communicated via HTTP headers if the servlet does not
389: * specify a content type; however, it is still used to encode text
390: * written via the servlet response's writer.
391: *
392: * @param loc the locale of the response
393: *
394: * @see #getLocale
395: * @see #setContentType
396: * @see #setCharacterEncoding
397: *
398: */
399:
400: public void setLocale(Locale loc);
401:
402: /**
403: * Returns the locale specified for this response
404: * using the {@link #setLocale} method. Calls made to
405: * <code>setLocale</code> after the response is committed
406: * have no effect. If no locale has been specified,
407: * the container's default locale is returned.
408: *
409: * @see #setLocale
410: *
411: */
412:
413: public Locale getLocale();
414:
415: }
|