java.lang.Object
com.thetransactioncompany.jsonrpc2.JSONRPC2Parser
public class JSONRPC2Parserextends 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(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

  • Field Details

    • preserveOrder

      private boolean preserveOrder
      If true the order of the parsed JSON object members must be preserved.

    • ignoreVersion

      private boolean ignoreVersion
      If true the "jsonrpc":"2.0" version attribute in the JSON-RPC 2.0 message must be ignored during parsing.

    • parseNonStdAttributes

      private boolean parseNonStdAttributes
      If true non-standard JSON-RPC 2.0 message attributes must be parsed too.

  • Constructor Details

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

    • parseJSONObject

      private Map<String,Object> parseJSONObject(String jsonString) throws JSONRPC2ParseException
      Parses a JSON object string. Provides the initial parsing of JSON-RPC 2.0 messages. The member order of JSON objects will be preserved if preserveOrder is set to true.
      Parameters:
      jsonString - The JSON string to parse. Must not be null.
      Returns:
      The parsed JSON object.
      Throws:
      JSONRPC2ParseException - With detailed message if parsing failed.

    • ensureVersion2

      private static void ensureVersion2(Object version, String jsonString) throws JSONRPC2ParseException
      Ensures the specified parameter is a String object set to "2.0". This method is intended to check the "jsonrpc" attribute during parsing of JSON-RPC messages.
      Parameters:
      version - The version parameter. Must not be null.
      jsonString - The original JSON string.
      Throws:
      JSONRPC2ParseException - If the parameter is not a string that equals "2.0".

    • 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(String), parseJSONRPC2Notification(String) and parseJSONRPC2Response(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.