com.thetransactioncompany.jsonrpc2

Class JSONRPC2Response

java.lang.Object

com.thetransactioncompany.jsonrpc2.JSONRPC2Message

com.thetransactioncompany.jsonrpc2.JSONRPC2Response

All Implemented Interfaces:

net.minidev.json.JSONAware

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

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.
net.minidev.json.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(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.

toJSONObject

public net.minidev.json.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.