lib/servlet-api/javax/servlet/ServletResponse.java

   1 /*
   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
   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 package javax.servlet;
  18
  19 import java.io.IOException;
  20 import java.io.PrintWriter;
  21 import java.util.Locale;
  22
  23 /**
  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.
  27  * <p>
  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.
  34  * <p>
  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.
  43  * <p>
  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.
  47  *
  48  * @see ServletOutputStream
  49  */
  50 public interface ServletResponse {
  51
  52     /**
  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.
  62      * <p>
  63      * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information
  64      * about character encoding and MIME.
  65      *
  66      * @return a <code>String</code> specifying the name of the character
  67      *         encoding, for example, <code>UTF-8</code>
  68      */
  69     public String getCharacterEncoding();
  70
  71     /**
  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.
  80      *
  81      * @return a <code>String</code> specifying the content type, for example,
  82      *         <code>text/html; charset=UTF-8</code>, or null
  83      * @since 2.4
  84      */
  85     public String getContentType();
  86
  87     /**
  88      * Returns a {@link ServletOutputStream} suitable for writing binary data in
  89      * the response. The servlet container does not encode the binary data.
  90      * <p>
  91      * Calling flush() on the ServletOutputStream commits the response. Either
  92      * this method or {@link #getWriter} may be called to write the body, not
  93      * both.
  94      *
  95      * @return a {@link ServletOutputStream} for writing binary data
  96      * @exception IllegalStateException
  97      *                if the <code>getWriter</code> method has been called on
  98      *                this response
  99      * @exception IOException
 100      *                if an input or output exception occurred
 101      * @see #getWriter
 102      */
 103     public ServletOutputStream getOutputStream() throws IOException;
 104
 105     /**
 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>.
 113      * <p>
 114      * Calling flush() on the <code>PrintWriter</code> commits the response.
 115      * <p>
 116      * Either this method or {@link #getOutputStream} may be called to write the
 117      * body, not both.
 118      *
 119      * @return a <code>PrintWriter</code> object that can return character data
 120      *         to the client
 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
 131      */
 132     public PrintWriter getWriter() throws IOException;
 133
 134     /**
 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>.
 143      * <p>
 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.
 147      * <p>
 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.
 155      *
 156      * @param charset
 157      *            a String specifying only the character set defined by IANA
 158      *            Character Sets
 159      *            (http://www.iana.org/assignments/character-sets)
 160      * @see #setContentType #setLocale
 161      * @since 2.4
 162      */
 163     public void setCharacterEncoding(String charset);
 164
 165     /**
 166      * Sets the length of the content body in the response In HTTP servlets,
 167      * this method sets the HTTP Content-Length header.
 168      *
 169      * @param len
 170      *            an integer specifying the length of the content being returned
 171      *            to the client; sets the Content-Length header
 172      */
 173     public void setContentLength(int len);
 174
 175     /**
 176      * TODO SERVLET 3.1
 177      */
 178     public void setContentLengthLong(long length);
 179
 180     /**
 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.
 187      * <p>
 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.
 193      * <p>
 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.
 198      *
 199      * @param type
 200      *            a <code>String</code> specifying the MIME type of the content
 201      * @see #setLocale
 202      * @see #setCharacterEncoding
 203      * @see #getOutputStream
 204      * @see #getWriter
 205      */
 206     public void setContentType(String type);
 207
 208     /**
 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>.
 212      * <p>
 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.
 217      * <p>
 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>.
 221      *
 222      * @param size
 223      *            the preferred buffer size
 224      * @exception IllegalStateException
 225      *                if this method is called after content has been written
 226      * @see #getBufferSize
 227      * @see #flushBuffer
 228      * @see #isCommitted
 229      * @see #reset
 230      */
 231     public void setBufferSize(int size);
 232
 233     /**
 234      * Returns the actual buffer size used for the response. If no buffering is
 235      * used, this method returns 0.
 236      *
 237      * @return the actual buffer size used
 238      * @see #setBufferSize
 239      * @see #flushBuffer
 240      * @see #isCommitted
 241      * @see #reset
 242      */
 243     public int getBufferSize();
 244
 245     /**
 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.
 249      *
 250      * @see #setBufferSize
 251      * @see #getBufferSize
 252      * @see #isCommitted
 253      * @see #reset
 254      */
 255     public void flushBuffer() throws IOException;
 256
 257     /**
 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>.
 261      *
 262      * @see #setBufferSize
 263      * @see #getBufferSize
 264      * @see #isCommitted
 265      * @see #reset
 266      * @since 2.3
 267      */
 268     public void resetBuffer();
 269
 270     /**
 271      * Returns a boolean indicating if the response has been committed. A
 272      * committed response has already had its status code and headers written.
 273      *
 274      * @return a boolean indicating if the response has been committed
 275      * @see #setBufferSize
 276      * @see #getBufferSize
 277      * @see #flushBuffer
 278      * @see #reset
 279      */
 280     public boolean isCommitted();
 281
 282     /**
 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>.
 286      *
 287      * @exception IllegalStateException
 288      *                if the response has already been committed
 289      * @see #setBufferSize
 290      * @see #getBufferSize
 291      * @see #flushBuffer
 292      * @see #isCommitted
 293      */
 294     public void reset();
 295
 296     /**
 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.
 306      * <p>
 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
 313      * committed.
 314      * <p>
 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.
 323      *
 324      * @param loc
 325      *            the locale of the response
 326      * @see #getLocale
 327      * @see #setContentType
 328      * @see #setCharacterEncoding
 329      */
 330     public void setLocale(Locale loc);
 331
 332     /**
 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.
 337      *
 338      * @see #setLocale
 339      */
 340     public Locale getLocale();
 341
 342 }