org.forgerock.json.resource

Class ResourceException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.io.IOException

org.forgerock.json.resource.ResourceException

All Implemented Interfaces:

Serializable, Response

Direct Known Subclasses:

BadRequestException, ConflictException, ForbiddenException, InternalServerErrorException, NotFoundException, NotSupportedException, PermanentException, PreconditionFailedException, PreconditionRequiredException, RetryableException, TokenCreationException, TokenValidationException, UncategorizedException

public class ResourceException
extends IOException
implements Response

An exception that is thrown during the processing of a JSON resource request. Contains an integer exception code and short reason phrase. A longer description of the exception is provided in the exception's detail message.

Positive 3-digit integer exception codes are explicitly reserved for exceptions that correspond with HTTP status codes. For the sake of interoperability with HTTP, if an exception corresponds with an HTTP error status, use the matching HTTP status code.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	BAD_REQUEST Indicates that the request could not be understood by the resource due to malformed syntax.
static int	CONFLICT Indicates the request could not be completed due to a conflict with the current state of the resource.
static String	FIELD_CAUSE The name of the JSON field used for the cause message.
static String	FIELD_CODE The name of the JSON field used for the code.
static String	FIELD_DETAIL The name of the JSON field used for the detail.
static String	FIELD_MESSAGE The name of the JSON field used for the message.
static String	FIELD_REASON The name of the JSON field used for the reason.
static int	FORBIDDEN Indicates that the resource understood the request, but is refusing to fulfill it.
static int	INTERNAL_ERROR Indicates that a resource encountered an unexpected condition which prevented it from fulfilling the request.
static int	NOT_FOUND Indicates that the resource could not be found.
static int	NOT_SUPPORTED Indicates that the resource does not implement/support the feature to fulfill the request HTTP status: 501 Not Implemented.
static int	UNAVAILABLE Indicates that the resource is temporarily unable to handle the request.
static int	VERSION_MISMATCH Indicates that the resource's current version does not match the version provided.
static int	VERSION_REQUIRED Indicates that the resource requires a version, but no version was supplied in the request.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ResourceException(int code) Constructs a new exception with the specified exception code, and null as its detail message.
protected	ResourceException(int code, String message) Constructs a new exception with the specified exception code and detail message.
protected	ResourceException(int code, String message, Throwable cause) Constructs a new exception with the specified exception code, reason phrase, detail message and cause.
protected	ResourceException(int code, Throwable cause) Constructs a new exception with the specified exception code and detail message.

Method Summary

Modifier and Type	Method and Description
<V> Promise<V,ResourceException>	asPromise() Return this ResourceException as a Promise.
int	getCode() Returns the numeric code of the exception.
JsonValue	getDetail() Returns the additional detail which can be evaluated by applications.
static ResourceException	getException(int code) Deprecated. in favor of ResourceException.newResourceException(int)
static ResourceException	getException(int code, String message) Deprecated. in favor of ResourceException.newResourceException(int, String)
static ResourceException	getException(int code, String message, Throwable cause) Deprecated. in favor of ResourceException.newResourceException(int, String, Throwable)
String	getReason() Returns the short reason phrase of the exception.
Version	getResourceApiVersion() Gets the API version of the resource that the request was routed to.
<E extends ResourceException> E	includeCauseInJsonValue() Returns this ResourceException with the includeCause flag set to true so that toJsonValue() method will include the cause if there is one supplied.
boolean	isServerError() Returns true if the HTTP error code is in the 500 range.
static ResourceException	newResourceException(int code) Returns an exception with the specified HTTP error code, but no detail message or cause, and a default reason phrase.
static ResourceException	newResourceException(int code, String message) Returns an exception with the specified HTTP error code and detail message, but no cause, and a default reason phrase.
static ResourceException	newResourceException(int code, String message, Throwable cause) Returns an exception with the specified HTTP error code, detail message, and cause, and a default reason phrase.
<E extends ResourceException> E	setDetail(JsonValue detail) Sets the additional detail which can be evaluated by applications.
<E extends ResourceException> E	setReason(String reason) Sets/overrides the short reason phrase of the exception.
void	setResourceApiVersion(Version version) Sets the API version of the resource that the request was routed to.
JsonValue	toJsonValue() Returns the exception in a JSON object structure, suitable for inclusion in the entity of an HTTP error response.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FIELD_DETAIL

public static final String FIELD_DETAIL

The name of the JSON field used for the detail.

See Also:

ResourceException.getDetail(), ResourceException.toJsonValue(), Constant Field Values

FIELD_MESSAGE

public static final String FIELD_MESSAGE

The name of the JSON field used for the message.

See Also:

Throwable.getMessage(), ResourceException.toJsonValue(), Constant Field Values

FIELD_REASON

public static final String FIELD_REASON

The name of the JSON field used for the reason.

See Also:

ResourceException.getReason(), ResourceException.toJsonValue(), Constant Field Values

FIELD_CODE

public static final String FIELD_CODE

The name of the JSON field used for the code.

See Also:

ResourceException.getCode(), ResourceException.toJsonValue(), Constant Field Values

FIELD_CAUSE

public static final String FIELD_CAUSE

The name of the JSON field used for the cause message.

See Also:

Throwable.getCause(), ResourceException.toJsonValue(), Constant Field Values

BAD_REQUEST

public static final int BAD_REQUEST

Indicates that the request could not be understood by the resource due to malformed syntax. Equivalent to HTTP status: 400 Bad Request.

See Also:

Constant Field Values

CONFLICT

public static final int CONFLICT

Indicates the request could not be completed due to a conflict with the current state of the resource. Equivalent to HTTP status: 409 Conflict.

See Also:

Constant Field Values

FORBIDDEN

public static final int FORBIDDEN

Indicates that the resource understood the request, but is refusing to fulfill it. Equivalent to HTTP status: 403 Forbidden.

See Also:

Constant Field Values

INTERNAL_ERROR

public static final int INTERNAL_ERROR

Indicates that a resource encountered an unexpected condition which prevented it from fulfilling the request. Equivalent to HTTP status: 500 Internal Server Error.

See Also:

Constant Field Values

NOT_FOUND

public static final int NOT_FOUND

Indicates that the resource could not be found. Equivalent to HTTP status: 404 Not Found.

See Also:

Constant Field Values

NOT_SUPPORTED

public static final int NOT_SUPPORTED

Indicates that the resource does not implement/support the feature to fulfill the request HTTP status: 501 Not Implemented.

See Also:

Constant Field Values

UNAVAILABLE

public static final int UNAVAILABLE

Indicates that the resource is temporarily unable to handle the request. Equivalent to HTTP status: 503 Service Unavailable.

See Also:

Constant Field Values

VERSION_MISMATCH

public static final int VERSION_MISMATCH

Indicates that the resource's current version does not match the version provided. Equivalent to HTTP status: 412 Precondition Failed.

See Also:

Constant Field Values

VERSION_REQUIRED

public static final int VERSION_REQUIRED

Indicates that the resource requires a version, but no version was supplied in the request. Equivalent to draft-nottingham-http-new-status-03 HTTP status: 428 Precondition Required.

See Also:

Constant Field Values

Constructor Detail

ResourceException

protected ResourceException(int code)

Constructs a new exception with the specified exception code, and null as its detail message. If the error code corresponds with a known HTTP error status code, then the reason phrase is set to a corresponding reason phrase, otherwise is set to a generic value "Resource Exception".

Parameters:

code - The numeric code of the exception.

ResourceException

protected ResourceException(int code,
                            String message)

Constructs a new exception with the specified exception code and detail message.

Parameters:

code - The numeric code of the exception.

message - The detail message.

ResourceException

protected ResourceException(int code,
                            Throwable cause)

Constructs a new exception with the specified exception code and detail message.

Parameters:

code - The numeric code of the exception.

cause - The exception which caused this exception to be thrown.

ResourceException

protected ResourceException(int code,
                            String message,
                            Throwable cause)

Constructs a new exception with the specified exception code, reason phrase, detail message and cause.

Parameters:

code - The numeric code of the exception.

message - The detail message.

cause - The exception which caused this exception to be thrown.

Method Detail

newResourceException

public static ResourceException newResourceException(int code)

Returns an exception with the specified HTTP error code, but no detail message or cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

If the type of the expected exception is known in advance, prefer to directly instantiate the exception type as usual:

     
     throw new InternalServerErrorException("Server failed");
     
 

Parameters:

code - The HTTP error code.

Returns:

A resource exception having the provided HTTP error code.

newResourceException

public static ResourceException newResourceException(int code,
                                                     String message)

Returns an exception with the specified HTTP error code and detail message, but no cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

If the type of the expected exception is known in advance, prefer to directly instantiate the exception type as usual:

     
     throw new InternalServerErrorException("Server failed");
     
 

Parameters:

code - The HTTP error code.

message - The detail message.

Returns:

A resource exception having the provided HTTP error code.

newResourceException

public static ResourceException newResourceException(int code,
                                                     String message,
                                                     Throwable cause)

Returns an exception with the specified HTTP error code, detail message, and cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

If the type of the expected exception is known in advance, prefer to directly instantiate the exception type as usual:

     
     throw new InternalServerErrorException("Server failed");
     
 

Parameters:

code - The HTTP error code.

message - The detail message.

cause - The exception which caused this exception to be thrown.

Returns:

A resource exception having the provided HTTP error code.

getException

@Deprecated
public static ResourceException getException(int code)

Deprecated. in favor of ResourceException.newResourceException(int)

Returns an exception with the specified HTTP error code, but no detail message or cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

Parameters:

code - The HTTP error code.

Returns:

A resource exception having the provided HTTP error code.

getException

@Deprecated
public static ResourceException getException(int code,
                                                         String message)

Deprecated. in favor of ResourceException.newResourceException(int, String)

Returns an exception with the specified HTTP error code and detail message, but no cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

Parameters:

code - The HTTP error code.

message - The detail message.

Returns:

A resource exception having the provided HTTP error code.

getException

@Deprecated
public static ResourceException getException(int code,
                                                         String message,
                                                         Throwable cause)

Deprecated. in favor of ResourceException.newResourceException(int, String, Throwable)

Returns an exception with the specified HTTP error code, detail message, and cause, and a default reason phrase. Useful for translating HTTP status codes to the relevant Java exception type. The type of the returned exception will be a sub-type of ResourceException.

Parameters:

code - The HTTP error code.

message - The detail message.

cause - The exception which caused this exception to be thrown.

Returns:

A resource exception having the provided HTTP error code.

getCode

public final int getCode()

Returns the numeric code of the exception.

Returns:

The numeric code of the exception.

isServerError

public boolean isServerError()

Returns true if the HTTP error code is in the 500 range.

Returns:

true if HTTP error code is in the 500 range.

getDetail

public final JsonValue getDetail()

Returns the additional detail which can be evaluated by applications. By default there is no additional detail ( getDetail().isNull() == true), and it is the responsibility of the resource provider to add it if needed.

Returns:

The additional detail which can be evaluated by applications (never null).

getReason

public final String getReason()

Returns the short reason phrase of the exception.

Returns:

The short reason phrase of the exception.

setDetail

public final <E extends ResourceException> E setDetail(JsonValue detail)

Sets the additional detail which can be evaluated by applications. By default there is no additional detail ( getDetail().isNull() == true), and it is the responsibility of the resource provider to add it if needed.

Type Parameters:

E - The ResourceException subtype

Parameters:

detail - The additional detail which can be evaluated by applications.

Returns:

This resource exception.

setReason

public final <E extends ResourceException> E setReason(String reason)

Sets/overrides the short reason phrase of the exception.

Type Parameters:

E - The ResourceException subtype

Parameters:

reason - The short reason phrase of the exception.

Returns:

This resource exception.

includeCauseInJsonValue

public final <E extends ResourceException> E includeCauseInJsonValue()

Returns this ResourceException with the includeCause flag set to true so that toJsonValue() method will include the cause if there is one supplied.

Type Parameters:

E - The ResourceException subtype

Returns:

the exception where this flag has been set

toJsonValue

public final JsonValue toJsonValue()

Returns the exception in a JSON object structure, suitable for inclusion in the entity of an HTTP error response. The JSON representation looks like this:

 {
     "code"    : 404,
     "reason"  : "...",  // optional
     "message" : "...",  // required
     "detail"  : { ... } // optional
     "cause"   : { ... } // optional iff includeCause is set to true
 }
 

Returns:

The exception in a JSON object structure, suitable for inclusion in the entity of an HTTP error response.

setResourceApiVersion

public void setResourceApiVersion(Version version)

Description copied from interface: Response

Sets the API version of the resource that the request was routed to.

Specified by:

setResourceApiVersion in interface Response

Parameters:

version - The resource API version.

getResourceApiVersion

public Version getResourceApiVersion()

Description copied from interface: Response

Gets the API version of the resource that the request was routed to.

Specified by:

getResourceApiVersion in interface Response

Returns:

The resource API version.

asPromise

public <V> Promise<V,ResourceException> asPromise()

Return this ResourceException as a Promise.

Type Parameters:

V - the result value type of the promise

Returns:

an Exception promise of type ResourceException