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 Summary

Constructors

Constructor	Description
JSONRPC2Request(String method, Object id)	Constructs a new JSON-RPC 2.0 request with no parameters.
JSONRPC2Request(String method, List<Object> positionalParams, Object id)	Constructs a new JSON-RPC 2.0 request with positional (JSON array) parameters.
JSONRPC2Request(String method, Map<String,Object> namedParams, Object id)	Constructs a new JSON-RPC 2.0 request with named (JSON object) parameters.

Method Summary

Modifier and Type	Method	Description
Object	getID()	Gets the request identifier.
String	getMethod()	Gets the name of the requested method.
Map<String,Object>	getNamedParams()	Gets the named parameters.
Object	getParams()	Deprecated.
JSONRPC2ParamsType	getParamsType()	Gets the parameters type (positional, named or none).
List<Object>	getPositionalParams()	Gets the positional (JSON array) parameters.
static JSONRPC2Request	parse(String jsonString)	Parses a JSON-RPC 2.0 request string.
static JSONRPC2Request	parse(String jsonString, boolean preserveOrder)	Parses a JSON-RPC 2.0 request string.
static JSONRPC2Request	parse(String jsonString, boolean preserveOrder, boolean ignoreVersion)	Parses a JSON-RPC 2.0 request string.
static JSONRPC2Request	parse(String jsonString, boolean preserveOrder, boolean ignoreVersion, boolean parseNonStdAttributes)	Parses a JSON-RPC 2.0 request string.
void	setID(Object id)	Sets the request identifier (ID).
void	setMethod(String method)	Sets the name of the requested method.
void	setNamedParams(Map<String,Object> namedParams)	Sets the named (JSON object) request parameters.
void	setParams(Object params)	Deprecated.
void	setPositionalParams(List<Object> positionalParams)	Sets the positional (JSON array) request parameters.
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

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 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 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<Object> for positional (JSON array), Map<String,Object> 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<Object>. For named (JSON object) pass a Map<String,Object>. 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.