Package 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 the 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 Summary

Constructors

Constructor	Description
JSONRPC2Message()

Method Summary

Modifier and Type	Method	Description
void	appendNonStdAttribute(String name, Object value)	Deprecated.
void	appendNonStdMember(String name, Object value)	Appends a non-standard member to this JSON-RPC 2.0 message.
Object	getNonStdAttribute(String name)	Deprecated.
Map<String,Object>	getNonStdAttributes()	Deprecated.
Object	getNonStdMember(String name)	Gets a non-standard JSON-RPC 2.0 message member.
Map<String,Object>	getNonStdMembers()	Gets the non-standard JSON-RPC 2.0 message members.
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)	Deprecated.
static JSONRPC2Message	parse(String jsonString, JSONRPC2Parser.Option... options)	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.

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,
                                    JSONRPC2Parser.Option... options)
                             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.

options - The parse options.

Returns:

An instance of JSONRPC2Request, JSONRPC2Notification or JSONRPC2Response.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

parse

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

Deprecated.

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

appendNonStdMember

public void appendNonStdMember(String name,
                               Object value)

Appends a non-standard member 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 members, such as the request processing time, to a JSON-RPC 2.0 message.

Parameters:

name - The member name. Must not conflict with the existing "method", "id", "params", "result", "error" and "jsonrpc" members reserved by the JSON-RPC 2.0 protocol, else an IllegalArgumentException will be thrown. Must not be null either.

value - The member value. Must be of type String, boolean, number, List, Map or null, else an IllegalArgumentException will be thrown.

appendNonStdAttribute

@Deprecated
public void appendNonStdAttribute(String name,
                                  Object value)

Deprecated.

Appends a non-standard member 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 members, such as the request processing time, to a JSON-RPC 2.0 message.

Parameters:

name - The member name. Must not conflict with the existing "method", "id", "params", "result", "error" and "jsonrpc" members reserved by the JSON-RPC 2.0 protocol, else an IllegalArgumentException will be thrown. Must not be null either.

value - The member value. Must be of type String, boolean, number, List, Map or null, else an IllegalArgumentException will be thrown.

getNonStdMember

public Object getNonStdMember(String name)

Gets a non-standard JSON-RPC 2.0 message member.

Parameters:

name - The name of the non-standard members to retrieve. Must not be null.

Returns:

The value of the non-standard members (may also be null), null if not found.

getNonStdAttribute

@Deprecated
public Object getNonStdAttribute(String name)

Deprecated.

Gets a non-standard JSON-RPC 2.0 message member.

Parameters:

name - The name of the non-standard members to retrieve. Must not be null.

Returns:

The value of the non-standard members (may also be null), null if not found.

getNonStdMembers

public Map<String,Object> getNonStdMembers()

Gets the non-standard JSON-RPC 2.0 message members.

Returns:

The non-standard members as a map, empty map if none.

getNonStdAttributes

@Deprecated
public Map<String,Object> getNonStdAttributes()

Deprecated.

Gets the non-standard JSON-RPC 2.0 message members.

Returns:

The non-standard members 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.