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

- - ### 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

    All Methods Instance Methods Concrete 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

    - #### 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`.

    - #### 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`.

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

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

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

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

    - #### 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`.

    - #### 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`.