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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    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&lt;Object&gt;` for positional (JSON array), `Map&lt;String,Object&gt;` 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&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.

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