lib/servlet-api/javax/servlet/http/HttpServletResponse.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.http;
  18
  19 import java.io.IOException;
  20 import java.util.Collection;
  21
  22 import javax.servlet.ServletResponse;
  23
  24 /**
  25  * Extends the {@link ServletResponse} interface to provide HTTP-specific
  26  * functionality in sending a response. For example, it has methods to access
  27  * HTTP headers and cookies.
  28  * <p>
  29  * The servlet container creates an <code>HttpServletResponse</code> object and
  30  * passes it as an argument to the servlet's service methods (<code>doGet</code>, <code>doPost</code>, etc).
  31  *
  32  * @see javax.servlet.ServletResponse
  33  */
  34 public interface HttpServletResponse extends ServletResponse {
  35
  36     /**
  37      * Adds the specified cookie to the response. This method can be called
  38      * multiple times to set more than one cookie.
  39      *
  40      * @param cookie
  41      *            the Cookie to return to the client
  42      */
  43     public void addCookie(Cookie cookie);
  44
  45     /**
  46      * Returns a boolean indicating whether the named response header has
  47      * already been set.
  48      *
  49      * @param name
  50      *            the header name
  51      * @return <code>true</code> if the named response header has already been
  52      *         set; <code>false</code> otherwise
  53      */
  54     public boolean containsHeader(String name);
  55
  56     /**
  57      * Encodes the specified URL by including the session ID in it, or, if
  58      * encoding is not needed, returns the URL unchanged. The implementation of
  59      * this method includes the logic to determine whether the session ID needs
  60      * to be encoded in the URL. For example, if the browser supports cookies,
  61      * or session tracking is turned off, URL encoding is unnecessary.
  62      * <p>
  63      * For robust session tracking, all URLs emitted by a servlet should be run
  64      * through this method. Otherwise, URL rewriting cannot be used with
  65      * browsers which do not support cookies.
  66      *
  67      * @param url
  68      *            the url to be encoded.
  69      * @return the encoded URL if encoding is needed; the unchanged URL
  70      *         otherwise.
  71      */
  72     public String encodeURL(String url);
  73
  74     /**
  75      * Encodes the specified URL for use in the <code>sendRedirect</code> method
  76      * or, if encoding is not needed, returns the URL unchanged. The
  77      * implementation of this method includes the logic to determine whether the
  78      * session ID needs to be encoded in the URL. Because the rules for making
  79      * this determination can differ from those used to decide whether to encode
  80      * a normal link, this method is separated from the <code>encodeURL</code>
  81      * method.
  82      * <p>
  83      * All URLs sent to the <code>HttpServletResponse.sendRedirect</code> method
  84      * should be run through this method. Otherwise, URL rewriting cannot be
  85      * used with browsers which do not support cookies.
  86      *
  87      * @param url
  88      *            the url to be encoded.
  89      * @return the encoded URL if encoding is needed; the unchanged URL
  90      *         otherwise.
  91      * @see #sendRedirect
  92      * @see #encodeUrl
  93      */
  94     public String encodeRedirectURL(String url);
  95
  96     /**
  97      * @param url
  98      *            the url to be encoded.
  99      * @return the encoded URL if encoding is needed; the unchanged URL
 100      *         otherwise.
 101      * @deprecated As of version 2.1, use encodeURL(String url) instead
 102      */
 103     @SuppressWarnings("dep-ann")
 104     // Spec API does not use @Deprecated
 105     public String encodeUrl(String url);
 106
 107     /**
 108      * @param url
 109      *            the url to be encoded.
 110      * @return the encoded URL if encoding is needed; the unchanged URL
 111      *         otherwise.
 112      * @deprecated As of version 2.1, use encodeRedirectURL(String url) instead
 113      */
 114     @SuppressWarnings("dep-ann")
 115     // Spec API does not use @Deprecated
 116     public String encodeRedirectUrl(String url);
 117
 118     /**
 119      * Sends an error response to the client using the specified status code and
 120      * clears the output buffer. The server defaults to creating the response to
 121      * look like an HTML-formatted server error page containing the specified
 122      * message, setting the content type to "text/html", leaving cookies and
 123      * other headers unmodified. If an error-page declaration has been made for
 124      * the web application corresponding to the status code passed in, it will
 125      * be served back in preference to the suggested msg parameter.
 126      * <p>
 127      * If the response has already been committed, this method throws an
 128      * IllegalStateException. After using this method, the response should be
 129      * considered to be committed and should not be written to.
 130      *
 131      * @param sc
 132      *            the error status code
 133      * @param msg
 134      *            the descriptive message
 135      * @exception IOException
 136      *                If an input or output exception occurs
 137      * @exception IllegalStateException
 138      *                If the response was committed
 139      */
 140     public void sendError(int sc, String msg) throws IOException;
 141
 142     /**
 143      * Sends an error response to the client using the specified status code and
 144      * clears the buffer. This is equivalent to calling {@link #sendError(int,
 145      * String)} with the same status code and <code>null</code> for the message.
 146      *
 147      * @param sc
 148      *            the error status code
 149      * @exception IOException
 150      *                If an input or output exception occurs
 151      * @exception IllegalStateException
 152      *                If the response was committed before this method call
 153      */
 154     public void sendError(int sc) throws IOException;
 155
 156     /**
 157      * Sends a temporary redirect response to the client using the specified
 158      * redirect location URL. This method can accept relative URLs; the servlet
 159      * container must convert the relative URL to an absolute URL before sending
 160      * the response to the client. If the location is relative without a leading
 161      * '/' the container interprets it as relative to the current request URI.
 162      * If the location is relative with a leading '/' the container interprets
 163      * it as relative to the servlet container root.
 164      * <p>
 165      * If the response has already been committed, this method throws an
 166      * IllegalStateException. After using this method, the response should be
 167      * considered to be committed and should not be written to.
 168      *
 169      * @param location
 170      *            the redirect location URL
 171      * @exception IOException
 172      *                If an input or output exception occurs
 173      * @exception IllegalStateException
 174      *                If the response was committed or if a partial URL is given
 175      *                and cannot be converted into a valid URL
 176      */
 177     public void sendRedirect(String location) throws IOException;
 178
 179     /**
 180      * Sets a response header with the given name and date-value. The date is
 181      * specified in terms of milliseconds since the epoch. If the header had
 182      * already been set, the new value overwrites the previous one. The
 183      * <code>containsHeader</code> method can be used to test for the presence
 184      * of a header before setting its value.
 185      *
 186      * @param name
 187      *            the name of the header to set
 188      * @param date
 189      *            the assigned date value
 190      * @see #containsHeader
 191      * @see #addDateHeader
 192      */
 193     public void setDateHeader(String name, long date);
 194
 195     /**
 196      * Adds a response header with the given name and date-value. The date is
 197      * specified in terms of milliseconds since the epoch. This method allows
 198      * response headers to have multiple values.
 199      *
 200      * @param name
 201      *            the name of the header to set
 202      * @param date
 203      *            the additional date value
 204      * @see #setDateHeader
 205      */
 206     public void addDateHeader(String name, long date);
 207
 208     /**
 209      * Sets a response header with the given name and value. If the header had
 210      * already been set, the new value overwrites the previous one. The
 211      * <code>containsHeader</code> method can be used to test for the presence
 212      * of a header before setting its value.
 213      *
 214      * @param name
 215      *            the name of the header
 216      * @param value
 217      *            the header value If it contains octet string, it should be
 218      *            encoded according to RFC 2047
 219      *            (http://www.ietf.org/rfc/rfc2047.txt)
 220      * @see #containsHeader
 221      * @see #addHeader
 222      */
 223     public void setHeader(String name, String value);
 224
 225     /**
 226      * Adds a response header with the given name and value. This method allows
 227      * response headers to have multiple values.
 228      *
 229      * @param name
 230      *            the name of the header
 231      * @param value
 232      *            the additional header value If it contains octet string, it
 233      *            should be encoded according to RFC 2047
 234      *            (http://www.ietf.org/rfc/rfc2047.txt)
 235      * @see #setHeader
 236      */
 237     public void addHeader(String name, String value);
 238
 239     /**
 240      * Sets a response header with the given name and integer value. If the
 241      * header had already been set, the new value overwrites the previous one.
 242      * The <code>containsHeader</code> method can be used to test for the
 243      * presence of a header before setting its value.
 244      *
 245      * @param name
 246      *            the name of the header
 247      * @param value
 248      *            the assigned integer value
 249      * @see #containsHeader
 250      * @see #addIntHeader
 251      */
 252     public void setIntHeader(String name, int value);
 253
 254     /**
 255      * Adds a response header with the given name and integer value. This method
 256      * allows response headers to have multiple values.
 257      *
 258      * @param name
 259      *            the name of the header
 260      * @param value
 261      *            the assigned integer value
 262      * @see #setIntHeader
 263      */
 264     public void addIntHeader(String name, int value);
 265
 266     /**
 267      * Sets the status code for this response. This method is used to set the
 268      * return status code when there is no error (for example, for the status
 269      * codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the
 270      * caller wishes to invoke an error-page defined in the web application, the
 271      * <code>sendError</code> method should be used instead.
 272      * <p>
 273      * The container clears the buffer and sets the Location header, preserving
 274      * cookies and other headers.
 275      *
 276      * @param sc
 277      *            the status code
 278      * @see #sendError
 279      */
 280     public void setStatus(int sc);
 281
 282     /**
 283      * Sets the status code and message for this response.
 284      *
 285      * @param sc
 286      *            the status code
 287      * @param sm
 288      *            the status message
 289      * @deprecated As of version 2.1, due to ambiguous meaning of the message
 290      *             parameter. To set a status code use
 291      *             <code>setStatus(int)</code>, to send an error with a
 292      *             description use <code>sendError(int, String)</code>.
 293      */
 294     @SuppressWarnings("dep-ann")
 295     // Spec API does not use @Deprecated
 296     public void setStatus(int sc, String sm);
 297
 298     /**
 299      * Return the HTTP status code associated with this Response.
 300      *
 301      * @since Servlet 3.0
 302      */
 303     public int getStatus();
 304
 305     /**
 306      * Return the value for the specified header, or <code>null</code> if this
 307      * header has not been set.  If more than one value was added for this
 308      * name, only the first is returned; use {@link #getHeaders(String)} to
 309      * retrieve all of them.
 310      *
 311      * @param name Header name to look up
 312      *
 313      * @since Servlet 3.0
 314      */
 315     public String getHeader(String name);
 316
 317     /**
 318      * Return a Collection of all the header values associated with the
 319      * specified header name.
 320      *
 321      * @param name Header name to look up
 322      *
 323      * @since Servlet 3.0
 324      */
 325     public Collection<String> getHeaders(String name);
 326
 327     /**
 328      * Return an Iterable of all the header names set for this response.
 329      *
 330      * @since Servlet 3.0
 331      */
 332     public Collection<String> getHeaderNames();
 333
 334     /*
 335      * Server status codes; see RFC 2068.
 336      */
 337
 338     /**
 339      * Status code (100) indicating the client can continue.
 340      */
 341     public static final int SC_CONTINUE = 100;
 342
 343     /**
 344      * Status code (101) indicating the server is switching protocols according
 345      * to Upgrade header.
 346      */
 347     public static final int SC_SWITCHING_PROTOCOLS = 101;
 348
 349     /**
 350      * Status code (200) indicating the request succeeded normally.
 351      */
 352     public static final int SC_OK = 200;
 353
 354     /**
 355      * Status code (201) indicating the request succeeded and created a new
 356      * resource on the server.
 357      */
 358     public static final int SC_CREATED = 201;
 359
 360     /**
 361      * Status code (202) indicating that a request was accepted for processing,
 362      * but was not completed.
 363      */
 364     public static final int SC_ACCEPTED = 202;
 365
 366     /**
 367      * Status code (203) indicating that the meta information presented by the
 368      * client did not originate from the server.
 369      */
 370     public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;
 371
 372     /**
 373      * Status code (204) indicating that the request succeeded but that there
 374      * was no new information to return.
 375      */
 376     public static final int SC_NO_CONTENT = 204;
 377
 378     /**
 379      * Status code (205) indicating that the agent <em>SHOULD</em> reset the
 380      * document view which caused the request to be sent.
 381      */
 382     public static final int SC_RESET_CONTENT = 205;
 383
 384     /**
 385      * Status code (206) indicating that the server has fulfilled the partial
 386      * GET request for the resource.
 387      */
 388     public static final int SC_PARTIAL_CONTENT = 206;
 389
 390     /**
 391      * Status code (300) indicating that the requested resource corresponds to
 392      * any one of a set of representations, each with its own specific location.
 393      */
 394     public static final int SC_MULTIPLE_CHOICES = 300;
 395
 396     /**
 397      * Status code (301) indicating that the resource has permanently moved to a
 398      * new location, and that future references should use a new URI with their
 399      * requests.
 400      */
 401     public static final int SC_MOVED_PERMANENTLY = 301;
 402
 403     /**
 404      * Status code (302) indicating that the resource has temporarily moved to
 405      * another location, but that future references should still use the
 406      * original URI to access the resource. This definition is being retained
 407      * for backwards compatibility. SC_FOUND is now the preferred definition.
 408      */
 409     public static final int SC_MOVED_TEMPORARILY = 302;
 410
 411     /**
 412      * Status code (302) indicating that the resource reside temporarily under a
 413      * different URI. Since the redirection might be altered on occasion, the
 414      * client should continue to use the Request-URI for future
 415      * requests.(HTTP/1.1) To represent the status code (302), it is recommended
 416      * to use this variable.
 417      */
 418     public static final int SC_FOUND = 302;
 419
 420     /**
 421      * Status code (303) indicating that the response to the request can be
 422      * found under a different URI.
 423      */
 424     public static final int SC_SEE_OTHER = 303;
 425
 426     /**
 427      * Status code (304) indicating that a conditional GET operation found that
 428      * the resource was available and not modified.
 429      */
 430     public static final int SC_NOT_MODIFIED = 304;
 431
 432     /**
 433      * Status code (305) indicating that the requested resource <em>MUST</em> be
 434      * accessed through the proxy given by the <code><em>Location</em></code>
 435      * field.
 436      */
 437     public static final int SC_USE_PROXY = 305;
 438
 439     /**
 440      * Status code (307) indicating that the requested resource resides
 441      * temporarily under a different URI. The temporary URI <em>SHOULD</em> be
 442      * given by the <code><em>Location</em></code> field in the response.
 443      */
 444     public static final int SC_TEMPORARY_REDIRECT = 307;
 445
 446     /**
 447      * Status code (400) indicating the request sent by the client was
 448      * syntactically incorrect.
 449      */
 450     public static final int SC_BAD_REQUEST = 400;
 451
 452     /**
 453      * Status code (401) indicating that the request requires HTTP
 454      * authentication.
 455      */
 456     public static final int SC_UNAUTHORIZED = 401;
 457
 458     /**
 459      * Status code (402) reserved for future use.
 460      */
 461     public static final int SC_PAYMENT_REQUIRED = 402;
 462
 463     /**
 464      * Status code (403) indicating the server understood the request but
 465      * refused to fulfill it.
 466      */
 467     public static final int SC_FORBIDDEN = 403;
 468
 469     /**
 470      * Status code (404) indicating that the requested resource is not
 471      * available.
 472      */
 473     public static final int SC_NOT_FOUND = 404;
 474
 475     /**
 476      * Status code (405) indicating that the method specified in the
 477      * <code><em>Request-Line</em></code> is not allowed for the resource
 478      * identified by the <code><em>Request-URI</em></code>.
 479      */
 480     public static final int SC_METHOD_NOT_ALLOWED = 405;
 481
 482     /**
 483      * Status code (406) indicating that the resource identified by the request
 484      * is only capable of generating response entities which have content
 485      * characteristics not acceptable according to the accept headers sent in
 486      * the request.
 487      */
 488     public static final int SC_NOT_ACCEPTABLE = 406;
 489
 490     /**
 491      * Status code (407) indicating that the client <em>MUST</em> first
 492      * authenticate itself with the proxy.
 493      */
 494     public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;
 495
 496     /**
 497      * Status code (408) indicating that the client did not produce a request
 498      * within the time that the server was prepared to wait.
 499      */
 500     public static final int SC_REQUEST_TIMEOUT = 408;
 501
 502     /**
 503      * Status code (409) indicating that the request could not be completed due
 504      * to a conflict with the current state of the resource.
 505      */
 506     public static final int SC_CONFLICT = 409;
 507
 508     /**
 509      * Status code (410) indicating that the resource is no longer available at
 510      * the server and no forwarding address is known. This condition
 511      * <em>SHOULD</em> be considered permanent.
 512      */
 513     public static final int SC_GONE = 410;
 514
 515     /**
 516      * Status code (411) indicating that the request cannot be handled without a
 517      * defined <code><em>Content-Length</em></code>.
 518      */
 519     public static final int SC_LENGTH_REQUIRED = 411;
 520
 521     /**
 522      * Status code (412) indicating that the precondition given in one or more
 523      * of the request-header fields evaluated to false when it was tested on the
 524      * server.
 525      */
 526     public static final int SC_PRECONDITION_FAILED = 412;
 527
 528     /**
 529      * Status code (413) indicating that the server is refusing to process the
 530      * request because the request entity is larger than the server is willing
 531      * or able to process.
 532      */
 533     public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413;
 534
 535     /**
 536      * Status code (414) indicating that the server is refusing to service the
 537      * request because the <code><em>Request-URI</em></code> is longer than the
 538      * server is willing to interpret.
 539      */
 540     public static final int SC_REQUEST_URI_TOO_LONG = 414;
 541
 542     /**
 543      * Status code (415) indicating that the server is refusing to service the
 544      * request because the entity of the request is in a format not supported by
 545      * the requested resource for the requested method.
 546      */
 547     public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;
 548
 549     /**
 550      * Status code (416) indicating that the server cannot serve the requested
 551      * byte range.
 552      */
 553     public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416;
 554
 555     /**
 556      * Status code (417) indicating that the server could not meet the
 557      * expectation given in the Expect request header.
 558      */
 559     public static final int SC_EXPECTATION_FAILED = 417;
 560
 561     /**
 562      * Status code (500) indicating an error inside the HTTP server which
 563      * prevented it from fulfilling the request.
 564      */
 565     public static final int SC_INTERNAL_SERVER_ERROR = 500;
 566
 567     /**
 568      * Status code (501) indicating the HTTP server does not support the
 569      * functionality needed to fulfill the request.
 570      */
 571     public static final int SC_NOT_IMPLEMENTED = 501;
 572
 573     /**
 574      * Status code (502) indicating that the HTTP server received an invalid
 575      * response from a server it consulted when acting as a proxy or gateway.
 576      */
 577     public static final int SC_BAD_GATEWAY = 502;
 578
 579     /**
 580      * Status code (503) indicating that the HTTP server is temporarily
 581      * overloaded, and unable to handle the request.
 582      */
 583     public static final int SC_SERVICE_UNAVAILABLE = 503;
 584
 585     /**
 586      * Status code (504) indicating that the server did not receive a timely
 587      * response from the upstream server while acting as a gateway or proxy.
 588      */
 589     public static final int SC_GATEWAY_TIMEOUT = 504;
 590
 591     /**
 592      * Status code (505) indicating that the server does not support or refuses
 593      * to support the HTTP protocol version that was used in the request
 594      * message.
 595      */
 596     public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;
 597 }