com.thetransactioncompany.jsonrpc2
Class JSONRPC2Notification

java.lang.Object
  com.thetransactioncompany.jsonrpc2.JSONRPC2Message
      com.thetransactioncompany.jsonrpc2.JSONRPC2Notification

All Implemented Interfaces:

net.minidev.json.JSONAware

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
 

The JSON-RPC 2.0 specification and user group forum can be found here.

Author:

Vladimir Dzhuvinov

Constructor Summary

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

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.
net.minidev.json.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

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.

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

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 notification parameters.

This method was deprecated in version 1.30. Use setPositionalParams(java.util.List) or setNamedParams(java.util.Map) 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

toJSONObject

public net.minidev.json.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.