Package org.apache.juneau.http.response

Class BasicHttpException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.apache.juneau.http.response.BasicHttpException
All Implemented Interfaces:
Serializable, HttpResponseMessage
Direct Known Subclasses:
BadGateway, BadRequest, BasicHttpException.Unmodifiable, Conflict, ExpectationFailed, FailedDependency, Forbidden, GatewayTimeout, Gone, HttpVersionNotSupported, InsufficientStorage, InternalServerError, LengthRequired, Locked, LoopDetected, MethodNotAllowed, MisdirectedRequest, NetworkAuthenticationRequired, NotAcceptable, NotExtended, NotFound, NotImplemented, PayloadTooLarge, PreconditionFailed, PreconditionRequired, RangeNotSatisfiable, RequestHeaderFieldsTooLarge, ServiceUnavailable, TooManyRequests, Unauthorized, UnavailableForLegalReasons, UnprocessableEntity, UnsupportedMediaType, UpgradeRequired, UriTooLong, VariantAlsoNegotiates
public class BasicHttpException extends RuntimeException implements HttpResponseMessage
Base class for HTTP error response exceptions (4xx and 5xx) in the org.apache.juneau.http stack.

Extends RuntimeException while also implementing HttpResponseMessage, so that HTTP error responses can be both thrown as exceptions and used as response objects. Provides classic-style fluent setters that mutate state and return this.

Immutability is expressed with the "funnel + nested Unmodifiable snapshot" paradigm: every mutator routes through the single protected modify(Runnable) choke-point, and each concrete leaf gets a nested X.Unmodifiable whose only behavioral override is a throwing modify(...). A leaf's unmodifiable() factory returns a point-in-time snapshot; any attempt to set a property on it throws an UnsupportedOperationException.

This is a Throwable-rooted hierarchy, so (unlike BasicHttpResponse) it cannot be a self-typed (CRTP) root — JLS §8.1.2 forbids a generic Throwable. The funnel therefore returns the base type and each leaf keeps its covariant setter overrides.

See Also:
Since:
9.2.1
See Also:

  • Constructor Details

    • BasicHttpException

      public BasicHttpException(int statusCode, String reasonPhrase)
      Constructor with no message body.
      Parameters:
      statusCode - The HTTP status code.
      reasonPhrase - The reason phrase (e.g. "Internal Server Error"). May be null.

    • BasicHttpException

      public BasicHttpException(int statusCode, String reasonPhrase, Throwable cause)
      Constructor with a status code and a cause.
      Parameters:
      statusCode - The HTTP status code.
      reasonPhrase - The reason phrase. May be null.
      cause - The cause. May be null.

    • BasicHttpException

      public BasicHttpException(int statusCode, String reasonPhrase, String msg, Object... args)
      Constructor with a String.format-style message body.
      Parameters:
      statusCode - The HTTP status code.
      reasonPhrase - The reason phrase. May be null.
      msg - The exception message and response body. May be null. Treated as a String.format-style format string (%s placeholders) when args is non-empty.
      args - Optional message arguments.

    • BasicHttpException

      public BasicHttpException(int statusCode, String reasonPhrase, Throwable cause, String msg, Object... args)
      Constructor with a cause and a String.format-style message body.
      Parameters:
      statusCode - The HTTP status code.
      reasonPhrase - The reason phrase. May be null.
      cause - The cause. May be null.
      msg - The exception message. May be null. Treated as a String.format-style format string (%s placeholders) when args is non-empty.
      args - Optional message arguments.

    • BasicHttpException

      protected BasicHttpException(BasicHttpException copyFrom)
      Copy constructor.

      The mutable sub-beans are deep-copied by direct field assignment, never through a funneled setter. This is the snapshot path used by unmodifiable(): the constructor runs inside an Unmodifiable instance whose modify(Runnable) already throws, so a setter-based copy would blow up during construction.

      Parameters:
      copyFrom - The instance to copy. Must not be null.

  • Method Details

    • getStatusLine

      public HttpStatusLine getStatusLine()
      Description copied from interface: HttpResponseMessage
      Returns the status line of this response.
      Specified by:
      getStatusLine in interface HttpResponseMessage
      Returns:
      The status line. Never null.

    • getHeaders

      public List<HttpHeader> getHeaders()
      Description copied from interface: HttpResponseMessage
      Returns all response headers, in the order they were received.
      Specified by:
      getHeaders in interface HttpResponseMessage
      Returns:
      An unmodifiable list of response headers. Never null.

    • getBody

      public HttpBody getBody()
      Description copied from interface: HttpResponseMessage
      Returns the response body, or null if the response has no body.
      Specified by:
      getBody in interface HttpResponseMessage
      Returns:
      The response body, possibly null.

    • getMessage

      public String getMessage()
      Overrides:
      getMessage in class Throwable

    • getStatusCode

      public int getStatusCode()
      Returns the HTTP status code.
      Returns:
      The status code.

    • getLocale

      public Locale getLocale()
      Returns the locale associated with this response, if any.
      Returns:
      The locale, possibly null.

    • setStatusLine

      public BasicHttpException setStatusLine(HttpStatusLine value)
      Sets the status line.
      Parameters:
      value - New status line. Must not be null.
      Returns:
      This object.

    • setStatusCode

      public BasicHttpException setStatusCode(int value)
      Sets the status code, preserving the existing protocol version and reason phrase.
      Parameters:
      value - New status code.
      Returns:
      This object.

    • setReasonPhrase

      public BasicHttpException setReasonPhrase(String value)
      Sets the reason phrase, preserving the existing protocol version and status code.
      Parameters:
      value - New reason phrase. May be null.
      Returns:
      This object.

    • setProtocolVersion

      public BasicHttpException setProtocolVersion(HttpProtocolVersion value)
      Sets the protocol version, preserving the existing status code and reason phrase.
      Parameters:
      value - New protocol version. Must not be null.
      Returns:
      This object.

    • setHeaders

      public BasicHttpException setHeaders(List<HttpHeader> values)
      Replaces all headers with the given list.
      Parameters:
      values - New headers. null is treated as an empty list.
      Returns:
      This object.

    • setHeaders

      public BasicHttpException setHeaders(HttpHeader... values)
      Replaces all headers with the given array.
      Parameters:
      values - New headers. null is treated as an empty array.
      Returns:
      This object.

    • setHeader

      public BasicHttpException setHeader(HttpHeader value)
      Sets a single header, replacing any existing header with the same name.
      Parameters:
      value - The header to set. null is ignored.
      Returns:
      This object.

    • setHeader

      public BasicHttpException setHeader(String name, String value)
      Sets a single header, replacing any existing header with the same name.
      Parameters:
      name - Header name. Must not be null.
      value - Header value. May be null.
      Returns:
      This object.

    • addHeader

      public BasicHttpException addHeader(HttpHeader value)
      Appends a header to the end of the header list.
      Parameters:
      value - The header to add. null is ignored.
      Returns:
      This object.

    • addHeader

      public BasicHttpException addHeader(String name, String value)
      Appends a header to the end of the header list.
      Parameters:
      name - Header name. Must not be null.
      value - Header value. May be null.
      Returns:
      This object.

    • setBody

      public BasicHttpException setBody(HttpBody value)
      Sets the response body.
      Parameters:
      value - New body. May be null.
      Returns:
      This object.

    • setContent

      public BasicHttpException setContent(String value)
      Sets the response body to a plain-text string body (UTF-8, text/plain).
      Parameters:
      value - Body text. May be null.
      Returns:
      This object.

    • setContent

      public BasicHttpException setContent(HttpBody value)
      Sets the response body.
      Parameters:
      value - New body. May be null.
      Returns:
      This object.

    • setLocale

      public BasicHttpException setLocale(Locale value)
      Sets the locale associated with this response.
      Parameters:
      value - New locale. May be null.
      Returns:
      This object.

    • isUnmodifiable

      public boolean isUnmodifiable()
      Returns whether this instance is an unmodifiable snapshot.
      Returns:
      true if this bean is an UnmodifiableBean snapshot.

    • unmodifiable

      public BasicHttpException unmodifiable()
      Returns an unmodifiable snapshot of this bean.

      The returned instance is a point-in-time copy of the leaf's nested Unmodifiable type; any attempt to set a property on it throws an UnsupportedOperationException. This method is idempotent: if this bean is already unmodifiable it returns itself rather than taking another snapshot. The receiver is left unchanged (and still modifiable unless it was already unmodifiable).

      Returns:
      An unmodifiable snapshot of this bean, or this bean if it is already unmodifiable.

    • getRootCause

      public Throwable getRootCause()
      Returns the root cause of this exception.

      The root cause is the first exception in the init-cause parent chain that's not one of the following:

      Returns:
      The root cause of this exception, or null if no root cause was found.

    • getFullStackMessage

      public String getFullStackMessage(boolean scrubForXssVulnerabilities)
      Returns all error messages from all errors in this exception's cause chain joined into a single string.
      Parameters:
      scrubForXssVulnerabilities - If true, replaces <, >, and & characters with spaces.
      Returns:
      A multi-line string of messages. Never null.

    • modify

      protected BasicHttpException modify(Runnable mutation)
      Single mutation funnel — the only choke-point through which all state changes on this bean flow.

      Every fluent setter routes through this method. The nested Unmodifiable snapshot overrides only this method to throw, which freezes the entire mutation surface with a single override. Because this is a Throwable-rooted hierarchy (no CRTP self-type), the funnel returns the base type.

      Parameters:
      mutation - The state change to apply.
      Returns:
      This object.

    • freeze

      protected void freeze()
      Deep-freeze hook invoked from the nested Unmodifiable constructor after the snapshot copy completes.

      The mutable sub-beans are frozen here by direct field assignment (never via a setter, which would route through the throwing modify(Runnable) and blow up during construction). A leaf that adds its own mutable sub-bean overrides this method (calling super.freeze() first).

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Throwable