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     * &lt;html&gt;
955     *  &lt;head&gt;
956     *   &lt;title&gt;Too Many Requests&lt;/title&gt;
957     *  &lt;/head&gt;
958     *  &lt;body&gt;
959     *   &lt;h1&gt;Too Many Requests&lt;/h1&gt;
960     *   &lt;p&gt;I only allow 50 requests per hour to this Web site per logged in user. Try again soon.&lt;/p&gt;
961     *   &lt;/body&gt;
962     * &lt;/html&gt;
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}