Package com.thetransactioncompany.jsonrpc2

Class 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 Detail

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

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