java.lang.Object
com.thetransactioncompany.jsonrpc2.JSONRPC2Message
com.thetransactioncompany.jsonrpc2.JSONRPC2Request
public class JSONRPC2Requestextends JSONRPC2Message
Represents a JSON-RPC 2.0 request.

A request carries four pieces of data:

  • method The name of the remote method to call.
  • params The required method parameters (if any), which can be packed into a JSON array or object.
  • id An identifier which is echoed back to the client with the response.
  • jsonrpc A string indicating the JSON-RPC protocol version set to "2.0".

Here is a sample JSON-RPC 2.0 request string:

{
   "method"  : "makePayment",
   "params"  : { "recipient" : "Penny Adams", "amount":175.05 },
   "id"      : "0001",
   "jsonrpc" : "2.0"
}

This class provides two methods to obtain a request object:

  • Pass a JSON-RPC 2.0 request string to the static parse(String) method, or
  • Invoke one of the constructors with the appropriate arguments.

Example 1: Parsing a request string:

String jsonString = "{\"method\":\"makePayment\"," +
                    "\"params\":{\"recipient\":\"Penny Adams\",\"amount\":175.05}," +
                    "\"id\":\"0001\","+
                    "\"jsonrpc\":\"2.0\"}";

JSONRPC2Request req = null;

try {
        req = JSONRPC2Request.parse(jsonString);

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

Example 2: Recreating the above request:

String method = "makePayment";
Map<String,Object> params = new HashMap<String,Object>();
params.put("recipient", "Penny Adams");
params.put("amount", 175.05);
String id = "0001";

JSONRPC2Request req = new JSONRPC2Request(method, params, id);

System.out.println(req);

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

    • method

      private String method
      The method name.

    • positionalParams

      private List<Object> positionalParams
      The positional parameters, null if none.

    • namedParams

      private Map<String,Object> namedParams
      The named parameters, null if none.

    • id

      private Object id
      The request identifier.

  • Constructor Details

    • JSONRPC2Request

      public JSONRPC2Request(String method, Object id)
      Constructs a new JSON-RPC 2.0 request with no parameters.
      Parameters:
      method - The name of the requested method. Must not be null.
      id - The request identifier echoed back to the caller. The value must map to a JSON scalar (null and fractions, however, should be avoided).

    • JSONRPC2Request

      public JSONRPC2Request(String method, List<Object> positionalParams, Object id)
      Constructs a new JSON-RPC 2.0 request with positional (JSON array) parameters.
      Parameters:
      method - The name of the requested method. Must not be null.
      positionalParams - The positional (JSON array) parameters, null if none.
      id - The request identifier echoed back to the caller. The value must map to a JSON scalar (null and fractions, however, should be avoided).

    • JSONRPC2Request

      public JSONRPC2Request(String method, Map<String,Object> namedParams, Object id)
      Constructs a new JSON-RPC 2.0 request with named (JSON object) parameters.
      Parameters:
      method - The name of the requested method.
      namedParams - The named (JSON object) parameters, null if none.
      id - The request identifier echoed back to the caller. The value must map to a JSON scalar (null and fractions, however, should be avoided).

  • Method Details

    • parse

      public static JSONRPC2Request parse(String jsonString) throws JSONRPC2ParseException
      Parses a JSON-RPC 2.0 request string. This method is thread-safe.
      Parameters:
      jsonString - The JSON-RPC 2.0 request string, UTF-8 encoded. Must not be null.
      Returns:
      The corresponding JSON-RPC 2.0 request object.
      Throws:
      JSONRPC2ParseException - With detailed message if parsing failed.

    • parse

      public static JSONRPC2Request parse(String jsonString, boolean preserveOrder) throws JSONRPC2ParseException
      Parses a JSON-RPC 2.0 request string. This method is thread-safe.
      Parameters:
      jsonString - The JSON-RPC 2.0 request string, UTF-8 encoded. Must not be null.
      preserveOrder - true to preserve the order of JSON object members in parameters.
      Returns:
      The corresponding JSON-RPC 2.0 request object.
      Throws:
      JSONRPC2ParseException - With detailed message if parsing failed.

    • parse

      public static JSONRPC2Request parse(String jsonString, boolean preserveOrder, boolean ignoreVersion) throws JSONRPC2ParseException
      Parses a JSON-RPC 2.0 request string. This method is thread-safe.
      Parameters:
      jsonString - The JSON-RPC 2.0 request string, UTF-8 encoded. Must not be null.
      preserveOrder - true to preserve the order of JSON object members in parameters.
      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 request object.
      Throws:
      JSONRPC2ParseException - With detailed message if parsing failed.

    • parse

      public static JSONRPC2Request parse(String jsonString, boolean preserveOrder, boolean ignoreVersion, boolean parseNonStdAttributes) throws JSONRPC2ParseException
      Parses a JSON-RPC 2.0 request string. This method is thread-safe.
      Parameters:
      jsonString - The JSON-RPC 2.0 request string, UTF-8 encoded. Must not be null.
      preserveOrder - true to preserve the order of JSON object members in parameters.
      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 request object.
      Throws:
      JSONRPC2ParseException - With detailed message if parsing failed.

    • getMethod

      public String getMethod()
      Gets the name of the requested method.
      Returns:
      The method name.

    • setMethod

      public void setMethod(String method)
      Sets the name of the requested method.
      Parameters:
      method - The method name. Must not be null.

    • getParamsType

      public JSONRPC2ParamsType getParamsType()
      Gets the parameters type (positional, named or none).
      Returns:
      The parameters type.

    • getPositionalParams

      public List<Object> getPositionalParams()
      Gets the positional (JSON array) parameters.
      Returns:
      The positional (JSON array) parameters, null if none

    • getNamedParams

      public Map<String,Object> getNamedParams()
      Gets the named parameters.
      Returns:
      The named (JSON object) parameters, null if none or

    • setPositionalParams

      public void setPositionalParams(List<Object> positionalParams)
      Sets the positional (JSON array) request parameters.
      Parameters:
      positionalParams - The positional (JSON array) request

    • setNamedParams

      public void setNamedParams(Map<String,Object> namedParams)
      Sets the named (JSON object) request parameters.
      Parameters:
      namedParams - The named (JSON object) request parameters,

    • getID

      public Object getID()
      Gets the request identifier.
      Returns:
      The request identifier (Number, Boolean, String) or null.

    • setID

      public void setID(Object id)
      Sets the request identifier (ID).
      Parameters:
      id - The request identifier echoed back to the caller. The value must map to a JSON scalar (null and fractions, however, should be avoided).

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