Package com.thetransactioncompany.jsonrpc2

Class JSONRPC2Request

java.lang.Object
com.thetransactioncompany.jsonrpc2.JSONRPC2Message
com.thetransactioncompany.jsonrpc2.JSONRPC2Request
public class JSONRPC2Request extends 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(java.lang.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
Author:
Vladimir Dzhuvinov

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

    • getParams

      @Deprecated public Object getParams()
      Deprecated.
      Gets the request parameters.

      This method was deprecated in version 1.30. Use getPositionalParams() or getNamedParams() instead.

      Returns:
      The parameters as List&lt;Object&gt; for positional (JSON array), Map&lt;String,Object&gt; for named (JSON object), or null if none.

    • getPositionalParams

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

    • getNamedParams

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

    • setParams

      @Deprecated public void setParams(Object params)
      Deprecated.
      Sets the request parameters.

      This method was deprecated in version 1.30. Use setPositionalParams(java.util.List<java.lang.Object>) or setNamedParams(java.util.Map<java.lang.String, java.lang.Object>) instead.

      Parameters:
      params - The parameters. For positional (JSON array) pass a List&lt;Object&gt;. For named (JSON object) pass a Map&lt;String,Object&gt;. If there are no parameters pass null.

    • setPositionalParams

      public void setPositionalParams(List<Object> positionalParams)
      Sets the positional (JSON array) request parameters.
      Parameters:
      positionalParams - The positional (JSON array) request parameters, null if none.
      Since:
      1.30

    • setNamedParams

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

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