com.thetransactioncompany.jsonrpc2

## Class JSONRPC2Error

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - com.thetransactioncompany.jsonrpc2.JSONRPC2Error

- All Implemented Interfaces:
    Serializable
  Direct Known Subclasses:
    JSONRPC2ExtendedError

      public class JSONRPC2Error
      extends Exception

  Represents a JSON-RPC 2.0 error that occurred during the processing of a request. This class is immutable.

  The protocol expects error objects to be structured like this:

  - `code` An integer that indicates the error type.
  - `message` A string providing a short description of the error. The message should be limited to a concise single sentence.
  - `data` Additional information, which may be omitted. Its contents is entirely defined by the application.

  Note that the "Error" word in the class name was put there solely to comply with the parlance of the JSON-RPC spec. This class doesn't inherit from `java.lang.Error`. It's a regular subclass of `java.lang.Exception` and, if thrown, it's to indicate a condition that a reasonable application might want to catch.

  This class also includes convenient final static instances for all standard JSON-RPC 2.0 errors:

  - `PARSE_ERROR` JSON parse error (-32700)
  - `INVALID_REQUEST` Invalid JSON-RPC 2.0 Request (-32600)
  - `METHOD_NOT_FOUND` Method not found (-32601)
  - `INVALID_PARAMS` Invalid parameters (-32602)
  - `INTERNAL_ERROR` Internal error (-32603)

  Note that the range -32099..-32000 is reserved for additional server errors.

  The mapping between JSON and Java entities (as defined by the underlying JSON Smart library):

           true|false  <--->  java.lang.Boolean
           number      <--->  java.lang.Number
           string      <--->  java.lang.String
           array       <--->  java.util.List
           object      <--->  java.util.Map
           null        <--->  null

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static JSONRPC2Error` | `INTERNAL_ERROR` Internal JSON-RPC 2.0 error (-32603).
    `static JSONRPC2Error` | `INVALID_PARAMS` Invalid parameters error (-32602).
    `static JSONRPC2Error` | `INVALID_REQUEST` Invalid JSON-RPC 2.0 request error (-32600).
    `static JSONRPC2Error` | `METHOD_NOT_FOUND` Method not found error (-32601).
    `static JSONRPC2Error` | `PARSE_ERROR` JSON parse error (-32700).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JSONRPC2Error(int code, String message)` Creates a new JSON-RPC 2.0 error with the specified code and message.
    `JSONRPC2Error(int code, String message, Object data)` Creates a new JSON-RPC 2.0 error with the specified code, message and data.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static JSONRPC2Error` | `appendMessage(JSONRPC2Error err, String apx)` Deprecated.
    `JSONRPC2Error` | `appendMessage(String apx)` Appends the specified string to the message of this JSON-RPC 2.0 error.
    `boolean` | `equals(Object object)` Overrides `Object.equals()`.
    `int` | `getCode()` Gets the JSON-RPC 2.0 error code.
    `Object` | `getData()` Gets the JSON-RPC 2.0 error data.
    `int` | `hashCode()`
    `static JSONRPC2Error` | `setData(JSONRPC2Error err, Object data)` Deprecated.
    `JSONRPC2Error` | `setData(Object data)` Sets the specified data to a JSON-RPC 2.0 error.
    `JsonObject` | `toJSON()` Deprecated.
    `JsonObject` | `toJSONObject()` Returns a JSON object representation of this JSON-RPC 2.0 error.
    `String` | `toString()` Serialises the error object to a JSON string.

    - ### Methods inherited from class java.lang.Throwable

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

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### INTERNAL_ERROR

          public static final JSONRPC2Error INTERNAL_ERROR

      Internal JSON-RPC 2.0 error (-32603).

    - #### INVALID_PARAMS

          public static final JSONRPC2Error INVALID_PARAMS

      Invalid parameters error (-32602).

    - #### INVALID_REQUEST

          public static final JSONRPC2Error INVALID_REQUEST

      Invalid JSON-RPC 2.0 request error (-32600).

    - #### METHOD_NOT_FOUND

          public static final JSONRPC2Error METHOD_NOT_FOUND

      Method not found error (-32601).

    - #### PARSE_ERROR

          public static final JSONRPC2Error PARSE_ERROR

      JSON parse error (-32700).

  - ### Constructor Detail

    - #### JSONRPC2Error

          public JSONRPC2Error(int code,
                               String message)

      Creates a new JSON-RPC 2.0 error with the specified code and message. The optional data is omitted.
      Parameters:
        `code` - The error code (standard pre-defined or application-specific).
        `message` - The error message.

    - #### JSONRPC2Error

          public JSONRPC2Error(int code,
                               String message,
                               Object data)

      Creates a new JSON-RPC 2.0 error with the specified code, message and data.
      Parameters:
        `code` - The error code (standard pre-defined or application-specific).
        `message` - The error message.
        `data` - Optional error data, must map to a valid JSON type.

  - ### Method Detail

    - #### appendMessage

          @Deprecated
          public static JSONRPC2Error appendMessage(JSONRPC2Error err,
                                                                String apx)

      Deprecated.
      Appends the specified string to the message of a JSON-RPC 2.0 error.
      Parameters:
        `err` - The JSON-RPC 2.0 error. Must not be `null`.
        `apx` - The string to append to the original error message.
      Returns:
        A new JSON-RPC 2.0 error with the appended message.

    - #### appendMessage

          public JSONRPC2Error appendMessage(String apx)

      Appends the specified string to the message of this JSON-RPC 2.0 error.
      Parameters:
        `apx` - The string to append to the original error message.
      Returns:
        A new JSON-RPC 2.0 error with the appended message.

    - #### equals

          public boolean equals(Object object)

      Overrides `Object.equals()`.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - The object to compare to.
      Returns:
        `true` if both objects are instances if this class and their error codes are identical, `false` if not.

    - #### getCode

          public int getCode()

      Gets the JSON-RPC 2.0 error code.
      Returns:
        The error code.

    - #### getData

          public Object getData()

      Gets the JSON-RPC 2.0 error data.
      Returns:
        The error data, `null` if none was specified.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### setData

          @Deprecated
          public static JSONRPC2Error setData(JSONRPC2Error err,
                                                          Object data)

      Deprecated.
      Sets the specified data to a JSON-RPC 2.0 error.
      Parameters:
        `err` - The JSON-RPC 2.0 error to have its data field set. Must not be `null`.
        `data` - Optional error data, must map to a valid JSON type.
      Returns:
        A new JSON-RPC 2.0 error with the set data.

    - #### setData

          public JSONRPC2Error setData(Object data)

      Sets the specified data to a JSON-RPC 2.0 error.
      Parameters:
        `data` - Optional error data, must map to a valid JSON type.
      Returns:
        A new JSON-RPC 2.0 error with the set data.

    - #### toJSON

          @Deprecated
          public JsonObject toJSON()

      Deprecated.
      See Also:
        `toJSONObject()`

    - #### toJSONObject

          public JsonObject toJSONObject()

      Returns a JSON object representation of this JSON-RPC 2.0 error.
      Returns:
        A JSON object representing this error object.

    - #### toString

          public String toString()

      Serialises the error object to a JSON string.
      Overrides:
        `toString` in class `Throwable`
      Returns:
        A JSON-encoded string representing this error object.