Package 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, UnsupportedMediaTypeException
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:

  • Field Details

    • FIELD_DETAIL

      public static final String FIELD_DETAIL
      The name of the JSON field used for the detail.
      See Also:

    • FIELD_MESSAGE

      public static final String FIELD_MESSAGE
      The name of the JSON field used for the message.
      See Also:

    • FIELD_REASON

      public static final String FIELD_REASON
      The name of the JSON field used for the reason.
      See Also:

    • FIELD_CODE

      public static final String FIELD_CODE
      The name of the JSON field used for the code.
      See Also:

    • FIELD_CAUSE

      public static final String FIELD_CAUSE
      The name of the JSON field used for the cause message.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • UNSUPPORTED_MEDIA_TYPE

      public static final int UNSUPPORTED_MEDIA_TYPE
      Indicates that the media type of the request body was not acceptable to the server. This may be due to the Content-Type or Content-Encoding of the body.
      See Also:

  • Constructor Details

    • 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 Details

    • 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 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 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 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