com.thetransactioncompany.jsonrpc2.client
Class JSONRPC2Session

java.lang.Object
  com.thetransactioncompany.jsonrpc2.client.JSONRPC2Session

public class JSONRPC2Session
extends 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

Constructor Summary

JSONRPC2Session(URL url)
Creates a new client session to a JSON-RPC 2.0 server at the specified URL.

Method Summary

static SSLSocketFactory	createTrustAllSocketFactory() Creates a trust-all-certificates SSL socket factory.
ConnectionConfigurator	getConnectionConfigurator() Gets the custom HTTP URL connection configurator.
List<HttpCookie>	getCookies() Gets all non-expired HTTP cookies currently stored in the client.
JSONRPC2SessionOptions	getOptions() Gets the JSON-RPC 2.0 client session options.
RawResponseInspector	getRawResponseInspector() Gets the optional inspector for the raw HTTP responses.
URL	getURL() Gets the JSON-RPC 2.0 server URL.
void	send(com.thetransactioncompany.jsonrpc2.JSONRPC2Notification notification) Sends a JSON-RPC 2.0 notification using HTTP POST.
com.thetransactioncompany.jsonrpc2.JSONRPC2Response	send(com.thetransactioncompany.jsonrpc2.JSONRPC2Request request) Sends a JSON-RPC 2.0 request using HTTP POST and returns the server response.
void	setConnectionConfigurator(ConnectionConfigurator connectionConfigurator) Specifies a custom HTTP URL connection configurator.
void	setOptions(JSONRPC2SessionOptions options) Sets the JSON-RPC 2.0 client session options.
void	setRawResponseInspector(RawResponseInspector responseInspector) Specifies an optional inspector for the raw HTTP responses to JSON-RPC 2.0 requests and notifications.
void	setURL(URL url) Sets the JSON-RPC 2.0 server URL.

Methods inherited from class java.lang.Object

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

Constructor Detail

JSONRPC2Session

public JSONRPC2Session(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. "http://jsonrpc.example.com:8080". Must not be null.

Method Detail

createTrustAllSocketFactory

public static SSLSocketFactory createTrustAllSocketFactory()

Creates a trust-all-certificates SSL socket factory. Encountered exceptions are not rethrown.

Returns:

The SSL socket factory.

getURL

public URL getURL()

Gets the JSON-RPC 2.0 server URL.

Returns:

The server URL.

setURL

public void setURL(URL url)

Sets the JSON-RPC 2.0 server URL.

Parameters:

url - The server URL. Must not be null.

getOptions

public JSONRPC2SessionOptions getOptions()

Gets the JSON-RPC 2.0 client session options.

Returns:

The client session options.

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.

getConnectionConfigurator

public ConnectionConfigurator getConnectionConfigurator()

Gets the custom HTTP URL connection configurator.

Returns:

The connection configurator, null if none is set.

Since:

1.5

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 a HTTP response.

You can use the RawResponseInspector interface to retrieve the unparsed 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 List<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.