Package 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
Author:
Vladimir Dzhuvinov

  • Constructor Details

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

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

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