Package com.thetransactioncompany.jsonrpc2.client

Class JSONRPC2Session

  • public class JSONRPC2Session
extends java.lang.Object
    Sends requests and / or notifications to a specified JSON-RPC 2.0 server URL. The JSON-RPC 2.0 messages are dispatched by means of HTTP(S) POST. This class is thread-safe.

    The client-session class has a number of optional settings. To change them pass a modified options instance to the setOptions() method.

    Example JSON-RPC 2.0 client session: 

     // First, import the required packages:
 
 // The Client sessions package
 import com.thetransactioncompany.jsonrpc2.client.*;
 
 // The Base package for representing JSON-RPC 2.0 messages
 import com.thetransactioncompany.jsonrpc2.*;
 
 // The JSON Smart package for JSON encoding/decoding (optional)
 import net.minidev.json.*;
 
 // For creating URLs
 import java.net.*;
 
 // ...
 
 
 // Creating a new session to a JSON-RPC 2.0 web service at a specified URL
 
 // The JSON-RPC 2.0 server URL
 URL serverURL = null;
 
 try {
        serverURL = new URL("http://jsonrpc.example.com:8080");
        
 } catch (MalformedURLException e) {
        // handle exception...
 }
 
 // Create new JSON-RPC 2.0 client session
  JSONRPC2Session mySession = new JSONRPC2Session(serverURL);
 
 
 // Once the client session object is created, you can use to send a series
 // of JSON-RPC 2.0 requests and notifications to it.
 
 // Sending an example "getServerTime" request:
 
  // Construct new request
  String method = "getServerTime";
  int requestID = 0;
  JSONRPC2Request request = new JSONRPC2Request(method, requestID);
 
  // Send request
  JSONRPC2Response response = null;
 
  try {
          response = mySession.send(request);
 
  } catch (JSONRPC2SessionException e) {
 
          System.err.println(e.getMessage());
          // handle exception...
  }
 
  // Print response result / error
  if (response.indicatesSuccess())
        System.out.println(response.getResult());
  else
        System.out.println(response.getError().getMessage());
    Author:
    Vladimir Dzhuvinov, Mike Outland

    • Constructor Detail

      • JSONRPC2Session

        public JSONRPC2Session​(java.net.URL url)
        Creates a new client session to a JSON-RPC 2.0 server at the specified URL. Uses a default JSONRPC2SessionOptions instance.
        Parameters:
        url - The server URL, e.g. https://jsonrpc.example.com:8080 Must not be null.

    • Method Detail

      • createTrustAllSocketFactory

        public static javax.net.ssl.SSLSocketFactory createTrustAllSocketFactory()
        Creates a trust-all-certificates SSL socket factory. Encountered exceptions are not rethrown.
        Returns:
        The SSL socket factory.

      • getURL

        public java.net.URL getURL()
        Gets the JSON-RPC 2.0 server URL.
        Returns:
        The server URL.

      • setURL

        public void setURL​(java.net.URL url)
        Sets the JSON-RPC 2.0 server URL.
        Parameters:
        url - The server URL. Must not be null.

      • setOptions

        public void setOptions​(JSONRPC2SessionOptions options)
        Sets the JSON-RPC 2.0 client session options.
        Parameters:
        options - The client session options, must not be null.

      • setConnectionConfigurator

        public void setConnectionConfigurator​(ConnectionConfigurator connectionConfigurator)
        Specifies a custom HTTP URL connection configurator. It will be applied to each new HTTP connection after the session options are applied and before the connection is established.

        This method may be used to set custom HTTP request headers, timeouts or other properties.

        Parameters:
        connectionConfigurator - A custom HTTP URL connection configurator, null to remove a previously set one.
        Since:
        1.5

      • getRawResponseInspector

        public RawResponseInspector getRawResponseInspector()
        Gets the optional inspector for the raw HTTP responses.
        Returns:
        The optional inspector for the raw HTTP responses, null if none is set.
        Since:
        1.6

      • setRawResponseInspector

        public void setRawResponseInspector​(RawResponseInspector responseInspector)
        Specifies an optional inspector for the raw HTTP responses to JSON-RPC 2.0 requests and notifications. Its inspect method will be called upon reception of an HTTP response.

        You can use the RawResponseInspector interface to retrieve the non-parsed response content and headers.

        Parameters:
        responseInspector - An optional inspector for the raw HTTP responses, null to remove a previously set one.
        Since:
        1.6

      • getCookies

        public java.util.List<java.net.HttpCookie> getCookies()
        Gets all non-expired HTTP cookies currently stored in the client.
        Returns:
        The HTTP cookies, or empty list if none were set by the server or cookies are not accepted.

      • send

        public com.thetransactioncompany.jsonrpc2.JSONRPC2Response send​(com.thetransactioncompany.jsonrpc2.JSONRPC2Request request)
                                                         throws JSONRPC2SessionException
        Sends a JSON-RPC 2.0 request using HTTP POST and returns the server response.
        Parameters:
        request - The JSON-RPC 2.0 request to send. Must not be null.
        Returns:
        The JSON-RPC 2.0 response returned by the server.
        Throws:
        JSONRPC2SessionException - On a network error, unexpected HTTP response content type or invalid JSON-RPC 2.0 response.

      • send

        public void send​(com.thetransactioncompany.jsonrpc2.JSONRPC2Notification notification)
          throws JSONRPC2SessionException
        Sends a JSON-RPC 2.0 notification using HTTP POST. Note that contrary to requests, notifications produce no server response.
        Parameters:
        notification - The JSON-RPC 2.0 notification to send. Must not be null.
        Throws:
        JSONRPC2SessionException - On a network error.