com.thetransactioncompany.jsonrpc2

## Class JSONRPC2Response

- java.lang.Object
- - com.thetransactioncompany.jsonrpc2.JSONRPC2Message
  - - com.thetransactioncompany.jsonrpc2.JSONRPC2Response

-     public class JSONRPC2Response
      extends JSONRPC2Message

  Represents a JSON-RPC 2.0 response.

  A response is returned to the caller after a JSON-RPC 2.0 request has been processed (notifications, however, don't produce a response). The response can take two different forms depending on the outcome:

  - The request was successful. The corresponding response returns a JSON object with the following information:
    - `result` The result, which can be of any JSON type - a number, a boolean value, a string, an array, an object or null.
    - `id` The request identifier which is echoed back back to the caller.
    - `jsonrpc` A string indicating the JSON-RPC protocol version set to "2.0".
  - The request failed. The returned JSON object contains:
    - `error` An object with:
      - `code` An integer indicating the error type.
      - `message` A brief error messsage.
      - `data` Optional error data.
    - `id` The request identifier. If it couldn't be determined, e.g. due to a request parse error, the ID is set to `null`.
    - `jsonrpc` A string indicating the JSON-RPC protocol version set to "2.0".

  Here is an example JSON-RPC 2.0 response string where the request has succeeded:

       {
          "result"  : true,
          "id"      : "req-002",
          "jsonrpc" : "2.0"
       }

  And here is an example JSON-RPC 2.0 response string indicating a failure:

       {
          "error"   : { "code" : -32601, "message" : "Method not found" },
          "id"      : "req-003",
          "jsonrpc" : "2.0"
       }

  A response object is obtained either by passing a valid JSON-RPC 2.0 response string to the static `parse(java.lang.String)` method or by invoking the appropriate constructor.

  Here is how parsing is done:

       String jsonString = "{\"result\":true,\"id\":\"req-002\",\"jsonrpc\":\"2.0\"}";

       JSONRPC2Response response = null;

       try {
               response = JSONRPC2Response.parse(jsonString);

       } catch (JSONRPC2Exception e) {
               // handle exception
       }

  And here is how you can replicate the above example response strings:

       // success example
       JSONRPC2Response resp = new JSONRPC2Response(true, "req-002");
       System.out.println(resp);

       // failure example
       JSONRPC2Error err = new JSONRPC2Error(-32601, "Method not found");
       resp = new JSONRPC2Response(err, "req-003");
       System.out.println(resp);

  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

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JSONRPC2Response(JSONRPC2Error error, Object id)` Creates a new JSON-RPC 2.0 response to a failed request.
    `JSONRPC2Response(Object id)` Creates a new JSON-RPC 2.0 response to a successful request which result is `null`.
    `JSONRPC2Response(Object result, Object id)` Creates a new JSON-RPC 2.0 response to a successful request.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `JSONRPC2Error` | `getError()` Gets the error object indicating the cause of the request failure.
    `Object` | `getID()` Gets the request identifier that is echoed back to the caller.
    `Object` | `getResult()` Gets the result of the request.
    `boolean` | `indicatesSuccess()` A convinience method to check if the response indicates success or failure of the request.
    `static JSONRPC2Response` | `parse(String jsonString)` Parses a JSON-RPC 2.0 response string.
    `static JSONRPC2Response` | `parse(String jsonString, boolean preserveOrder)` Parses a JSON-RPC 2.0 response string.
    `static JSONRPC2Response` | `parse(String jsonString, boolean preserveOrder, boolean ignoreVersion)` Parses a JSON-RPC 2.0 response string.
    `static JSONRPC2Response` | `parse(String jsonString, boolean preserveOrder, boolean ignoreVersion, boolean parseNonStdAttributes)` Parses a JSON-RPC 2.0 response string.
    `void` | `setError(JSONRPC2Error error)` Indicates a failed JSON-RPC 2.0 request and sets the error details.
    `void` | `setID(Object id)` Sets the request identifier echoed back to the caller.
    `void` | `setResult(Object result)` Indicates a successful JSON-RPC 2.0 request and sets the result.
    `JsonObject` | `toJSONObject()` Returns a JSON object representing this JSON-RPC 2.0 message.

    - ### Methods inherited from class com.thetransactioncompany.jsonrpc2.JSONRPC2Message

      `appendNonStdAttribute, getNonStdAttribute, getNonStdAttributes, toJSONString, toString`

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

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

- - ### Constructor Detail

    - #### JSONRPC2Response

          public JSONRPC2Response(JSONRPC2Error error,
                                  Object id)

      Creates a new JSON-RPC 2.0 response to a failed request.
      Parameters:
        `error` - A JSON-RPC 2.0 error instance indicating the cause of the failure. Must not be `null`.
        `id` - The request identifier echoed back to the caller. Pass a `null` if the request identifier couldn't be determined (e.g. due to a parse error).

    - #### JSONRPC2Response

          public JSONRPC2Response(Object id)

      Creates a new JSON-RPC 2.0 response to a successful request which result is `null`.
      Parameters:
        `id` - The request identifier echoed back to the caller. May be `null` though not recommended.

    - #### JSONRPC2Response

          public JSONRPC2Response(Object result,
                                  Object id)

      Creates a new JSON-RPC 2.0 response to a successful request.
      Parameters:
        `result` - The result. The value can map to any JSON type. May be `null`.
        `id` - The request identifier echoed back to the caller. May be `null` though not recommended.

  - ### Method Detail

    - #### getError

          public JSONRPC2Error getError()

      Gets the error object indicating the cause of the request failure. If a `null` is returned, the request succeeded and there was no error.
      Returns:
        A JSON-RPC 2.0 error object, `null` if the response indicates success.

    - #### getID

          public Object getID()

      Gets the request identifier that is echoed back to the caller.
      Returns:
        The request identifier. If there was an error during the the request retrieval (e.g. parse error) and the identifier couldn't be determined, the value will be `null`.

    - #### getResult

          public Object getResult()

      Gets the result of the request. The returned value has meaning only if the request was successful. Use the `getError` method to check this.
      Returns:
        The result.

    - #### indicatesSuccess

          public boolean indicatesSuccess()

      A convinience method to check if the response indicates success or failure of the request. Alternatively, you can use the `#getError` method for this purpose.
      Returns:
        `true` if the request succeeded, `false` if there was an error.

    - #### parse

          public static JSONRPC2Response parse(String jsonString)
                                        throws JSONRPC2ParseException

      Parses a JSON-RPC 2.0 response string. This method is thread-safe.
      Parameters:
        `jsonString` - The JSON-RPC 2.0 response string, UTF-8 encoded. Must not be `null`.
      Returns:
        The corresponding JSON-RPC 2.0 response object.
      Throws:
        `JSONRPC2ParseException` - With detailed message if parsing failed.

    - #### parse

          public static JSONRPC2Response parse(String jsonString,
                                               boolean preserveOrder)
                                        throws JSONRPC2ParseException

      Parses a JSON-RPC 2.0 response string. This method is thread-safe.
      Parameters:
        `jsonString` - The JSON-RPC 2.0 response string, UTF-8 encoded. Must not be `null`.
        `preserveOrder` - `true` to preserve the order of JSON object members in results.
      Returns:
        The corresponding JSON-RPC 2.0 response object.
      Throws:
        `JSONRPC2ParseException` - With detailed message if parsing failed.

    - #### parse

          public static JSONRPC2Response parse(String jsonString,
                                               boolean preserveOrder,
                                               boolean ignoreVersion)
                                        throws JSONRPC2ParseException

      Parses a JSON-RPC 2.0 response string. This method is thread-safe.
      Parameters:
        `jsonString` - The JSON-RPC 2.0 response string, UTF-8 encoded. Must not be `null`.
        `preserveOrder` - `true` to preserve the order of JSON object members in results.
        `ignoreVersion` - `true` to skip a check of the `"jsonrpc":"2.0"` version attribute in the JSON-RPC 2.0 message.
      Returns:
        The corresponding JSON-RPC 2.0 response object.
      Throws:
        `JSONRPC2ParseException` - With detailed message if the parsing failed.

    - #### parse

          public static JSONRPC2Response parse(String jsonString,
                                               boolean preserveOrder,
                                               boolean ignoreVersion,
                                               boolean parseNonStdAttributes)
                                        throws JSONRPC2ParseException

      Parses a JSON-RPC 2.0 response string. This method is thread-safe.
      Parameters:
        `jsonString` - The JSON-RPC 2.0 response string, UTF-8 encoded. Must not be `null`.
        `preserveOrder` - `true` to preserve the order of JSON object members in results.
        `ignoreVersion` - `true` to skip a check of the `"jsonrpc":"2.0"` version attribute in the JSON-RPC 2.0 message.
        `parseNonStdAttributes` - `true` to parse non-standard attributes found in the JSON-RPC 2.0 message.
      Returns:
        The corresponding JSON-RPC 2.0 response object.
      Throws:
        `JSONRPC2ParseException` - With detailed message if the parsing failed.

    - #### setError

          public void setError(JSONRPC2Error error)

      Indicates a failed JSON-RPC 2.0 request and sets the error details. Note that if the response was previously indicating success this will turn it into a response indicating failure. Any previously set result data will be invalidated.
      Parameters:
        `error` - A JSON-RPC 2.0 error instance indicating the cause of the failure. Must not be `null`.

    - #### setID

          public void setID(Object id)

      Sets the request identifier echoed back to the caller.
      Parameters:
        `id` - The value must map to a JSON scalar. Pass a `null` if the request identifier couldn't be determined (e.g. due to a parse error).

    - #### setResult

          public void setResult(Object result)

      Indicates a successful JSON-RPC 2.0 request and sets the result. Note that if the response was previously indicating failure this will turn it into a response indicating success. Any previously set error data will be invalidated.
      Parameters:
        `result` - The result. The value can map to any JSON type. May be `null`.

    - #### toJSONObject

          public JsonObject toJSONObject()

      Description copied from class: `JSONRPC2Message`
      Returns a JSON object representing this JSON-RPC 2.0 message.
      Specified by:
        `toJSONObject` in class `JSONRPC2Message`
      Returns:
        The JSON object.