com.thetransactioncompany.jsonrpc2

Class JSONRPC2Parser

java.lang.Object

com.thetransactioncompany.jsonrpc2.JSONRPC2Parser

public class JSONRPC2Parser
extends Object

Parses JSON-RPC 2.0 request, notification and response messages.

Parsing of batched requests / notifications is not supported.

This class is not thread-safe. A parser instance should not be used by more than one thread unless properly synchronised. Alternatively, you may use the thread-safe JSONRPC2Message.parse(java.lang.String) and its sister methods.

Example:

 String jsonString = "{\"method\":\"makePayment\"," +
                      "\"params\":{\"recipient\":\"Penny Adams\",\"amount\":175.05}," +
                      "\"id\":\"0001\","+
                      "\"jsonrpc\":\"2.0\"}";
  
  JSONRPC2Request req = null;

 JSONRPC2Parser parser = new JSONRPC2Parser();
  
  try {
          req = parser.parseJSONRPC2Request(jsonString);
 
  } catch (JSONRPC2ParseException e) {
          // handle exception
  }

 

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

Constructors

Constructor and Description
JSONRPC2Parser() Creates a new JSON-RPC 2.0 message parser.
JSONRPC2Parser(boolean preserveOrder) Creates a new JSON-RPC 2.0 message parser.
JSONRPC2Parser(boolean preserveOrder, boolean ignoreVersion) Creates a new JSON-RPC 2.0 message parser.
JSONRPC2Parser(boolean preserveOrder, boolean ignoreVersion, boolean parseNonStdAttributes) Creates a new JSON-RPC 2.0 message parser.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	ignoresVersion() Returns true if the "jsonrpc":"2.0" version attribute in parsed JSON-RPC 2.0 messages is ignored, else false.
void	ignoreVersion(boolean ignore) Specifies whether to ignore the "jsonrpc":"2.0" version attribute during parsing of JSON-RPC 2.0 messages.
JSONRPC2Message	parseJSONRPC2Message(String jsonString) Provides common parsing of JSON-RPC 2.0 requests, notifications and responses.
JSONRPC2Notification	parseJSONRPC2Notification(String jsonString) Parses a JSON-RPC 2.0 notification string.
JSONRPC2Request	parseJSONRPC2Request(String jsonString) Parses a JSON-RPC 2.0 request string.
JSONRPC2Response	parseJSONRPC2Response(String jsonString) Parses a JSON-RPC 2.0 response string.
void	parseNonStdAttributes(boolean enable) Specifies whether to parse non-standard attributes found in JSON-RPC 2.0 messages.
boolean	parsesNonStdAttributes() Returns true if non-standard attributes in JSON-RPC 2.0 messages are parsed.
void	preserveOrder(boolean preserveOrder) Controls the preservation of JSON object member order in parsed JSON-RPC 2.0 messages.
boolean	preservesOrder() Returns true if the order of JSON object members in parsed JSON-RPC 2.0 messages is preserved, else false.

Methods inherited from class java.lang.Object

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

Constructor Detail

JSONRPC2Parser

public JSONRPC2Parser()

Creates a new JSON-RPC 2.0 message parser.

The member order of parsed JSON objects in parameters and results will not be preserved; strict checking of the 2.0 JSON-RPC version attribute will be enforced; non-standard message attributes will be ignored. Check the other constructors if you want to specify different behaviour.

JSONRPC2Parser

public JSONRPC2Parser(boolean preserveOrder)

Creates a new JSON-RPC 2.0 message parser.

Strict checking of the 2.0 JSON-RPC version attribute will be enforced; non-standard message attributes will be ignored. Check the other constructors if you want to specify different behaviour.

Parameters:

preserveOrder - If true the member order of JSON objects in parameters and results will be preserved.

JSONRPC2Parser

public JSONRPC2Parser(boolean preserveOrder,
              boolean ignoreVersion)

Creates a new JSON-RPC 2.0 message parser.

Non-standard message attributes will be ignored. Check the other constructors if you want to specify different behaviour.

Parameters:

preserveOrder - If true the member order of JSON objects in parameters and results will be preserved.

ignoreVersion - If true the "jsonrpc":"2.0" version attribute in the JSON-RPC 2.0 message will not be checked.

JSONRPC2Parser

public JSONRPC2Parser(boolean preserveOrder,
              boolean ignoreVersion,
              boolean parseNonStdAttributes)

Creates a new JSON-RPC 2.0 message parser.

This constructor allows full specification of the available JSON-RPC message parsing properties.

Parameters:

preserveOrder - If true the member order of JSON objects in parameters and results will be preserved.

ignoreVersion - If true the "jsonrpc":"2.0" version attribute in the JSON-RPC 2.0 message will not be checked.

parseNonStdAttributes - If true non-standard attributes found in the JSON-RPC 2.0 messages will be parsed too.

Method Detail

parseJSONRPC2Message

public JSONRPC2Message parseJSONRPC2Message(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 string represents.

If a particular message type is expected use the dedicated parseJSONRPC2Request(java.lang.String), parseJSONRPC2Notification(java.lang.String) and parseJSONRPC2Response(java.lang.String) methods. They are more efficient and would provide you with 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 the parsing failed.

parseJSONRPC2Request

public JSONRPC2Request parseJSONRPC2Request(String jsonString)
                                     throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 request string.

Parameters:

jsonString - The JSON-RPC 2.0 request string, UTF-8 encoded. Must not be null.

Returns:

The corresponding JSON-RPC 2.0 request object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

parseJSONRPC2Notification

public JSONRPC2Notification parseJSONRPC2Notification(String jsonString)
                                               throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 notification string.

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.

parseJSONRPC2Response

public JSONRPC2Response parseJSONRPC2Response(String jsonString)
                                       throws JSONRPC2ParseException

Parses a JSON-RPC 2.0 response string.

Parameters:

jsonString - The JSON-RPC 2.0 response string, UTF-8 encoded. Must not be null.

Returns:

The corresponding JSON-RPC 2.0 response object.

Throws:

JSONRPC2ParseException - With detailed message if parsing failed.

preserveOrder

public void preserveOrder(boolean preserveOrder)

Controls the preservation of JSON object member order in parsed JSON-RPC 2.0 messages.

Parameters:

preserveOrder - true to preserve the order of JSON object members, else false.

preservesOrder

public boolean preservesOrder()

Returns true if the order of JSON object members in parsed JSON-RPC 2.0 messages is preserved, else false.

Returns:

true if order is preserved, else false.

ignoreVersion

public void ignoreVersion(boolean ignore)

Specifies whether to ignore the "jsonrpc":"2.0" version attribute during parsing of JSON-RPC 2.0 messages.

You may with to disable strict 2.0 version checking if the parsed JSON-RPC 2.0 messages don't include a version attribute or if you wish to achieve limited compatibility with older JSON-RPC protocol versions.

Parameters:

ignore - true to skip checks of the "jsonrpc":"2.0" version attribute in parsed JSON-RPC 2.0 messages, else false.

ignoresVersion

public boolean ignoresVersion()

Returns true if the "jsonrpc":"2.0" version attribute in parsed JSON-RPC 2.0 messages is ignored, else false.

Returns:

true if the "jsonrpc":"2.0" version attribute in parsed JSON-RPC 2.0 messages is ignored, else false.

parseNonStdAttributes

public void parseNonStdAttributes(boolean enable)

Specifies whether to parse non-standard attributes found in JSON-RPC 2.0 messages.

Parameters:

enable - true to parse non-standard attributes, else false.

parsesNonStdAttributes

public boolean parsesNonStdAttributes()

Returns true if non-standard attributes in JSON-RPC 2.0 messages are parsed.

Returns:

true if non-standard attributes are parsed, else false.