Package org.apache.juneau.http.classic.response

Class BasicHttpException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.apache.juneau.commons.BasicRuntimeException

org.apache.juneau.marshall.BasicRuntimeException

org.apache.juneau.http.classic.response.BasicHttpException

All Implemented Interfaces:

Serializable, HttpMessage, HttpResponse

Direct Known Subclasses:

BadRequest, BasicHttpException.Unmodifiable, Conflict, ExpectationFailed, FailedDependency, Forbidden, 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

@Marshalled(as=STRING)
public class BasicHttpException
extends BasicRuntimeException
implements HttpResponse

Basic implementation of the HttpResponse interface for error responses.

Although this class implements the various setters defined on the HttpResponse interface, it's in general going to be more efficient to set the status/headers/content of this bean through the builder.

Immutability is expressed with the "funnel + nested Unmodifiable snapshot" paradigm: every mutator (fluent setter and void interface 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 of type X.Unmodifiable; 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.

Notes:

• Beans are not thread safe unless they're marked as unmodifiable.

See Also:

• juneau-rest-common

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	BasicHttpException.Unmodifiable	Unmodifiable point-in-time snapshot of the enclosing BasicHttpException.

Constructor Summary

Constructors

Modifier	Constructor	Description
	BasicHttpException()	Constructor.
	BasicHttpException(int statusCode)	Constructor.
	BasicHttpException(int statusCode, String msg, Object... args)	Constructor.
	BasicHttpException(int statusCode, Throwable causedBy)	Constructor.
	BasicHttpException(int statusCode, Throwable cause, String msg, Object... args)	Constructor.
	BasicHttpException(HttpResponse response)	Constructor.
protected	BasicHttpException(BasicHttpException copyFrom)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
void	addHeader(String name, String value)
void	addHeader(Header value)
protected void	assertStatusCode(HttpResponse response)	Asserts that the specified HTTP response has the same status code as the one on the status line of this bean.
boolean	containsHeader(String name)
boolean	equals(Object o)
protected void	freeze()	Deep-freeze hook invoked from the nested Unmodifiable constructor after the snapshot copy completes.
Header[]	getAllHeaders()
HttpEntity	getEntity()
Header	getFirstHeader(String name)
String	getFullStackMessage(boolean scrubForXssVulnerabilities)	Returns all error messages from all errors in this stack.
HeaderList	getHeaders()	Returns access to the underlying builder for the headers.
Header[]	getHeaders(String name)
Header	getLastHeader(String name)
Locale	getLocale()
String	getMessage()
HttpParams	getParams()
ProtocolVersion	getProtocolVersion()
Throwable	getRootCause()	Returns the root cause of this exception.
StatusLine	getStatusLine()
int	hashCode()
HeaderIterator	headerIterator()
HeaderIterator	headerIterator(String name)
boolean	isUnmodifiable()	Returns true if this bean is unmodifiable.
protected BasicHttpException	modify(Runnable mutation)	Single mutation funnel — the only choke-point through which all state changes on this bean flow.
void	removeHeader(Header value)
void	removeHeaders(String name)
BasicHttpException	setContent(String value)	Sets the body on this response.
BasicHttpException	setContent(HttpEntity value)	Sets the body on this response.
void	setEntity(HttpEntity entity)
void	setHeader(String name, String value)
void	setHeader(Header value)
BasicHttpException	setHeader2(String name, Object value)	Sets a header on this response.
BasicHttpException	setHeaders(List<Header> values)	Sets the specified headers on this response.
void	setHeaders(Header[] values)
BasicHttpException	setHeaders(HeaderList value)	Sets the specified headers on this response.
BasicHttpException	setHeaders2(Header... values)	Sets multiple headers on this response.
void	setLocale(Locale loc)
BasicHttpException	setLocale2(Locale value)	Sets the locale used to retrieve reason phrases.
BasicHttpException	setMessage(String message, Object... args)	Sets the detail message on this exception.
void	setParams(HttpParams params)
BasicHttpException	setProtocolVersion(ProtocolVersion value)	Sets the protocol version on the status line.
void	setReasonPhrase(String reason)
BasicHttpException	setReasonPhrase2(String value)	Sets the reason phrase on the status line.
BasicHttpException	setReasonPhraseCatalog(ReasonPhraseCatalog value)	Sets the reason phrase catalog used to retrieve reason phrases.
void	setStatusCode(int code)
BasicHttpException	setStatusCode2(int code)	Same as setStatusCode(int) but returns this object.
void	setStatusLine(ProtocolVersion ver, int code)
void	setStatusLine(ProtocolVersion ver, int code, String reason)
void	setStatusLine(StatusLine value)
BasicHttpException	setStatusLine(BasicStatusLine value)	Sets the protocol version on the status line.
String	toString()
BasicHttpException	unmodifiable()	Returns an unmodifiable snapshot of this bean.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

BasicHttpException

public BasicHttpException()

Constructor.

BasicHttpException

public BasicHttpException(HttpResponse response)

Constructor.

This is the constructor used when parsing an HTTP response.

Parameters:

response - The HTTP response being parsed. Must not be null.

BasicHttpException

public BasicHttpException(int statusCode)

Constructor.

Parameters:

statusCode - The HTTP status code.

BasicHttpException

public BasicHttpException(int statusCode,
 String msg,
 Object... args)

Constructor.

Parameters:

statusCode - The HTTP status code.

msg - The message. Can be null, in which case the reason phrase is used as the message.

args - Optional printf-style ("%s") arguments in the message.

BasicHttpException

public BasicHttpException(int statusCode,
 Throwable causedBy)

Constructor.

Parameters:

statusCode - The HTTP status code.

causedBy - The cause. Can be null, in which case no cause is chained and the reason phrase is used as the message.

BasicHttpException

public BasicHttpException(int statusCode,
 Throwable cause,
 String msg,
 Object... args)

Constructor.

Parameters:

statusCode - The HTTP status code.

cause - The caused-by exception. Can be null (no cause is chained).

msg - The message. Can be null, in which case the cause's message is used, or the reason phrase if the cause is also null or has no message.

args - The 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 bean to copy. Must not be null.

Method Details

addHeader

public void addHeader(Header value)

Specified by:

addHeader in interface HttpMessage

addHeader

public void addHeader(String name,
 String value)

Specified by:

addHeader in interface HttpMessage

containsHeader

public boolean containsHeader(String name)

Specified by:

containsHeader in interface HttpMessage

getAllHeaders

public Header[] getAllHeaders()

Specified by:

getAllHeaders in interface HttpMessage

getEntity

public HttpEntity getEntity()

Specified by:

getEntity in interface HttpResponse

getFirstHeader

public Header getFirstHeader(String name)

Specified by:

getFirstHeader in interface HttpMessage

getFullStackMessage

public String getFullStackMessage(boolean scrubForXssVulnerabilities)

Returns all error messages from all errors in this stack.

Typically useful if you want to render all the error messages in the stack, but don't want to render all the stack traces too.

Parameters:

scrubForXssVulnerabilities - If true, replaces '<', '>', and '&' characters with spaces.

Returns:

All error messages from all errors in this stack.

getHeaders

public HeaderList getHeaders()

Returns access to the underlying builder for the headers.

Returns:

The underlying builder for the headers.

getHeaders

public Header[] getHeaders(String name)

Specified by:

getHeaders in interface HttpMessage

getLastHeader

public Header getLastHeader(String name)

Specified by:

getLastHeader in interface HttpMessage

getLocale

public Locale getLocale()

Specified by:

getLocale in interface HttpResponse

getMessage

public String getMessage()

Overrides:

getMessage in class BasicRuntimeException

getParams

public HttpParams getParams()

Specified by:

getParams in interface HttpMessage

getProtocolVersion

public ProtocolVersion getProtocolVersion()

Specified by:

getProtocolVersion in interface HttpMessage

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:

• BasicHttpException
• InvocationTargetException

Returns:

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

getStatusLine

public StatusLine getStatusLine()

Specified by:

getStatusLine in interface HttpResponse

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

headerIterator

public HeaderIterator headerIterator()

Specified by:

headerIterator in interface HttpMessage

headerIterator

public HeaderIterator headerIterator(String name)

Specified by:

headerIterator in interface HttpMessage

isUnmodifiable

public boolean isUnmodifiable()

Returns true if this bean is unmodifiable.

Returns:

true if this bean is an UnmodifiableBean snapshot.

removeHeader

public void removeHeader(Header value)

Specified by:

removeHeader in interface HttpMessage

removeHeaders

public void removeHeaders(String name)

Specified by:

removeHeaders in interface HttpMessage

setContent

public BasicHttpException setContent(HttpEntity value)

Sets the body on this response.

Parameters:

value - The body on this response. Can be null to unset the property.

Returns:

This object.

setContent

public BasicHttpException setContent(String value)

Sets the body on this response.

Parameters:

value - The body on this response. Can be null (treated as an empty string).

Returns:

This object.

setEntity

public void setEntity(HttpEntity entity)

Specified by:

setEntity in interface HttpResponse

setHeader

public void setHeader(Header value)

Specified by:

setHeader in interface HttpMessage

setHeader

public void setHeader(String name,
 String value)

Specified by:

setHeader in interface HttpMessage

setHeader2

public BasicHttpException setHeader2(String name,
 Object value)

Sets a header on this response.

Parameters:

name - The header name.

value - The header value.

Returns:

This object.

setHeaders

public void setHeaders(Header[] values)

Specified by:

setHeaders in interface HttpMessage

setHeaders

public BasicHttpException setHeaders(HeaderList value)

Sets the specified headers on this response.

Parameters:

value - The new value. Must not be null.

Returns:

This object.

setHeaders

public BasicHttpException setHeaders(List<Header> values)

Sets the specified headers on this response.

Parameters:

values - The headers to set. null values are ignored.

Returns:

This object.

setHeaders2

public BasicHttpException setHeaders2(Header... values)

Sets multiple headers on this response.

Parameters:

values - The headers to add.

Returns:

This object.

setLocale

public void setLocale(Locale loc)

Specified by:

setLocale in interface HttpResponse

setLocale2

public BasicHttpException setLocale2(Locale value)

Sets the locale used to retrieve reason phrases.

If not specified, uses Locale.getDefault().

Parameters:

value - The new value. Can be null. The effect is implementation-dependent, depending on the configured ReasonPhraseCatalog (e.g. ignored by EnglishReasonPhraseCatalog).

Returns:

This object.

setMessage

public BasicHttpException setMessage(String message,
 Object... args)

Description copied from class: BasicRuntimeException

Sets the detail message on this exception.

Overrides:

setMessage in class BasicRuntimeException

Parameters:

message - The message.

args - The message args.

Returns:

This object.

setParams

public void setParams(HttpParams params)

Specified by:

setParams in interface HttpMessage

setProtocolVersion

public BasicHttpException setProtocolVersion(ProtocolVersion value)

Sets the protocol version on the status line.

If not specified, "HTTP/1.1" will be used.

Parameters:

value - The new value. Can be null, in which case the default protocol version is cleared and BasicStatusLine.getProtocolVersion() returns null.

Returns:

This object.

setReasonPhrase

public void setReasonPhrase(String reason)
                     throws IllegalStateException

Specified by:

setReasonPhrase in interface HttpResponse

Throws:

IllegalStateException

setReasonPhrase2

public BasicHttpException setReasonPhrase2(String value)

Sets the reason phrase on the status line.

If not specified, the reason phrase will be retrieved from the reason phrase catalog using the locale on this builder.

Parameters:

value - The new value. Can be null to fall back to the reason phrase catalog.

Returns:

This object.

setReasonPhraseCatalog

public BasicHttpException setReasonPhraseCatalog(ReasonPhraseCatalog value)

Sets the reason phrase catalog used to retrieve reason phrases.

If not specified, uses EnglishReasonPhraseCatalog.

Parameters:

value - The new value. Can be null to fall back to EnglishReasonPhraseCatalog.INSTANCE.

Returns:

This object.

setStatusCode

public void setStatusCode(int code)
                   throws IllegalStateException

Specified by:

setStatusCode in interface HttpResponse

Throws:

IllegalStateException

setStatusCode2

public BasicHttpException setStatusCode2(int code)
                                  throws IllegalStateException

Same as setStatusCode(int) but returns this object.

Parameters:

code - The new status code.

Returns:

This object.

Throws:

IllegalStateException - If status code could not be set.

setStatusLine

public BasicHttpException setStatusLine(BasicStatusLine value)

Sets the protocol version on the status line.

If not specified, "HTTP/1.1" will be used.

Parameters:

value - The new value. Must not be null.

Returns:

This object.

setStatusLine

public void setStatusLine(ProtocolVersion ver,
 int code)

Specified by:

setStatusLine in interface HttpResponse

setStatusLine

public void setStatusLine(ProtocolVersion ver,
 int code,
 String reason)

Specified by:

setStatusLine in interface HttpResponse

setStatusLine

public void setStatusLine(StatusLine value)

Specified by:

setStatusLine in interface HttpResponse

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.

toString

public String toString()

Overrides:

toString in class Throwable

assertStatusCode

protected void assertStatusCode(HttpResponse response)
                         throws IllegalArgumentException

Asserts that the specified HTTP response has the same status code as the one on the status line of this bean.

Parameters:

response - The HTTP response to check. Must not be null.

Throws:

IllegalArgumentException - If status code is not what was expected.

modify

protected BasicHttpException modify(Runnable mutation)

Single mutation funnel — the only choke-point through which all state changes on this bean flow.

Every mutator (fluent setter and void interface mutator) 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).