Response Handling

/**
 * Extension of HttpEntity that adds an HttpStatusCode status code.
 * Used in RestController methods to represent the complete HTTP response.
 *
 * @param <T> the body type
 */
public class ResponseEntity<T> extends HttpEntity<T> {
    /**
     * Create a ResponseEntity with a status code only.
     *
     * @param status the status code
     */
    public ResponseEntity(HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with a body and a status code.
     *
     * @param body the entity body
     * @param status the status code
     */
    public ResponseEntity(@Nullable T body, HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with headers and a status code.
     *
     * @param headers the entity headers
     * @param status the status code
     * @deprecated since 7.0, in favor of {@link #ResponseEntity(HttpHeaders, HttpStatusCode)}
     */
    @Deprecated(since = "7.0")
    public ResponseEntity(MultiValueMap<String, String> headers, HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with a body, headers, and a status code.
     *
     * @param body the entity body
     * @param headers the entity headers
     * @param status the status code
     * @deprecated since 7.0, in favor of {@link #ResponseEntity(Object, HttpHeaders, HttpStatusCode)}
     */
    @Deprecated(since = "7.0")
    public ResponseEntity(T body, MultiValueMap<String, String> headers, HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with headers and a status code.
     *
     * @param headers the entity headers
     * @param status the status code
     * @since 7.0
     */
    public ResponseEntity(HttpHeaders headers, HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with a body, headers, and a status code.
     *
     * @param body the entity body
     * @param headers the entity headers
     * @param status the status code
     * @since 7.0
     */
    public ResponseEntity(@Nullable T body, HttpHeaders headers, HttpStatusCode status) {}

    /**
     * Create a ResponseEntity with a body, headers, and a raw status code.
     *
     * @param body the entity body
     * @param headers the entity headers
     * @param rawStatus the status code value
     * @since 7.0
     */
    public ResponseEntity(@Nullable T body, @Nullable HttpHeaders headers, int rawStatus) {}

    /**
     * Return the HTTP status code of the response.
     *
     * @return the HTTP status as an HttpStatusCode value
     */
    public HttpStatusCode getStatusCode() {}

    // Static factory methods

    /**
     * Create a builder with the given status.
     *
     * @param status the response status
     * @return the created builder
     */
    public static BodyBuilder status(HttpStatusCode status) {}

    /**
     * Create a builder with the given status.
     *
     * @param status the response status
     * @return the created builder
     */
    public static BodyBuilder status(int status) {}

    /**
     * Create a builder with the status set to OK (200).
     *
     * @return the created builder
     */
    public static BodyBuilder ok() {}

    /**
     * A shortcut for creating a ResponseEntity with the given body and status OK.
     *
     * @param body the body of the response entity
     * @param <T> the type of the body
     * @return the created ResponseEntity
     */
    public static <T> ResponseEntity<T> ok(T body) {}

    /**
     * Create a new builder with a CREATED (201) status and a location header
     * set to the given URI.
     *
     * @param location the location URI
     * @return the created builder
     */
    public static BodyBuilder created(URI location) {}

    /**
     * Create a builder with an ACCEPTED (202) status.
     *
     * @return the created builder
     */
    public static BodyBuilder accepted() {}

    /**
     * Create a builder with a NO_CONTENT (204) status.
     *
     * @return the created builder
     */
    public static HeadersBuilder<?> noContent() {}

    /**
     * Create a builder with a BAD_REQUEST (400) status.
     *
     * @return the created builder
     */
    public static BodyBuilder badRequest() {}

    /**
     * Create a builder with a NOT_FOUND (404) status.
     *
     * @return the created builder
     */
    public static HeadersBuilder<?> notFound() {}

    /**
     * Create a builder with an UNPROCESSABLE_ENTITY (422) status.
     *
     * @return the created builder
     * @deprecated since 7.0, in favor of {@link #unprocessableContent()}
     */
    @Deprecated(since = "7.0")
    public static BodyBuilder unprocessableEntity() {}

    /**
     * Create a builder with an UNPROCESSABLE_CONTENT (422) status.
     *
     * @return the created builder
     * @since 7.0
     */
    public static BodyBuilder unprocessableContent() {}

    /**
     * Create a builder with an INTERNAL_SERVER_ERROR (500) status.
     *
     * @return the created builder
     * @since 6.2
     */
    public static BodyBuilder internalServerError() {}

    /**
     * Create a new builder with the given optional body.
     * Returns a builder with status 200 OK if the body is present,
     * or a builder with status 404 NOT FOUND if empty.
     *
     * @param body an optional body
     * @param <T> the type of the body
     * @return the created builder
     * @since 5.1
     */
    public static <T> ResponseEntity<T> of(Optional<T> body) {}

    /**
     * Create a new builder with the given nullable body.
     * Returns a builder with status 200 OK if the body is non-null,
     * or a builder with status 404 NOT FOUND if null.
     *
     * @param body a nullable body
     * @param <T> the type of the body
     * @return the created builder
     * @since 5.1
     */
    public static <T> ResponseEntity<T> ofNullable(@Nullable T body) {}

    /**
     * Create a new builder with its status set to the ProblemDetail's status
     * and its body set to the ProblemDetail.
     * This is a convenience method for creating RFC 9457 error responses.
     *
     * @param body the ProblemDetail body
     * @return the created builder
     * @since 6.0
     */
    public static HeadersBuilder<?> of(ProblemDetail body) {}

    /**
     * Defines a builder that adds headers to the response entity.
     *
     * @param <B> the builder subclass
     */
    public interface HeadersBuilder<B extends HeadersBuilder<B>> {
        /**
         * Add the given, single header value under the given name.
         *
         * @param headerName the header name
         * @param headerValues the header value(s)
         * @return this builder
         */
        B header(String headerName, String... headerValues);

        /**
         * Copy the given headers into the entity's headers map.
         *
         * @param headers the existing HttpHeaders to copy from
         * @return this builder
         */
        B headers(HttpHeaders headers);

        /**
         * Manipulate this entity's headers with the given consumer.
         *
         * @param headersConsumer a function that consumes the HttpHeaders
         * @return this builder
         */
        B headers(Consumer<HttpHeaders> headersConsumer);

        /**
         * Set the set of allowed HTTP methods, as specified by the Allow header.
         *
         * @param allowedMethods the allowed methods
         * @return this builder
         */
        B allow(HttpMethod... allowedMethods);

        /**
         * Set the entity tag of the body, as specified by the ETag header.
         *
         * @param etag the new entity tag
         * @return this builder
         */
        B eTag(String etag);

        /**
         * Set the time the resource was last changed, as specified by the
         * Last-Modified header.
         *
         * @param lastModified the last modified date
         * @return this builder
         */
        B lastModified(ZonedDateTime lastModified);

        /**
         * Set the time the resource was last changed, as specified by the
         * Last-Modified header.
         *
         * @param lastModified the last modified date
         * @return this builder
         */
        B lastModified(Instant lastModified);

        /**
         * Set the time the resource was last changed, as specified by the
         * Last-Modified header.
         *
         * @param lastModified the last modified date (in milliseconds since epoch)
         * @return this builder
         */
        B lastModified(long lastModified);

        /**
         * Set the location of a resource, as specified by the Location header.
         *
         * @param location the location
         * @return this builder
         */
        B location(URI location);

        /**
         * Set the caching directives for the resource, as specified by the
         * Cache-Control header.
         *
         * @param cacheControl a builder for cache-related HTTP response headers
         * @return this builder
         */
        B cacheControl(CacheControl cacheControl);

        /**
         * Configure one or more request header names to vary the response by.
         *
         * @param requestHeaders request header names
         * @return this builder
         */
        B varyBy(String... requestHeaders);

        /**
         * Build the response entity with no body.
         *
         * @return the response entity
         */
        ResponseEntity<Void> build();
    }

    /**
     * Defines a builder that adds a body to the response entity.
     */
    public interface BodyBuilder extends HeadersBuilder<BodyBuilder> {
        /**
         * Set the length of the body in bytes, as specified by the Content-Length header.
         *
         * @param contentLength the content length
         * @return this builder
         */
        BodyBuilder contentLength(long contentLength);

        /**
         * Set the media type of the body, as specified by the Content-Type header.
         *
         * @param contentType the content type
         * @return this builder
         */
        BodyBuilder contentType(MediaType contentType);

        /**
         * Set the body of the response entity and return it.
         *
         * @param body the body of the response entity
         * @param <T> the type of the body
         * @return the built response entity
         */
        <T> ResponseEntity<T> body(T body);
    }
}

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        Product product = productService.findById(id);
        if (product == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok()
            .eTag(product.getVersion())
            .lastModified(product.getUpdatedAt())
            .body(product);
    }

    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody Product product) {
        Product created = productService.save(product);
        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();
        return ResponseEntity.created(location)
            .contentType(MediaType.APPLICATION_JSON)
            .body(created);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Product> updateProduct(
            @PathVariable Long id,
            @RequestBody Product product,
            @RequestHeader(value = "If-Match", required = false) String ifMatch) {
        Product existing = productService.findById(id);
        if (existing == null) {
            return ResponseEntity.notFound().build();
        }
        if (ifMatch != null && !ifMatch.equals(existing.getVersion())) {
            return ResponseEntity.status(HttpStatus.PRECONDITION_FAILED).build();
        }
        Product updated = productService.update(id, product);
        return ResponseEntity.ok()
            .eTag(updated.getVersion())
            .body(updated);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        boolean deleted = productService.delete(id);
        if (!deleted) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.noContent().build();
    }

    @GetMapping
    public ResponseEntity<List<Product>> getAllProducts() {
        List<Product> products = productService.findAll();
        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(60, TimeUnit.SECONDS))
            .body(products);
    }

    @GetMapping("/search")
    public ResponseEntity<byte[]> exportProducts(@RequestParam String format) {
        byte[] data = productService.export(format);
        return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .contentLength(data.length)
            .header("Content-Disposition", "attachment; filename=products." + format)
            .body(data);
    }
}

/**
 * Represents an HTTP request or response entity, consisting of headers and body.
 *
 * Typically used in combination with RestTemplate or @Controller methods.
 *
 * @param <T> the body type
 */
public class HttpEntity<T> {
    /**
     * The empty HttpEntity, with no body or headers.
     */
    public static final HttpEntity<?> EMPTY = new HttpEntity<>();

    /**
     * Create a new, empty HttpEntity.
     */
    public HttpEntity() {}

    /**
     * Create a new HttpEntity with the given body and no headers.
     *
     * @param body the entity body
     */
    public HttpEntity(T body) {}

    /**
     * Create a new HttpEntity with the given headers and no body.
     *
     * @param headers the entity headers
     */
    public HttpEntity(MultiValueMap<String, String> headers) {}

    /**
     * Create a new HttpEntity with the given body and headers.
     *
     * @param body the entity body
     * @param headers the entity headers
     */
    public HttpEntity(T body, MultiValueMap<String, String> headers) {}

    /**
     * Returns the headers of this entity.
     *
     * @return the HttpHeaders
     */
    public HttpHeaders getHeaders() {}

    /**
     * Returns the body of this entity.
     *
     * @return the body
     */
    public T getBody() {}

    /**
     * Indicates whether this entity has a body.
     *
     * @return true if this entity has a body, false otherwise
     */
    public boolean hasBody() {}
}

@RestController
@RequestMapping("/api/messages")
public class MessageController {

    @PostMapping("/send")
    public ResponseEntity<String> sendMessage(HttpEntity<Message> httpEntity) {
        HttpHeaders headers = httpEntity.getHeaders();
        Message message = httpEntity.getBody();

        String contentType = headers.getFirst("Content-Type");
        messageService.send(message, contentType);

        return ResponseEntity.ok("Message sent");
    }

    @GetMapping("/template")
    public HttpEntity<MessageTemplate> getTemplate() {
        MessageTemplate template = messageService.getTemplate();
        HttpHeaders headers = new HttpHeaders();
        headers.set("X-Custom-Header", "template-v1");
        return new HttpEntity<>(template, headers);
    }
}

/**
 * A data structure representing HTTP request or response headers, mapping String header names
 * to a list of String values, also offering accessors for common application-level data types.
 *
 * Implements MultiValueMap.
 */
public class HttpHeaders implements MultiValueMap<String, String>, Serializable {
    /**
     * The HTTP Accept header field name.
     */
    public static final String ACCEPT = "Accept";

    /**
     * The HTTP Accept-Charset header field name.
     */
    public static final String ACCEPT_CHARSET = "Accept-Charset";

    /**
     * The HTTP Accept-Encoding header field name.
     */
    public static final String ACCEPT_ENCODING = "Accept-Encoding";

    /**
     * The HTTP Accept-Language header field name.
     */
    public static final String ACCEPT_LANGUAGE = "Accept-Language";

    /**
     * The HTTP Authorization header field name.
     */
    public static final String AUTHORIZATION = "Authorization";

    /**
     * The HTTP Cache-Control header field name.
     */
    public static final String CACHE_CONTROL = "Cache-Control";

    /**
     * The HTTP Content-Type header field name.
     */
    public static final String CONTENT_TYPE = "Content-Type";

    /**
     * The HTTP Content-Length header field name.
     */
    public static final String CONTENT_LENGTH = "Content-Length";

    /**
     * The HTTP Location header field name.
     */
    public static final String LOCATION = "Location";

    /**
     * Create a new, empty HttpHeaders instance.
     */
    public HttpHeaders() {}

    /**
     * Set the list of acceptable media types, as specified by the Accept header.
     *
     * @param acceptableMediaTypes the acceptable media types
     */
    public void setAccept(List<MediaType> acceptableMediaTypes) {}

    /**
     * Return the list of acceptable media types, as specified by the Accept header.
     *
     * @return the acceptable media types, or an empty list if not set
     */
    public List<MediaType> getAccept() {}

    /**
     * Set the acceptable language tags, as specified by the Accept-Language header.
     *
     * @param languages the acceptable language tags
     */
    public void setAcceptLanguage(List<Locale.LanguageRange> languages) {}

    /**
     * Return the language tags from the Accept-Language header.
     *
     * @return the language tags, or an empty list if not set
     */
    public List<Locale.LanguageRange> getAcceptLanguage() {}

    /**
     * Set the value of the Authorization header to Basic authentication.
     *
     * @param username the username
     * @param password the password
     */
    public void setBasicAuth(String username, String password) {}

    /**
     * Set the value of the Authorization header to the given Bearer token.
     *
     * @param token the Base64 encoded token
     */
    public void setBearerAuth(String token) {}

    /**
     * Set the cache control directives, as specified by the Cache-Control header.
     *
     * @param cacheControl the cache control directives
     */
    public void setCacheControl(CacheControl cacheControl) {}

    /**
     * Return the cache control directives from the Cache-Control header.
     *
     * @return the cache control directives, or null if not set
     */
    public String getCacheControl() {}

    /**
     * Set the length of the body in bytes, as specified by the Content-Length header.
     *
     * @param contentLength the content length
     */
    public void setContentLength(long contentLength) {}

    /**
     * Return the length of the body in bytes, as specified by the Content-Length header.
     *
     * @return the content length, or -1 if not set
     */
    public long getContentLength() {}

    /**
     * Set the media type of the body, as specified by the Content-Type header.
     *
     * @param mediaType the media type
     */
    public void setContentType(MediaType mediaType) {}

    /**
     * Return the media type of the body, as specified by the Content-Type header.
     *
     * @return the media type, or null if not set
     */
    public MediaType getContentType() {}

    /**
     * Set the (new) value of the ETag header.
     *
     * @param etag the new ETag
     */
    public void setETag(String etag) {}

    /**
     * Return the entity tag of the body, as specified by the ETag header.
     *
     * @return the entity tag, or null if not set
     */
    public String getETag() {}

    /**
     * Set the time the resource was last changed, as specified by the Last-Modified header.
     *
     * @param lastModified the last modified date
     */
    public void setLastModified(Instant lastModified) {}

    /**
     * Return the time the resource was last changed, as specified by the Last-Modified header.
     *
     * @return the last modified date, or -1 if not set
     */
    public long getLastModified() {}

    /**
     * Set the (new) location of a resource, as specified by the Location header.
     *
     * @param location the location
     */
    public void setLocation(URI location) {}

    /**
     * Return the (new) location of a resource, as specified by the Location header.
     *
     * @return the location, or null if not set
     */
    public URI getLocation() {}

    /**
     * Set the (new) value of the Origin header.
     *
     * @param origin the origin
     */
    public void setOrigin(String origin) {}

    /**
     * Return the value of the Origin header.
     *
     * @return the origin, or null if not set
     */
    public String getOrigin() {}

    /**
     * Return a read-only empty HttpHeaders instance.
     *
     * @return the empty HttpHeaders instance
     */
    public static HttpHeaders readOnlyHttpHeaders(HttpHeaders headers) {}

    // Additional MultiValueMap methods inherited...
}

@RestController
@RequestMapping("/api/files")
public class FileController {

    @GetMapping("/{filename}")
    public ResponseEntity<byte[]> downloadFile(@PathVariable String filename) {
        byte[] data = fileService.loadFile(filename);

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
        headers.setContentLength(data.length);
        headers.set("Content-Disposition", "attachment; filename=\"" + filename + "\"");
        headers.setCacheControl(CacheControl.noCache());

        return new ResponseEntity<>(data, headers, HttpStatus.OK);
    }

    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(
            @RequestParam("file") MultipartFile file,
            @RequestHeader HttpHeaders headers) {
        String contentType = headers.getContentType().toString();
        List<Locale.LanguageRange> languages = headers.getAcceptLanguage();

        fileService.save(file, contentType);
        return ResponseEntity.ok("File uploaded");
    }
}

/**
 * Annotation that indicates a method return value should be bound to the
 * web response body. Supported for annotated handler methods.
 *
 * The return value will be written to the HTTP response body using
 * HttpMessageConverters.
 */
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ResponseBody {
}

@Controller
@RequestMapping("/api/data")
public class DataController {

    // This method returns JSON instead of a view name
    @GetMapping("/json")
    @ResponseBody
    public Map<String, Object> getJsonData() {
        Map<String, Object> data = new HashMap<>();
        data.put("message", "Hello World");
        data.put("timestamp", System.currentTimeMillis());
        return data;
    }

    // This method returns a view name (no @ResponseBody)
    @GetMapping("/page")
    public String getPage(Model model) {
        model.addAttribute("data", "some data");
        return "dataPage";
    }

    // Class-level @ResponseBody applies to all methods
    @RestController // Equivalent to @Controller + @ResponseBody
    @RequestMapping("/api/users")
    public class UserApiController {
        @GetMapping
        public List<User> getAllUsers() {
            return userService.findAll();
        }
    }
}

/**
 * Marks a method or exception class with the status code and reason that
 * should be returned. The status code is applied to the HTTP response when
 * the handler method is invoked and overrides status information set by
 * other means, like ResponseEntity or "redirect:".
 *
 * Warning: when using this annotation on an exception class, or when
 * setting the reason attribute, the HttpServletResponse.sendError method
 * will be used. With HttpServletResponse.sendError, the response is
 * considered complete and should not be written to any further. Furthermore,
 * the Servlet container will typically write an HTML error page therefore
 * making the use of a reason unsuitable for REST APIs. For such cases it
 * is preferable to use a ResponseEntity as a return type and avoid the
 * use of @ResponseStatus altogether.
 */
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ResponseStatus {
    /**
     * Alias for {@link #code}.
     */
    @AliasFor("code")
    HttpStatus value() default HttpStatus.INTERNAL_SERVER_ERROR;

    /**
     * The status code to use for the response.
     */
    @AliasFor("value")
    HttpStatus code() default HttpStatus.INTERNAL_SERVER_ERROR;

    /**
     * The reason to be used for the response. This will be used with
     * HttpServletResponse.sendError(int, String).
     */
    String reason() default "";
}

@RestController
@RequestMapping("/api/resources")
public class ResourceController {

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Resource createResource(@RequestBody Resource resource) {
        return resourceService.save(resource);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteResource(@PathVariable Long id) {
        resourceService.delete(id);
    }

    @PutMapping("/{id}/publish")
    @ResponseStatus(HttpStatus.ACCEPTED)
    public void publishResource(@PathVariable Long id) {
        resourceService.publishAsync(id);
    }
}

// Custom exception with status code
@ResponseStatus(value = HttpStatus.NOT_FOUND, reason = "Resource not found")
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

@ResponseStatus(HttpStatus.CONFLICT)
public class ResourceConflictException extends RuntimeException {
    public ResourceConflictException(String message) {
        super(message);
    }
}

/**
 * Enumeration of HTTP status codes.
 */
public enum HttpStatus {
    // 1xx Informational
    CONTINUE(100, "Continue"),
    SWITCHING_PROTOCOLS(101, "Switching Protocols"),
    PROCESSING(102, "Processing"),

    // 2xx Success
    OK(200, "OK"),
    CREATED(201, "Created"),
    ACCEPTED(202, "Accepted"),
    NON_AUTHORITATIVE_INFORMATION(203, "Non-Authoritative Information"),
    NO_CONTENT(204, "No Content"),
    RESET_CONTENT(205, "Reset Content"),
    PARTIAL_CONTENT(206, "Partial Content"),

    // 3xx Redirection
    MULTIPLE_CHOICES(300, "Multiple Choices"),
    MOVED_PERMANENTLY(301, "Moved Permanently"),
    FOUND(302, "Found"),
    SEE_OTHER(303, "See Other"),
    NOT_MODIFIED(304, "Not Modified"),
    TEMPORARY_REDIRECT(307, "Temporary Redirect"),
    PERMANENT_REDIRECT(308, "Permanent Redirect"),

    // 4xx Client Error
    BAD_REQUEST(400, "Bad Request"),
    UNAUTHORIZED(401, "Unauthorized"),
    PAYMENT_REQUIRED(402, "Payment Required"),
    FORBIDDEN(403, "Forbidden"),
    NOT_FOUND(404, "Not Found"),
    METHOD_NOT_ALLOWED(405, "Method Not Allowed"),
    NOT_ACCEPTABLE(406, "Not Acceptable"),
    PROXY_AUTHENTICATION_REQUIRED(407, "Proxy Authentication Required"),
    REQUEST_TIMEOUT(408, "Request Timeout"),
    CONFLICT(409, "Conflict"),
    GONE(410, "Gone"),
    LENGTH_REQUIRED(411, "Length Required"),
    PRECONDITION_FAILED(412, "Precondition Failed"),
    PAYLOAD_TOO_LARGE(413, "Payload Too Large"),
    URI_TOO_LONG(414, "URI Too Long"),
    UNSUPPORTED_MEDIA_TYPE(415, "Unsupported Media Type"),
    REQUESTED_RANGE_NOT_SATISFIABLE(416, "Requested range not satisfiable"),
    EXPECTATION_FAILED(417, "Expectation Failed"),
    I_AM_A_TEAPOT(418, "I'm a teapot"),
    UNPROCESSABLE_ENTITY(422, "Unprocessable Entity"),
    LOCKED(423, "Locked"),
    FAILED_DEPENDENCY(424, "Failed Dependency"),
    TOO_EARLY(425, "Too Early"),
    UPGRADE_REQUIRED(426, "Upgrade Required"),
    PRECONDITION_REQUIRED(428, "Precondition Required"),
    TOO_MANY_REQUESTS(429, "Too Many Requests"),
    REQUEST_HEADER_FIELDS_TOO_LARGE(431, "Request Header Fields Too Large"),
    UNAVAILABLE_FOR_LEGAL_REASONS(451, "Unavailable For Legal Reasons"),

    // 5xx Server Error
    INTERNAL_SERVER_ERROR(500, "Internal Server Error"),
    NOT_IMPLEMENTED(501, "Not Implemented"),
    BAD_GATEWAY(502, "Bad Gateway"),
    SERVICE_UNAVAILABLE(503, "Service Unavailable"),
    GATEWAY_TIMEOUT(504, "Gateway Timeout"),
    HTTP_VERSION_NOT_SUPPORTED(505, "HTTP Version not supported"),
    VARIANT_ALSO_NEGOTIATES(506, "Variant Also Negotiates"),
    INSUFFICIENT_STORAGE(507, "Insufficient Storage"),
    LOOP_DETECTED(508, "Loop Detected"),
    BANDWIDTH_LIMIT_EXCEEDED(509, "Bandwidth Limit Exceeded"),
    NOT_EXTENDED(510, "Not Extended"),
    NETWORK_AUTHENTICATION_REQUIRED(511, "Network Authentication Required");

    /**
     * Return the integer value of this status code.
     */
    public int value() {}

    /**
     * Return the reason phrase of this status code.
     */
    public String getReasonPhrase() {}

    /**
     * Whether this status code is in the Informational class (1xx).
     */
    public boolean is1xxInformational() {}

    /**
     * Whether this status code is in the Successful class (2xx).
     */
    public boolean is2xxSuccessful() {}

    /**
     * Whether this status code is in the Redirection class (3xx).
     */
    public boolean is3xxRedirection() {}

    /**
     * Whether this status code is in the Client Error class (4xx).
     */
    public boolean is4xxClientError() {}

    /**
     * Whether this status code is in the Server Error class (5xx).
     */
    public boolean is5xxServerError() {}

    /**
     * Whether this status code is in the Client or Server Error class (4xx or 5xx).
     */
    public boolean isError() {}

    /**
     * Return the HttpStatus enum constant with the specified numeric value.
     *
     * @param statusCode the numeric value of the enum to be returned
     * @return the enum constant with the specified numeric value
     * @throws IllegalArgumentException if this enum has no constant for the specified value
     */
    public static HttpStatus valueOf(int statusCode) {}
}

/**
 * A builder for creating "Cache-Control" HTTP response headers.
 */
public class CacheControl {
    /**
     * Create a "Cache-Control" header with the given directive.
     *
     * @return this CacheControl instance
     */
    public static CacheControl empty() {}

    /**
     * Add a "max-age" directive.
     *
     * @param maxAge the maximum time a response is considered fresh
     * @param unit the time unit of the maxAge argument
     * @return this CacheControl instance
     */
    public static CacheControl maxAge(long maxAge, TimeUnit unit) {}

    /**
     * Add a "no-cache" directive.
     *
     * @return this CacheControl instance
     */
    public static CacheControl noCache() {}

    /**
     * Add a "no-store" directive.
     *
     * @return this CacheControl instance
     */
    public static CacheControl noStore() {}

    /**
     * Add an "s-maxage" directive.
     *
     * @param sMaxAge the maximum time the response should be cached by shared caches
     * @param unit the time unit of the sMaxAge argument
     * @return this CacheControl instance
     */
    public CacheControl sMaxAge(long sMaxAge, TimeUnit unit) {}

    /**
     * Add a "must-revalidate" directive.
     *
     * @return this CacheControl instance
     */
    public CacheControl mustRevalidate() {}

    /**
     * Add a "proxy-revalidate" directive.
     *
     * @return this CacheControl instance
     */
    public CacheControl proxyRevalidate() {}

    /**
     * Add a "public" directive.
     *
     * @return this CacheControl instance
     */
    public CacheControl cachePublic() {}

    /**
     * Add a "private" directive.
     *
     * @return this CacheControl instance
     */
    public CacheControl cachePrivate() {}

    /**
     * Add a "stale-while-revalidate" directive.
     *
     * @param staleWhileRevalidate the time during which the cache can serve stale responses
     * @param unit the time unit
     * @return this CacheControl instance
     */
    public CacheControl staleWhileRevalidate(long staleWhileRevalidate, TimeUnit unit) {}

    /**
     * Add a "stale-if-error" directive.
     *
     * @param staleIfError the time during which the cache can serve stale responses if an error occurs
     * @param unit the time unit
     * @return this CacheControl instance
     */
    public CacheControl staleIfError(long staleIfError, TimeUnit unit) {}

    /**
     * Return the "Cache-Control" header value.
     *
     * @return the header value, or null if no directive was added
     */
    public String getHeaderValue() {}
}