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

  • Field Details

  • 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 ResourceException 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.
      Parameters:
      detail - The additional detail which can be evaluated by applications.
      Returns:
      This resource exception.

    • setReason

      public final ResourceException setReason(String reason)
      Sets/overrides the short reason phrase of the exception.
      Parameters:
      reason - The short reason phrase of the exception.
      Returns:
      This resource exception.

    • includeCauseInJsonValue

      public final ResourceException includeCauseInJsonValue()
      Returns this ResourceException with the includeCause flag set to true so that toJsonValue() method will include the cause if there is one supplied.
      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