001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2015 ForgeRock AS. 015 */ 016 017package org.forgerock.http.protocol; 018 019import static java.lang.String.format; 020 021import java.util.HashMap; 022import java.util.Map; 023 024/** 025 * The status-code element is a three-digit integer code giving the 026 * result of the attempt to understand and satisfy the request. 027 * 028 * <p> 029 * HTTP status codes are extensible. HTTP clients are not required to 030 * understand the meaning of all registered status codes, though such 031 * understanding is obviously desirable. However, a client MUST 032 * understand the class of any status code, as indicated by the first 033 * digit, and treat an unrecognized status code as being equivalent to 034 * the x00 status code of that class, with the exception that a 035 * recipient MUST NOT cache a response with an unrecognized status code.</p> 036 * 037 * <p> 038 * For example, if an unrecognized status code of 471 is received by a 039 * client, the client can assume that there was something wrong with its 040 * request and treat the response as if it had received a 400 (Bad 041 * Request) status code. The response message will usually contain a 042 * representation that explains the status.</p> 043 * 044 * <p> 045 * The first digit of the status-code defines the class of response. 046 * The last two digits do not have any categorization role. There are 047 * five values for the first digit: 048 * </p> 049 * <ul> 050 * <li>1xx (Informational): The request was received, continuing process</li> 051 * 052 * <li>2xx (Successful): The request was successfully received, 053 * understood, and accepted</li> 054 * 055 * <li>3xx (Redirection): Further action needs to be taken in order to 056 * complete the request</li> 057 * 058 * <li>4xx (Client Error): The request contains bad syntax or cannot be 059 * fulfilled</li> 060 * 061 * <li>5xx (Server Error): The server failed to fulfill an apparently 062 * valid request</li> 063 * </ul> 064 * 065 * <p>The reason phrases are only recommendations they can be replaced by local 066 * equivalents without affecting the protocol.</p> 067 * 068 * @see <a href="https://tools.ietf.org/html/rfc7231#section-6">Hypertext Transfer Protocol (HTTP/1.1): Response Status 069 * Codes</a> 070 */ 071public final class Status { 072 073 private static final Map<Integer, Status> KNOWN_STATUSES = new HashMap<>(); 074 075 private final int code; 076 private final String reasonPhrase; 077 private final Family family; 078 079 private Status(int code, final String reasonPhrase) { 080 this.code = code; 081 this.reasonPhrase = reasonPhrase; 082 // Note that this can throw an IllegalArgumentException in case of invalid code 083 this.family = Status.Family.valueOf(code); 084 } 085 086 @Override 087 public String toString() { 088 return "[Status: " + code + " " + (reasonPhrase == null ? "No reason given" : reasonPhrase) + "]"; 089 } 090 091 /** 092 * Returns the three-digit integer code giving the result of the attempt to understand and satisfy the request. 093 * @return the three-digit integer code giving the result of the attempt to understand and satisfy the request. 094 */ 095 public int getCode() { 096 return code; 097 } 098 099 /** 100 * Returns the reason phrase associated with the status code. 101 * The reason phrase is purely informative and can even be changed without affecting the protocol. 102 * @return the reason phrase associated with this status code. 103 */ 104 public String getReasonPhrase() { 105 return reasonPhrase; 106 } 107 108 /** 109 * Returns the class of response of this status code. 110 * @return the class of response of this status code. 111 */ 112 public Family getFamily() { 113 return family; 114 } 115 116 /** 117 * Is the family of this status a {@link Family#INFORMATIONAL} one ? 118 * @return true if the family of this status is a {@link Family#INFORMATIONAL} one. 119 */ 120 public boolean isInformational() { 121 return Family.INFORMATIONAL.equals(getFamily()); 122 } 123 124 /** 125 * Is the family of this status a {@link Family#SUCCESSFUL} one ? 126 * @return true if the family of this status is a {@link Family#SUCCESSFUL} one. 127 */ 128 public boolean isSuccessful() { 129 return Family.SUCCESSFUL.equals(getFamily()); 130 } 131 132 /** 133 * Is the family of this status a {@link Family#REDIRECTION} one ? 134 * @return true if the family of this status is a {@link Family#REDIRECTION} one. 135 */ 136 public boolean isRedirection() { 137 return Family.REDIRECTION.equals(getFamily()); 138 } 139 140 /** 141 * Is the family of this status a {@link Family#CLIENT_ERROR} one ? 142 * @return true if the family of this status is a {@link Family#CLIENT_ERROR} one. 143 */ 144 public boolean isClientError() { 145 return Family.CLIENT_ERROR.equals(getFamily()); 146 } 147 148 /** 149 * Is the family of this status a {@link Family#SERVER_ERROR} one ? 150 * @return true if the family of this status is a {@link Family#SERVER_ERROR} one. 151 */ 152 public boolean isServerError() { 153 return Family.SERVER_ERROR.equals(getFamily()); 154 } 155 156 /** 157 * The first digit of the status-code defines the class of response. 158 * The last two digits do not have any categorization role. There are 159 * five values for the first digit: 160 * 161 * <ul> 162 * <li>1xx (Informational): The request was received, continuing process</li> 163 * 164 * <li>2xx (Successful): The request was successfully received, 165 * understood, and accepted</li> 166 * 167 * <li>3xx (Redirection): Further action needs to be taken in order to 168 * complete the request</li> 169 * 170 * <li>4xx (Client Error): The request contains bad syntax or cannot be 171 * fulfilled</li> 172 * 173 * <li>5xx (Server Error): The server failed to fulfill an apparently 174 * valid request</li> 175 * </ul> 176 */ 177 public enum Family { 178 /** 179 * The {@literal 1xx} (Informational) class of status code indicates an interim 180 * response for communicating connection status or request progress 181 * prior to completing the requested action and sending a final 182 * response. {@literal 1xx} responses are terminated by the first empty line after 183 * the status-line (the empty line signaling the end of the header 184 * section). Since HTTP/1.0 did not define any 1xx status codes, a 185 * server MUST NOT send a {@literal 1xx} response to an HTTP/1.0 client. 186 * 187 * <p> 188 * A client MUST be able to parse one or more 1xx responses received 189 * prior to a final response, even if the client does not expect one. A 190 * user agent MAY ignore unexpected {@literal 1xx} responses.</p> 191 * 192 * <p> 193 * A proxy MUST forward {@literal 1xx} responses unless the proxy itself requested 194 * the generation of the 1xx response. For example, if a proxy adds an 195 * {@literal "Expect: 100-continue"} field when it forwards a request, then it need 196 * not forward the corresponding 100 (Continue) response(s).</p> 197 */ 198 INFORMATIONAL, 199 200 /** 201 * The {@literal 2xx} (Successful) class of status code indicates that the client's 202 $ request was successfully received, understood, and accepted. 203 */ 204 SUCCESSFUL, 205 206 /** 207 * The {@literal 3xx} (Redirection) class of status code indicates that further 208 * action needs to be taken by the user agent in order to fulfill the 209 * request. If a {@literal Location} header field (Section 7.1.2) is provided, the 210 * user agent MAY automatically redirect its request to the URI 211 * referenced by the {@literal Location} field value, even if the specific status 212 * code is not understood. Automatic redirection needs to done with 213 * care for methods not known to be safe, as defined in Section 4.2.1, 214 * since the user might not wish to redirect an unsafe request. 215 * 216 * <p> 217 * There are several types of redirects: 218 * </p> 219 * <ol> 220 * <li>Redirects that indicate the resource might be available at a 221 * different URI, as provided by the Location field, as in the 222 * status codes {@literal 301} (Moved Permanently), 302 (Found), and 307 223 * (Temporary Redirect).</li> 224 * 225 * <li>Redirection that offers a choice of matching resources, each 226 * capable of representing the original request target, as in the 227 * 300 (Multiple Choices) status code.</li> 228 * 229 * <li>Redirection to a different resource, identified by the Location 230 * field, that can represent an indirect response to the request, as 231 * in the 303 (See Other) status code.</li> 232 * 233 * <li>Redirection to a previously cached result, as in the 304 (Not 234 * Modified) status code. 235 * <p> 236 * Note: In HTTP/1.0, the status codes 301 (Moved Permanently) and 237 * 302 (Found) were defined for the first type of redirect 238 * ([RFC1945], Section 9.3). Early user agents split on whether the 239 * method applied to the redirect target would be the same as the 240 * original request or would be rewritten as GET. Although HTTP 241 * originally defined the former semantics for 301 and 302 (to match 242 * its original implementation at CERN), and defined 303 (See Other) 243 * to match the latter semantics, prevailing practice gradually 244 * converged on the latter semantics for 301 and 302 as well. The 245 * first revision of HTTP/1.1 added 307 (Temporary Redirect) to 246 * indicate the former semantics without being impacted by divergent 247 * practice. Over 10 years later, most user agents still do method 248 * rewriting for 301 and 302; therefore, this specification makes 249 * that behavior conformant when the original request is POST.</p> 250 * </li> 251 * </ol> 252 * 253 * <p> 254 * A client SHOULD detect and intervene in cyclical redirections (i.e., 255 * "infinite" redirection loops). 256 * <br> 257 * Note: An earlier version of this specification recommended a 258 * maximum of five redirections ([RFC2068], Section 10.3). Content 259 * developers need to be aware that some clients might implement such 260 * a fixed limitation.</p> 261 */ 262 REDIRECTION, 263 264 /** 265 * The {@literal 4xx} (Client Error) class of status code indicates that the client 266 * seems to have erred. Except when responding to a {@literal HEAD} request, the 267 * server SHOULD send a representation containing an explanation of the 268 * error situation, and whether it is a temporary or permanent 269 * condition. These status codes are applicable to any request method. 270 * User agents SHOULD display any included representation to the user. 271 */ 272 CLIENT_ERROR, 273 274 /** 275 * The {@literal 5xx} (Server Error) class of status code indicates that the server 276 * is aware that it has erred or is incapable of performing the 277 * requested method. Except when responding to a {@literal HEAD} request, the 278 * server SHOULD send a representation containing an explanation of the 279 * error situation, and whether it is a temporary or permanent 280 * condition. A user agent SHOULD display any included representation 281 * to the user. These response codes are applicable to any request 282 * method. 283 */ 284 SERVER_ERROR, 285 286 /** 287 * This class of status code is for all status code above 600, that are not classified in the specification. 288 */ 289 UNKNOWN; 290 291 /** 292 * Find the class of the given status code. 293 * A {@link IllegalArgumentException} will be thrown if the given integer is negative or superior to 999. 294 * 295 * @param code 296 * given HTTP status code 297 * @return the {@link Family} of the given code 298 * @see <a href="http://tools.ietf.org/html/rfc1945#section-6.1.1">RFC1945 Status Code and Reason Phrase</a> 299 */ 300 public static Family valueOf(final int code) { 301 if (code < 100 || code >= 1000) { 302 throw new IllegalArgumentException(format("Given code '%d' is invalid", code)); 303 } else if (code >= 100 && code < 200) { 304 return INFORMATIONAL; 305 } else if (code >= 200 && code < 300) { 306 return SUCCESSFUL; 307 } else if (code >= 300 && code < 400) { 308 return REDIRECTION; 309 } else if (code >= 400 && code < 500) { 310 return CLIENT_ERROR; 311 } else if (code >= 500 && code < 600) { 312 return SERVER_ERROR; 313 } else { 314 // No matching family was found but the code's value is valid. 315 return UNKNOWN; 316 } 317 } 318 } 319 320 321 /** 322 * Get a {@link Status} from the given integer. 323 * First try to match a known (supported by this enum) status code, otherwise try to build a new one. 324 * @param code 325 * the three-digit integer code giving the result of the attempt to understand and satisfy the request. 326 * It must be in the range {@code 100 <= code < 1000 } and not already used by another {@link Status}, 327 * otherwise an {@link IllegalArgumentException} is thrown. 328 * @return the {@link Status} 329 */ 330 public static Status valueOf(int code) { 331 return valueOf(code, "Unknown"); 332 } 333 334 /** 335 * Get a {@link Status} from the given integer. 336 * First try to match a known (supported by this enum) status code, otherwise try to build a new one. 337 * @param code 338 * the three-digit integer code giving the result of the attempt to understand and satisfy the request. 339 * It must be in the range {@code 100 <= code < 1000 } and not already used by another {@link Status}, 340 * otherwise an {@link IllegalArgumentException} is thrown. 341 * @param reason 342 * the reason phrase to describe this {@link Status}. It is purely informative. 343 * @return the {@link Status} 344 */ 345 public static Status valueOf(int code, String reason) { 346 Status status = KNOWN_STATUSES.get(code); 347 if (status != null) { 348 return status; 349 } 350 return newStatus(code, reason); 351 } 352 353 private static Status newStatus(final int code, final String reason) { 354 if (KNOWN_STATUSES.containsKey(code)) { 355 throw new IllegalArgumentException(format("The code %s is already registered.", code)); 356 } 357 Status status = new Status(code, reason); 358 KNOWN_STATUSES.put(code, status); 359 return status; 360 } 361 362 // Constants 363 364 /** 365 * The 100 (Continue) status code indicates that the initial part of a 366 * request has been received and has not yet been rejected by the 367 * server. The server intends to send a final response after the 368 * request has been fully received and acted upon. 369 * 370 * When the request contains an Expect header field that includes a 371 * 100-continue expectation, the 100 response indicates that the server 372 * wishes to receive the request payload body, as described in 373 * Section 5.1.1. The client ought to continue sending the request and 374 * discard the 100 response. 375 * 376 * If the request did not contain an Expect header field containing the 377 * 100-continue expectation, the client can simply discard this interim 378 * response. 379 */ 380 public static final Status CONTINUE = newStatus(100, "Continue"); 381 382 /** 383 * The 101 (Switching Protocols) status code indicates that the server 384 * understands and is willing to comply with the client's request, via 385 * the Upgrade header field (Section 6.7 of [RFC7230]), for a change in 386 * the application protocol being used on this connection. The server 387 * MUST generate an Upgrade header field in the response that indicates 388 * which protocol(s) will be switched to immediately after the empty 389 * line that terminates the 101 response. 390 * 391 * It is assumed that the server will only agree to switch protocols 392 * when it is advantageous to do so. For example, switching to a newer 393 * version of HTTP might be advantageous over older versions, and 394 * switching to a real-time, synchronous protocol might be advantageous 395 * when delivering resources that use such features. 396 */ 397 public static final Status SWITCHING_PROTOCOLS = newStatus(101, "Switching Protocols"); 398 399 /** 400 * The 200 (OK) status code indicates that the request has succeeded. 401 * The payload sent in a 200 response depends on the request method. 402 * For the methods defined by this specification, the intended meaning 403 * of the payload can be summarized as: 404 * 405 * GET a representation of the target resource; 406 * 407 * HEAD the same representation as GET, but without the representation 408 * data; 409 * 410 * POST a representation of the status of, or results obtained from, 411 * the action; 412 * 413 * PUT, DELETE a representation of the status of the action; 414 * 415 * OPTIONS a representation of the communications options; 416 * 417 * TRACE a representation of the request message as received by the end 418 * server. 419 * 420 * Aside from responses to CONNECT, a 200 response always has a payload, 421 * though an origin server MAY generate a payload body of zero length. 422 * If no payload is desired, an origin server ought to send 204 (No 423 * Content) instead. For CONNECT, no payload is allowed because the 424 * successful result is a tunnel, which begins immediately after the 200 425 * response header section. 426 * 427 * A 200 response is cacheable by default; i.e., unless otherwise 428 * indicated by the method definition or explicit cache controls (see 429 * Section 4.2.2 of [RFC7234]). 430 */ 431 public static final Status OK = newStatus(200, "OK"); 432 433 /** 434 * The 201 (Created) status code indicates that the request has been 435 * fulfilled and has resulted in one or more new resources being 436 * created. The primary resource created by the request is identified 437 * by either a Location header field in the response or, if no Location 438 * field is received, by the effective request URI. 439 * 440 * The 201 response payload typically describes and links to the 441 * resource(s) created. See Section 7.2 for a discussion of the meaning 442 * and purpose of validator header fields, such as ETag and 443 * Last-Modified, in a 201 response. 444 */ 445 public static final Status CREATED = newStatus(201, "Created"); 446 447 /** 448 * The 202 (Accepted) status code indicates that the request has been 449 * accepted for processing, but the processing has not been completed. 450 * The request might or might not eventually be acted upon, as it might 451 * be disallowed when processing actually takes place. There is no 452 * facility in HTTP for re-sending a status code from an asynchronous 453 * operation. 454 * 455 * The 202 response is intentionally noncommittal. Its purpose is to 456 * allow a server to accept a request for some other process (perhaps a 457 * batch-oriented process that is only run once per day) without 458 * requiring that the user agent's connection to the server persist 459 * until the process is completed. The representation sent with this 460 * response ought to describe the request's current status and point to 461 * (or embed) a status monitor that can provide the user with an 462 * estimate of when the request will be fulfilled. 463 */ 464 public static final Status ACCEPTED = newStatus(202, "Accepted"); 465 466 /** 467 * The 203 (Non-Authoritative Information) status code indicates that 468 * the request was successful but the enclosed payload has been modified 469 * from that of the origin server's 200 (OK) response by a transforming 470 * proxy (Section 5.7.2 of [RFC7230]). This status code allows the 471 * proxy to notify recipients when a transformation has been applied, 472 * since that knowledge might impact later decisions regarding the 473 * content. For example, future cache validation requests for the 474 * content might only be applicable along the same request path (through 475 * the same proxies). 476 * 477 * The 203 response is similar to the Warning code of 214 Transformation 478 * Applied (Section 5.5 of [RFC7234]); which has the advantage of being 479 * applicable to responses with any status code. 480 * 481 * A 203 response is cacheable by default; i.e., unless otherwise 482 * indicated by the method definition or explicit cache controls (see 483 * Section 4.2.2 of [RFC7234]). 484 */ 485 public static final Status NON_AUTHORITATIVE_INFO = newStatus(203, "Non-Authoritative Information"); 486 487 /** 488 * The 204 (No Content) status code indicates that the server has 489 * successfully fulfilled the request and that there is no additional 490 * content to send in the response payload body. Metadata in the 491 * response header fields refer to the target resource and its selected 492 * representation after the requested action was applied. 493 * 494 * For example, if a 204 status code is received in response to a PUT 495 * request and the response contains an ETag header field, then the PUT 496 * was successful and the ETag field-value contains the entity-tag for 497 * the new representation of that target resource. 498 * 499 * The 204 response allows a server to indicate that the action has been 500 * successfully applied to the target resource, while implying that the 501 * user agent does not need to traverse away from its current "document 502 * view" (if any). The server assumes that the user agent will provide 503 * some indication of the success to its user, in accord with its own 504 * interface, and apply any new or updated metadata in the response to 505 * its active representation. 506 * 507 * For example, a 204 status code is commonly used with document editing 508 * interfaces corresponding to a "save" action, such that the document 509 * being saved remains available to the user for editing. It is also 510 * frequently used with interfaces that expect automated data transfers 511 * to be prevalent, such as within distributed version control systems. 512 * 513 * A 204 response is terminated by the first empty line after the header 514 * fields because it cannot contain a message body. 515 * 516 * A 204 response is cacheable by default; i.e., unless otherwise 517 * indicated by the method definition or explicit cache controls (see 518 * Section 4.2.2 of [RFC7234]). 519 */ 520 public static final Status NO_CONTENT = newStatus(204, "No Content"); 521 522 /** 523 * The 205 (Reset Content) status code indicates that the server has 524 * fulfilled the request and desires that the user agent reset the 525 * "document view", which caused the request to be sent, to its original 526 * state as received from the origin server. 527 * 528 * This response is intended to support a common data entry use case 529 * where the user receives content that supports data entry (a form, 530 * notepad, canvas, etc.), enters or manipulates data in that space, 531 * causes the entered data to be submitted in a request, and then the 532 * data entry mechanism is reset for the next entry so that the user can 533 * easily initiate another input action. 534 * 535 * Since the 205 status code implies that no additional content will be 536 * provided, a server MUST NOT generate a payload in a 205 response. In 537 * other words, a server MUST do one of the following for a 205 538 * response: a) indicate a zero-length body for the response by 539 * including a Content-Length header field with a value of 0; b) 540 * indicate a zero-length payload for the response by including a 541 * Transfer-Encoding header field with a value of chunked and a message 542 * body consisting of a single chunk of zero-length; or, c) close the 543 * connection immediately after sending the blank line terminating the 544 * header section. 545 */ 546 public static final Status RESET_CONTENT = newStatus(205, "Reset Content"); 547 548 /** 549 * The 300 (Multiple Choices) status code indicates that the target 550 * resource has more than one representation, each with its own more 551 * specific identifier, and information about the alternatives is being 552 * provided so that the user (or user agent) can select a preferred 553 * representation by redirecting its request to one or more of those 554 * identifiers. In other words, the server desires that the user agent 555 * engage in reactive negotiation to select the most appropriate 556 * representation(s) for its needs (Section 3.4). 557 * 558 * If the server has a preferred choice, the server SHOULD generate a 559 * Location header field containing a preferred choice's URI reference. 560 * The user agent MAY use the Location field value for automatic 561 * redirection. 562 * 563 * For request methods other than HEAD, the server SHOULD generate a 564 * payload in the 300 response containing a list of representation 565 * metadata and URI reference(s) from which the user or user agent can 566 * choose the one most preferred. The user agent MAY make a selection 567 * from that list automatically if it understands the provided media 568 * type. A specific format for automatic selection is not defined by 569 * this specification because HTTP tries to remain orthogonal to the 570 * definition of its payloads. In practice, the representation is 571 * provided in some easily parsed format believed to be acceptable to 572 * the user agent, as determined by shared design or content 573 * negotiation, or in some commonly accepted hypertext format. 574 * 575 * A 300 response is cacheable by default; i.e., unless otherwise 576 * indicated by the method definition or explicit cache controls (see 577 * Section 4.2.2 of [RFC7234]). 578 * 579 * Note: The original proposal for the 300 status code defined the 580 * URI header field as providing a list of alternative 581 * representations, such that it would be usable for 200, 300, and 582 * 406 responses and be transferred in responses to the HEAD method. 583 * However, lack of deployment and disagreement over syntax led to 584 * both URI and Alternates (a subsequent proposal) being dropped from 585 * this specification. It is possible to communicate the list using 586 * a set of Link header fields [RFC5988], each with a relationship of 587 * "alternate", though deployment is a chicken-and-egg problem. 588 */ 589 public static final Status MULTIPLE_CHOICES = newStatus(300, "Multiple Choices"); 590 591 /** 592 * The 301 (Moved Permanently) status code indicates that the target 593 * resource has been assigned a new permanent URI and any future 594 * references to this resource ought to use one of the enclosed URIs. 595 * Clients with link-editing capabilities ought to automatically re-link 596 * references to the effective request URI to one or more of the new 597 * references sent by the server, where possible. 598 * 599 * The server SHOULD generate a Location header field in the response 600 * containing a preferred URI reference for the new permanent URI. The 601 * user agent MAY use the Location field value for automatic 602 * redirection. The server's response payload usually contains a short 603 * hypertext note with a hyperlink to the new URI(s). 604 * 605 * Note: For historical reasons, a user agent MAY change the request 606 * method from POST to GET for the subsequent request. If this 607 * behavior is undesired, the 307 (Temporary Redirect) status code 608 * can be used instead. 609 * 610 * A 301 response is cacheable by default; i.e., unless otherwise 611 * indicated by the method definition or explicit cache controls (see 612 * Section 4.2.2 of [RFC7234]). 613 */ 614 public static final Status MOVED_PERMANENTLY = newStatus(301, "Moved Permanently"); 615 616 /** 617 * The 302 (Found) status code indicates that the target resource 618 * resides temporarily under a different URI. Since the redirection 619 * might be altered on occasion, the client ought to continue to use the 620 * effective request URI for future requests. 621 * 622 * The server SHOULD generate a Location header field in the response 623 * containing a URI reference for the different URI. The user agent MAY 624 * use the Location field value for automatic redirection. The server's 625 * response payload usually contains a short hypertext note with a 626 * hyperlink to the different URI(s). 627 * 628 * Note: For historical reasons, a user agent MAY change the request 629 * method from POST to GET for the subsequent request. If this 630 * behavior is undesired, the 307 (Temporary Redirect) status code 631 * can be used instead. 632 */ 633 public static final Status FOUND = newStatus(302, "Found"); 634 635 /** 636 * The 303 (See Other) status code indicates that the server is 637 * redirecting the user agent to a different resource, as indicated by a 638 * URI in the Location header field, which is intended to provide an 639 * indirect response to the original request. A user agent can perform 640 * a retrieval request targeting that URI (a GET or HEAD request if 641 * using HTTP), which might also be redirected, and present the eventual 642 * result as an answer to the original request. Note that the new URI 643 * in the Location header field is not considered equivalent to the 644 * effective request URI. 645 * 646 * This status code is applicable to any HTTP method. It is primarily 647 * used to allow the output of a POST action to redirect the user agent 648 * to a selected resource, since doing so provides the information 649 * corresponding to the POST response in a form that can be separately 650 * identified, bookmarked, and cached, independent of the original 651 * request. 652 * 653 * A 303 response to a GET request indicates that the origin server does 654 * not have a representation of the target resource that can be 655 * transferred by the server over HTTP. However, the Location field 656 * value refers to a resource that is descriptive of the target 657 * resource, such that making a retrieval request on that other resource 658 * might result in a representation that is useful to recipients without 659 * implying that it represents the original target resource. Note that 660 * answers to the questions of what can be represented, what 661 * representations are adequate, and what might be a useful description 662 * are outside the scope of HTTP. 663 * 664 * Except for responses to a HEAD request, the representation of a 303 665 * response ought to contain a short hypertext note with a hyperlink to 666 * the same URI reference provided in the Location header field. 667 */ 668 public static final Status SEE_OTHER = newStatus(303, "See Other"); 669 670 /** 671 * The 305 (Use Proxy) status code was defined in a previous version of 672 * this specification and is now deprecated (Appendix B). 673 */ 674 public static final Status USE_PROXY = newStatus(305, "Use Proxy"); 675 676 /** 677 * The 306 status code was defined in a previous version of this 678 * specification, is no longer used, and the code is reserved. 679 */ 680 public static final Status UNUSED = newStatus(306, "Unused"); 681 682 /** 683 * The 307 (Temporary Redirect) status code indicates that the target 684 * resource resides temporarily under a different URI and the user agent 685 * MUST NOT change the request method if it performs an automatic 686 * redirection to that URI. Since the redirection can change over time, 687 * the client ought to continue using the original effective request URI 688 * for future requests. 689 * 690 * The server SHOULD generate a Location header field in the response 691 * containing a URI reference for the different URI. The user agent MAY 692 * use the Location field value for automatic redirection. The server's 693 * response payload usually contains a short hypertext note with a 694 * hyperlink to the different URI(s). 695 * 696 * Note: This status code is similar to 302 (Found), except that it 697 * does not allow changing the request method from POST to GET. This 698 * specification defines no equivalent counterpart for 301 (Moved 699 * Permanently) ([RFC7238], however, defines the status code 308 700 * (Permanent Redirect) for this purpose). 701 */ 702 public static final Status TEMPORARY_REDIRECT = newStatus(307, "Temporary Redirect"); 703 704 // TODO Add 308 (Permanent Redirect) ? https://tools.ietf.org/html/rfc7238 705 706 /** 707 * The 400 (Bad Request) status code indicates that the server cannot or 708 * will not process the request due to something that is perceived to be 709 * a client error (e.g., malformed request syntax, invalid request 710 * message framing, or deceptive request routing). 711 */ 712 public static final Status BAD_REQUEST = newStatus(400, "Bad Request"); 713 714 /** 715 * The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 716 * 14.47) containing a challenge applicable to the requested resource. The client MAY repeat the request with a 717 * suitable Authorization header field (section 14.8). If the request already included Authorization credentials, 718 * then the 401 response indicates that authorization has been refused for those credentials. If the 401 response 719 * contains the same challenge as the prior response, and the user agent has already attempted authentication at 720 * least once, then the user SHOULD be presented the entity that was given in the response, since that entity might 721 * include relevant diagnostic information. HTTP access authentication is explained in 722 * "HTTP Authentication: Basic and Digest Access Authentication" (see RFC 2617). 723 * 724 * @see <a href="http://tools.ietf.org/html/rfc7231">RFC 7231 : Hypertext Transfer Protocol (HTTP/1.1): Semantics 725 * and Content</a> 726 * @see <a href="http://tools.ietf.org/html/rfc2617">RFC 2617 : HTTP Authentication: Basic and Digest Access 727 * Authentication</a> 728 */ 729 public static final Status UNAUTHORIZED = newStatus(401, "Unauthorized"); 730 731 /** 732 * The 402 (Payment Required) status code is reserved for future use. 733 */ 734 public static final Status PAYMENT_REQUIRED = newStatus(402, "Payment Required"); 735 736 /** 737 * The 403 (Forbidden) status code indicates that the server understood 738 * the request but refuses to authorize it. A server that wishes to 739 * make public why the request has been forbidden can describe that 740 * reason in the response payload (if any). 741 * 742 * If authentication credentials were provided in the request, the 743 * server considers them insufficient to grant access. The client 744 * SHOULD NOT automatically repeat the request with the same 745 * credentials. The client MAY repeat the request with new or different 746 * credentials. However, a request might be forbidden for reasons 747 * unrelated to the credentials. 748 * 749 * An origin server that wishes to "hide" the current existence of a 750 * forbidden target resource MAY instead respond with a status code of 751 * 404 (Not Found). 752 */ 753 public static final Status FORBIDDEN = newStatus(403, "Forbidden"); 754 755 /** 756 * The 404 (Not Found) status code indicates that the origin server did 757 * not find a current representation for the target resource or is not 758 * willing to disclose that one exists. A 404 status code does not 759 * indicate whether this lack of representation is temporary or 760 * permanent; the 410 (Gone) status code is preferred over 404 if the 761 * origin server knows, presumably through some configurable means, that 762 * the condition is likely to be permanent. 763 * 764 * A 404 response is cacheable by default; i.e., unless otherwise 765 * indicated by the method definition or explicit cache controls (see 766 * Section 4.2.2 of [RFC7234]). 767 */ 768 public static final Status NOT_FOUND = newStatus(404, "Not Found"); 769 770 /** 771 * The 405 (Method Not Allowed) status code indicates that the method 772 * received in the request-line is known by the origin server but not 773 * supported by the target resource. The origin server MUST generate an 774 * Allow header field in a 405 response containing a list of the target 775 * resource's currently supported methods. 776 * 777 * A 405 response is cacheable by default; i.e., unless otherwise 778 * indicated by the method definition or explicit cache controls (see 779 * Section 4.2.2 of [RFC7234]). 780 */ 781 public static final Status METHOD_NOT_ALLOWED = newStatus(405, "Method Not Allowed"); 782 783 /** 784 * The 406 (Not Acceptable) status code indicates that the target 785 * resource does not have a current representation that would be 786 * acceptable to the user agent, according to the proactive negotiation 787 * header fields received in the request (Section 5.3), and the server 788 * is unwilling to supply a default representation. 789 * 790 * The server SHOULD generate a payload containing a list of available 791 * representation characteristics and corresponding resource identifiers 792 * from which the user or user agent can choose the one most 793 * appropriate. A user agent MAY automatically select the most 794 * appropriate choice from that list. However, this specification does 795 * not define any standard for such automatic selection, as described in 796 * Section 6.4.1. 797 */ 798 public static final Status NOT_ACCEPTABLE = newStatus(406, "Not Acceptable"); 799 800 /** 801 * The 408 (Request Timeout) status code indicates that the server did 802 * not receive a complete request message within the time that it was 803 * prepared to wait. A server SHOULD send the "close" connection option 804 * (Section 6.1 of [RFC7230]) in the response, since 408 implies that 805 * the server has decided to close the connection rather than continue 806 * waiting. If the client has an outstanding request in transit, the 807 * client MAY repeat that request on a new connection. 808 */ 809 public static final Status REQUEST_TIMEOUT = newStatus(408, "Request Timeout"); 810 811 /** 812 * The 409 (Conflict) status code indicates that the request could not 813 * be completed due to a conflict with the current state of the target 814 * resource. This code is used in situations where the user might be 815 * able to resolve the conflict and resubmit the request. The server 816 * SHOULD generate a payload that includes enough information for a user 817 * to recognize the source of the conflict. 818 * 819 * Conflicts are most likely to occur in response to a PUT request. For 820 * example, if versioning were being used and the representation being 821 * PUT included changes to a resource that conflict with those made by 822 * an earlier (third-party) request, the origin server might use a 409 823 * response to indicate that it can't complete the request. In this 824 * case, the response representation would likely contain information 825 * useful for merging the differences based on the revision history. 826 */ 827 public static final Status CONFLICT = newStatus(409, "Conflict"); 828 829 /** 830 * The 410 (Gone) status code indicates that access to the target 831 * resource is no longer available at the origin server and that this 832 * condition is likely to be permanent. If the origin server does not 833 * know, or has no facility to determine, whether or not the condition 834 * is permanent, the status code 404 (Not Found) ought to be used 835 * instead. 836 * 837 * The 410 response is primarily intended to assist the task of web 838 * maintenance by notifying the recipient that the resource is 839 * intentionally unavailable and that the server owners desire that 840 * remote links to that resource be removed. Such an event is common 841 * for limited-time, promotional services and for resources belonging to 842 * individuals no longer associated with the origin server's site. It 843 * is not necessary to mark all permanently unavailable resources as 844 * "gone" or to keep the mark for any length of time -- that is left to 845 * the discretion of the server owner. 846 * 847 * A 410 response is cacheable by default; i.e., unless otherwise 848 * indicated by the method definition or explicit cache controls (see 849 * Section 4.2.2 of [RFC7234]). 850 */ 851 public static final Status GONE = newStatus(410, "Gone"); 852 853 /** 854 * The 411 (Length Required) status code indicates that the server 855 * refuses to accept the request without a defined Content-Length 856 * (Section 3.3.2 of [RFC7230]). The client MAY repeat the request if 857 * it adds a valid Content-Length header field containing the length of 858 * the message body in the request message. 859 */ 860 public static final Status LENGTH_REQUIRED = newStatus(411, "Length Required"); 861 862 /** 863 * The 413 (Payload Too Large) status code indicates that the server is 864 * refusing to process a request because the request payload is larger 865 * than the server is willing or able to process. The server MAY close 866 * the connection to prevent the client from continuing the request. 867 * 868 * If the condition is temporary, the server SHOULD generate a 869 * Retry-After header field to indicate that it is temporary and after 870 * what time the client MAY try again. 871 */ 872 public static final Status PAYLOAD_TOO_LARGE = newStatus(413, "Payload Too Large"); 873 874 /** 875 * The 414 (URI Too Long) status code indicates that the server is 876 * refusing to service the request because the request-target (Section 877 * 5.3 of [RFC7230]) is longer than the server is willing to interpret. 878 * This rare condition is only likely to occur when a client has 879 * improperly converted a POST request to a GET request with long query 880 * information, when the client has descended into a "black hole" of 881 * redirection (e.g., a redirected URI prefix that points to a suffix of 882 * itself) or when the server is under attack by a client attempting to 883 * exploit potential security holes. 884 * 885 * A 414 response is cacheable by default; i.e., unless otherwise 886 * indicated by the method definition or explicit cache controls (see 887 * Section 4.2.2 of [RFC7234]). 888 */ 889 public static final Status URI_TOO_LONG = newStatus(414, "URI Too Long"); 890 891 /** 892 * The 415 (Unsupported Media Type) status code indicates that the 893 * origin server is refusing to service the request because the payload 894 * is in a format not supported by this method on the target resource. 895 * The format problem might be due to the request's indicated 896 * Content-Type or Content-Encoding, or as a result of inspecting the 897 * data directly. 898 */ 899 public static final Status UNSUPPORTED_MEDIA_TYPE = newStatus(415, "Unsupported Media Type"); 900 901 /** 902 * The 417 (Expectation Failed) status code indicates that the 903 * expectation given in the request's Expect header field 904 * (Section 5.1.1) could not be met by at least one of the inbound 905 * servers. 906 */ 907 public static final Status EXPECTATION_FAILED = newStatus(417, "Expectation Failed"); 908 909 /** 910 * Any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot". The resulting entity 911 * body MAY be short and stout. This code was defined in 1998 as one of the traditional IETF April Fools' jokes, in 912 * RFC 2324, Hyper Text Coffee Pot Control Protocol, and is not expected to be implemented by actual HTTP servers. 913 * The RFC specifies this code should be returned by tea pots requested to brew coffee. 914 * 915 * @see <a href="http://tools.ietf.org/html/rfc2324">Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)</a> 916 */ 917 public static final Status TEAPOT = newStatus(418, "I'm a teapot"); 918 919 /** 920 * The 426 (Upgrade Required) status code indicates that the server 921 * refuses to perform the request using the current protocol but might 922 * be willing to do so after the client upgrades to a different 923 * protocol. The server MUST send an Upgrade header field in a 426 924 * response to indicate the required protocol(s) (Section 6.7 of 925 * [RFC7230]). 926 * 927 * Example: 928 * 929 * <pre>{@code 930 * HTTP/1.1 426 Upgrade Required 931 * Upgrade: HTTP/3.0 932 * Connection: Upgrade 933 * Content-Length: 53 934 * Content-Type: text/plain 935 * }</pre> 936 * 937 * This service requires use of the HTTP/3.0 protocol. 938 */ 939 public static final Status UPGRADE_REQUIRED = newStatus(426, "Upgrade Required"); 940 941 942 /** 943 * The 429 status code indicates that the user has sent too many requests in a given amount of time 944 * ("rate limiting"). The response representations SHOULD include details explaining the condition, and MAY include 945 * a Retry-After header indicating how long to wait before making a new request. 946 * 947 * For example: 948 * 949 * <pre>{@code 950 * HTTP/1.1 429 Too Many Requests 951 * Content-Type: text/html 952 * Retry-After: 3600 953 * 954 * <html> 955 * <head> 956 * <title>Too Many Requests</title> 957 * </head> 958 * <body> 959 * <h1>Too Many Requests</h1> 960 * <p>I only allow 50 requests per hour to this Web site per logged in user. Try again soon.</p> 961 * </body> 962 * </html> 963 * }</pre> 964 * 965 * Note that this specification does not define how the origin server identifies the user, nor how 966 * it counts requests. For example, an origin server that is limiting request rates can do so based upon counts of 967 * requests on a per-resource basis, across the entire server, or even among a set of servers. Likewise, it might 968 * identify the user by its authentication credentials, or a stateful cookie. Responses with the 429 status code 969 * MUST NOT be stored by a cache. 970 * 971 * @see <a href="http://tools.ietf.org/html/rfc6585">Additional HTTP Status Codes</a> 972 */ 973 public static final Status TOO_MANY_REQUESTS = newStatus(429, "Too Many Requests"); 974 975 /** 976 * The 500 (Internal Server Error) status code indicates that the server 977 * encountered an unexpected condition that prevented it from fulfilling 978 * the request. 979 */ 980 public static final Status INTERNAL_SERVER_ERROR = newStatus(500, "Internal Server Error"); 981 982 /** 983 * The 501 (Not Implemented) status code indicates that the server does 984 * not support the functionality required to fulfill the request. This 985 * is the appropriate response when the server does not recognize the 986 * request method and is not capable of supporting it for any resource. 987 * 988 * A 501 response is cacheable by default; i.e., unless otherwise 989 * indicated by the method definition or explicit cache controls (see 990 * Section 4.2.2 of [RFC7234]). 991 */ 992 public static final Status NOT_IMPLEMENTED = newStatus(501, "Not Implemented"); 993 994 /** 995 * The 502 (Bad Gateway) status code indicates that the server, while 996 * acting as a gateway or proxy, received an invalid response from an 997 * inbound server it accessed while attempting to fulfill the request. 998 */ 999 public static final Status BAD_GATEWAY = newStatus(502, "Bad Gateway"); 1000 1001 /** 1002 * The 503 (Service Unavailable) status code indicates that the server 1003 * is currently unable to handle the request due to a temporary overload 1004 * or scheduled maintenance, which will likely be alleviated after some 1005 * delay. The server MAY send a Retry-After header field 1006 * (Section 7.1.3) to suggest an appropriate amount of time for the 1007 * client to wait before retrying the request. 1008 * 1009 * Note: The existence of the 503 status code does not imply that a 1010 * server has to use it when becoming overloaded. Some servers might 1011 * simply refuse the connection. 1012 */ 1013 public static final Status SERVICE_UNAVAILABLE = newStatus(503, "Service Unavailable"); 1014 1015 /** 1016 * The 504 (Gateway Timeout) status code indicates that the server, 1017 * while acting as a gateway or proxy, did not receive a timely response 1018 * from an upstream server it needed to access in order to complete the 1019 * request. 1020 */ 1021 public static final Status GATEWAY_TIMEOUT = newStatus(504, "Gateway Timeout"); 1022 1023 /** 1024 * The 505 (HTTP Version Not Supported) status code indicates that the 1025 * server does not support, or refuses to support, the major version of 1026 * HTTP that was used in the request message. The server is indicating 1027 * that it is unable or unwilling to complete the request using the same 1028 * major version as the client, as described in Section 2.6 of 1029 * [RFC7230], other than with this error message. The server SHOULD 1030 * generate a representation for the 505 response that describes why 1031 * that version is not supported and what other protocols are supported 1032 * by that server. 1033 */ 1034 public static final Status HTTP_VERSION_NOT_SUPPORTED = newStatus(505, "HTTP Version Not Supported"); 1035 1036}