com.thetransactioncompany.jsonrpc2
Class JSONRPC2Message

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

All Implemented Interfaces:

net.minidev.json.JSONAware

Direct Known Subclasses:

JSONRPC2Notification, JSONRPC2Request, JSONRPC2Response

public abstract class JSONRPC2Message
extends Object
implements net.minidev.json.JSONAware

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
 

The JSON-RPC 2.0 specification and user group forum can be found here.

Author:

Vladimir Dzhuvinov

Constructor Summary

JSONRPC2Message()

Method Summary

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 net.minidev.json.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

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 net.minidev.json.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.

Specified by:

toJSONString in interface net.minidev.json.JSONAware

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.