Class JSONRPC2Request

  • All Implemented Interfaces:
    net.minidev.json.JSONAware

    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 Detail

      • JSONRPC2Request

        public JSONRPC2Request​(String method,
                               Object id)
        Creates 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)
        Creates 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)
        Creates 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 Detail

      • 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 JSON-RPC 2.0 request object.
        Throws:
        JSONRPC2ParseException - With detailed message if parsing failed.
      • parse

        @Deprecated
        public static JSONRPC2Request parse​(String jsonString,
                                            boolean preserveOrder)
                                     throws JSONRPC2ParseException
        Deprecated.
        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 JSON-RPC 2.0 request object.
        Throws:
        JSONRPC2ParseException - With detailed message if parsing failed.
      • parse

        @Deprecated
        public static JSONRPC2Request parse​(String jsonString,
                                            boolean preserveOrder,
                                            boolean ignoreVersion)
                                     throws JSONRPC2ParseException
        Deprecated.
        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 member in the JSON-RPC 2.0 message.
        Returns:
        The JSON-RPC 2.0 request object.
        Throws:
        JSONRPC2ParseException - With detailed message if parsing failed.
      • parse

        @Deprecated
        public static JSONRPC2Request parse​(String jsonString,
                                            boolean preserveOrder,
                                            boolean ignoreVersion,
                                            boolean parseNonStdMembers)
                                     throws JSONRPC2ParseException
        Deprecated.
        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 member in the JSON-RPC 2.0 message.
        parseNonStdMembers - true to parse non-standard members found in the JSON-RPC 2.0 message.
        Returns:
        The 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.
      • getPositionalParams

        public List<ObjectgetPositionalParams()
        Gets the positional (JSON array) parameters.
        Returns:
        The positional (JSON array) parameters, null if none or named.
        Since:
        1.30
      • getNamedParams

        public Map<String,​ObjectgetNamedParams()
        Gets the named parameters.
        Returns:
        The named (JSON object) parameters, null if none or positional.
        Since:
        1.30
      • 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).