Package 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
Author:
Vladimir Dzhuvinov

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

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