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

  • Constructor Details

  • Method Details

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

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

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