com.thetransactioncompany.jsonrpc2

Class JSONRPC2Notification

java.lang.Object

com.thetransactioncompany.jsonrpc2.JSONRPC2Message

com.thetransactioncompany.jsonrpc2.JSONRPC2Notification

public class JSONRPC2Notification
extends JSONRPC2Message

Represents a JSON-RPC 2.0 notification.

Notifications provide a mean for calling a remote procedure without generating a response. Note that notifications are inherently unreliable as no confirmation is sent back to the caller.

Notifications have the same JSON structure as requests, except that they lack an identifier:

• 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.
• jsonrpc A string indicating the JSON-RPC protocol version set to "2.0".

Here is a sample JSON-RPC 2.0 notification string:

 {
    "method"  : "progressNotify",
    "params"  : ["75%"],
    "jsonrpc" : "2.0"
 }
 

This class provides two methods to obtain a request object:

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

Example 1: Parsing a notification string:

 String jsonString = "{\"method\":\"progressNotify\",\"params\":[\"75%\"],\"jsonrpc\":\"2.0\"}";

 JSONRPC2Notification notification = null;

 try {
         notification = JSONRPC2Notification.parse(jsonString);

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

Example 2: Recreating the above request:

 String method = "progressNotify";
 List<Object> params = new Vector<Object>();
 params.add("75%");

 JSONRPC2Notification notification = new JSONRPC2Notification(method, params);

 System.out.println(notification);
 

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
 

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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 JSONRPC2Notification	parse(String jsonString) Parses a JSON-RPC 2.0 notification string.
static JSONRPC2Notification	parse(String jsonString, boolean preserveOrder) Parses a JSON-RPC 2.0 notification string.
static JSONRPC2Notification	parse(String jsonString, boolean preserveOrder, boolean ignoreVersion) Parses a JSON-RPC 2.0 notification string.
static JSONRPC2Notification	parse(String jsonString, boolean preserveOrder, boolean ignoreVersion, boolean parseNonStdAttributes) Parses a JSON-RPC 2.0 notification string.
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

JSONRPC2Notification

public JSONRPC2Notification(String method)

Constructs a new JSON-RPC 2.0 notification with no parameters.

Parameters:

method - The name of the requested method. Must not be null.

JSONRPC2Notification

public JSONRPC2Notification(String method,
                            List<Object> positionalParams)

Constructs a new JSON-RPC 2.0 notification 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.

JSONRPC2Notification

public JSONRPC2Notification(String method,
                            Map<String,Object> namedParams)

Constructs a new JSON-RPC 2.0 notification with named (JSON object) parameters.

Parameters:

method - The name of the requested method.

namedParams - The named (JSON object) parameters, null if none.

Method Detail

getMethod

public String getMethod()

Gets the name of the requested method.

Returns:

The method name.

getNamedParams

public Map<String,Object> getNamedParams()

Gets the named parameters.

Returns:

The named (JSON object) parameters, null if none or positional.

getParams

@Deprecated
public Object getParams()

Deprecated.

Gets the notification 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.

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 or named.

parse

public static JSONRPC2Notification parse(String jsonString)
                                  throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 notification string. This method is thread-safe.

Parameters:

jsonString - The JSON-RPC 2.0 notification string, UTF-8 encoded. Must not be null.

Returns:

The corresponding JSON-RPC 2.0 notification object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

parse

public static JSONRPC2Notification parse(String jsonString,
                                         boolean preserveOrder)
                                  throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 notification string. This method is thread-safe.

Parameters:

jsonString - The JSON-RPC 2.0 notification 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 notification object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

parse

public static JSONRPC2Notification parse(String jsonString,
                                         boolean preserveOrder,
                                         boolean ignoreVersion)
                                  throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 notification string. This method is thread-safe.

Parameters:

jsonString - The JSON-RPC 2.0 notification 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 notification object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

parse

public static JSONRPC2Notification parse(String jsonString,
                                         boolean preserveOrder,
                                         boolean ignoreVersion,
                                         boolean parseNonStdAttributes)
                                  throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 notification string. This method is thread-safe.

Parameters:

jsonString - The JSON-RPC 2.0 notification 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 notification object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

setMethod

public void setMethod(String method)

Sets the name of the requested method.

Parameters:

method - The method name. Must not be null.

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.

setParams

@Deprecated
public void setParams(Object params)

Deprecated.

Sets the notification 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.

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.