java.lang.Object
com.thetransactioncompany.jsonrpc2.JSONRPC2Message
com.thetransactioncompany.jsonrpc2.JSONRPC2Response
public class JSONRPC2Responseextends 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 message.
      • 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(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

  • Field Details

    • result

      private Object result
      The result.

    • error

      private JSONRPC2Error error
      The error object.

    • id

      private Object id
      The echoed request identifier.

  • Constructor Details

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

    • 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(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).

  • Method Details

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

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

    • 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 request result, of any JSON type - a number, a boolean, a string, an array or an object - or null if the request 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.

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

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

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

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

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