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