Package com.thetransactioncompany.jsonrpc2

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

      • 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

      • 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