com.thetransactioncompany.jsonrpc2

## Class JSONRPC2Message

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

- Direct Known Subclasses:
    JSONRPC2Notification, JSONRPC2Request, JSONRPC2Response

      public abstract class JSONRPC2Message
      extends Object

  The base abstract class for JSON-RPC 2.0 requests, notifications and responses. Provides common methods for parsing (from JSON string) and serialisation (to JSON string) of these three message types.

  Example parsing and serialisation back to JSON:

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

       JSONRPC2Message message = null;

       // parse
       try {
              message = JSONRPC2Message.parse(jsonString);
       } catch (JSONRPC2ParseException e) {
              // handle parse exception
       }

       if (message instanceof JSONRPC2Request)
              System.out.println("The message is a request");
       else if (message instanceof JSONRPC2Notification)
              System.out.println("The message is a notification");
       else if (message instanceof JSONRPC2Response)
              System.out.println("The message is a response");

       // serialise back to JSON string
       System.out.println(message);

  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
    `JSONRPC2Message()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendNonStdAttribute(String name, Object value)` Appends a non-standard attribute to this JSON-RPC 2.0 message.
    `Object` | `getNonStdAttribute(String name)` Retrieves a non-standard JSON-RPC 2.0 message attribute.
    `Map<String,Object>` | `getNonStdAttributes()` Retrieves the non-standard JSON-RPC 2.0 message attributes.
    `static JSONRPC2Message` | `parse(String jsonString)` Provides common parsing of JSON-RPC 2.0 requests, notifications and responses.
    `static JSONRPC2Message` | `parse(String jsonString, boolean preserveOrder, boolean ignoreVersion)` Provides common parsing of JSON-RPC 2.0 requests, notifications and responses.
    `abstract JsonObject` | `toJSONObject()` Returns a JSON object representing this JSON-RPC 2.0 message.
    `String` | `toJSONString()` Returns a JSON string representation of this JSON-RPC 2.0 message.
    `String` | `toString()` Serialises this JSON-RPC 2.0 message to a JSON object string.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### JSONRPC2Message

          public JSONRPC2Message()

  - ### Method Detail

    - #### appendNonStdAttribute

          public void appendNonStdAttribute(String name,
                                            Object value)

      Appends a non-standard attribute to this JSON-RPC 2.0 message. This is done by adding a new member (key / value pair) to the top level JSON object representing the message.

      You may use this method to add meta and debugging attributes, such as the request processing time, to a JSON-RPC 2.0 message.

      Parameters:
        `name` - The attribute name. Must not conflict with the existing "method", "id", "params", "result", "error" and "jsonrpc" attributes reserved by the JSON-RPC 2.0 protocol, else an `IllegalArgumentException` will be thrown. Must not be `null` either.
        `value` - The attribute value. Must be of type String, boolean, number, List, Map or null, else an `IllegalArgumentException` will be thrown.

    - #### getNonStdAttribute

          public Object getNonStdAttribute(String name)

      Retrieves a non-standard JSON-RPC 2.0 message attribute.
      Parameters:
        `name` - The name of the non-standard attribute to retrieve. Must not be `null`.
      Returns:
        The value of the non-standard attribute (may also be `null`, `null` if not found.

    - #### getNonStdAttributes

          public Map<String,Object> getNonStdAttributes()

      Retrieves the non-standard JSON-RPC 2.0 message attributes.
      Returns:
        The non-standard attributes as a map, `null` if none.

    - #### parse

          public static JSONRPC2Message parse(String jsonString)
                                       throws JSONRPC2ParseException

      Provides common parsing of JSON-RPC 2.0 requests, notifications and responses. Use this method if you don't know which type of JSON-RPC message the input JSON string represents.

      Batched requests / notifications are not supported.

      This method is thread-safe.

      If you are certain about the message type use the dedicated `JSONRPC2Request.parse(java.lang.String)`, `JSONRPC2Notification.parse(java.lang.String)` or `JSONRPC2Response.parse(java.lang.String)` methods. They are more efficient and provide a more detailed parse error reporting.

      The member order of parsed JSON objects will not be preserved (for efficiency reasons) and the JSON-RPC 2.0 version field must be set to "2.0". To change this behaviour check the optional `parse(String,boolean,boolean)` method.

      Parameters:
        `jsonString` - A JSON string representing a JSON-RPC 2.0 request, notification or response, UTF-8 encoded. Must not be `null`.
      Returns:
        An instance of `JSONRPC2Request`, `JSONRPC2Notification` or `JSONRPC2Response`.
      Throws:
        `JSONRPC2ParseException` - With detailed message if parsing failed.

    - #### parse

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

      Provides common parsing of JSON-RPC 2.0 requests, notifications and responses. Use this method if you don't know which type of JSON-RPC message the input string represents.

      Batched requests / notifications are not supported.

      This method is thread-safe.

      If you are certain about the message type use the dedicated `JSONRPC2Request.parse(java.lang.String)`, `JSONRPC2Notification.parse(java.lang.String)` or `JSONRPC2Response.parse(java.lang.String)` methods. They are more efficient and provide a more detailed parse error reporting.

      Parameters:
        `jsonString` - A JSON string representing a JSON-RPC 2.0 request, notification or response, UTF-8 encoded. Must not be `null`.
        `preserveOrder` - If `true` the member order of JSON objects in parameters and results must be preserved.
        `ignoreVersion` - If `true` the `"jsonrpc":"2.0"` version field in the JSON-RPC 2.0 message will not be checked.
      Returns:
        An instance of `JSONRPC2Request`, `JSONRPC2Notification` or `JSONRPC2Response`.
      Throws:
        `JSONRPC2ParseException` - With detailed message if parsing failed.

    - #### toJSONObject

          public abstract JsonObject toJSONObject()

      Returns a JSON object representing this JSON-RPC 2.0 message.
      Returns:
        The JSON object.

    - #### toJSONString

          public String toJSONString()

      Returns a JSON string representation of this JSON-RPC 2.0 message.
      Returns:
        The JSON object string representing this JSON-RPC 2.0 message.
      See Also:
        `toString()`

    - #### toString

          public String toString()

      Serialises this JSON-RPC 2.0 message to a JSON object string.
      Overrides:
        `toString` in class `Object`
      Returns:
        The JSON object string representing this JSON-RPC 2.0 message.