com.thetransactioncompany.jsonrpc2.client

Class JSONRPC2SessionOptions

java.lang.Object

com.thetransactioncompany.jsonrpc2.client.JSONRPC2SessionOptions

public class JSONRPC2SessionOptions
extends Object

Optional settings for JSON-RPC 2.0 client sessions. The no-argument constructor specifies the default settings that the JSONRPC2Session uses. To apply different ones instantiate a new settings instance, set the desired ones to your liking, and then pass it to your JSONRPC2Session instance.

Overview of the available session options:

• Customise the "Content-Type" header in HTTP POST requests.
• Set an "Origin" header in HTTP POST requests to simulate Cross-Origin Resource Sharing (CORS) requests from a browser.
• Accept HTTP cookies (if client sessions are established by this mean instead of through the JSON-RPC protocol itself).
• Customise the allowable "Content-Type" header values in HTTP POST responses.
• Preserve parse order of JSON object members in JSON-RPC 2.0 response results (for human-facing clients, e.g. the JSON-RPC 2.0 Shell).
• Ignore version 2.0 checks when parsing responses to allow client sessions to older JSON-RPC (1.0) servers.
• Parse non-standard attributes in JSON-RPC 2.0 responses.
• Set an HTTP connect timeout.
• Set an HTTP read timeout.
• Set an HTTP proxy.
• Enable HTTP response compression (using GZIP or DEFLATE content encoding).
• Trust all X.509 server certificates (for HTTPS connections), including self-signed.

Since:

1.4

Author:

Vladimir Dzhuvinov

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEFAULT_ACCEPT_COOKIES The default HTTP cookie acceptance policy.
static String[]	DEFAULT_ALLOWED_RESPONSE_CONTENT_TYPES The default allowed "Content-Type" (MIME) header values of HTTP responses.
static int	DEFAULT_CONNECT_TIMEOUT The default HTTP connect timeout.
static String	DEFAULT_CONTENT_TYPE The default "Content-Type" (MIME) header value of HTTP POST requests.
static boolean	DEFAULT_ENABLE_COMPRESSION The default HTTP GZIP and DEFLATE compression enable policy.
static boolean	DEFAULT_IGNORE_VERSION The default policy for version 2.0 checking.
static String	DEFAULT_ORIGIN The default CORS "Origin" header value.
static boolean	DEFAULT_PARSE_NON_STD_ATTRIBUTES The default policy for parsing non-standard attributes in JSON-RPC 2.0 messages.
static boolean	DEFAULT_PRESERVE_OBJECT_MEMBER_ORDER The default policy for preserving the order of parsed JSON object members.
static int	DEFAULT_READ_TIMEOUT The default HTTP read timeout.
static boolean	DEFAULT_TRUST_ALL The default policy for trusting self-signed certificates.

Constructor Summary

Constructors

Constructor and Description
JSONRPC2SessionOptions() Creates a new default JSON-RPC 2.0 client session options instance.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	acceptCookies() Returns true if HTTP cookies are accepted, else false if they are ignored.
void	acceptCookies(boolean acceptCookies) Specifies whether to accept HTTP cookies contained in the server response.
boolean	enableCompression() Checks if HTTP response compression using GZIP or DEFLATE content encoding is enabled or disabled.
void	enableCompression(boolean enable) Enables or disables HTTP response compression using GZIP or DEFLATE content encoding.
String[]	getAllowedResponseContentTypes() Gets the allowed "Content-Type" (MIME) header values of HTTP responses.
int	getConnectTimeout() Gets the HTTP connect timeout.
String	getOrigin() Gets the value of the "Origin" HTTP header.
Proxy	getProxy() Gets the HTTP proxy.
int	getReadTimeout() Gets the HTTP read timeout.
String	getRequestContentType() Gets the value of the "Content-Type" (MIME) header for HTTP POST requests.
boolean	ignoresVersion() Returns true if strict parsing of received JSON-RPC 2.0 responses is disabled and the "jsonrpc" version attribute is not checked for "2.0" equality.
void	ignoreVersion(boolean ignore) Controls the strictness of the JSON-RPC 2.0 response parser.
boolean	isAllowedResponseContentType(String contentType) Checks if the specified HTTP "Content-Type" (MIME) header value is allowed.
void	parseNonStdAttributes(boolean enable) Specifies whether to parse non-standard attributes found in JSON-RPC 2.0 responses.
boolean	parsesNonStdAttributes() Returns true if non-standard attributes in JSON-RPC 2.0 responses are parsed.
void	preserveParseOrder(boolean preserve) Controls the behaviour of the JSON parser when processing object members in JSON-RPC 2.0 response results.
boolean	preservesParseOrder() Returns true if the member order of parsed JSON objects in JSON-RPC 2.0 response results is preserved.
void	setAllowedResponseContentTypes(String[] contentTypes) Sets the allowed "Content-Type" (MIME) header values of HTTP responses.
void	setConnectTimeout(int timeout) Sets the HTTP connect timeout.
void	setOrigin(String origin) Sets the value of the "Origin" HTTP header.
void	setProxy(Proxy proxy) Sets an HTTP proxy.
void	setReadTimeout(int timeout) Sets the HTTP read timeout.
void	setRequestContentType(String contentType) Sets the value of the HTTP "Content-Type" (MIME) header.
void	trustAllCerts(boolean trustAll) Controls checking of X.509 certificates presented by the server when establishing a secure HTTPS connection.
boolean	trustsAllCerts() Returns true if all X.509 certificates presented by the web server will be trusted, including self-signed ones.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CONTENT_TYPE

public static final String DEFAULT_CONTENT_TYPE

The default "Content-Type" (MIME) header value of HTTP POST requests. Set to application/json.

See Also:

Constant Field Values

DEFAULT_ALLOWED_RESPONSE_CONTENT_TYPES

public static final String[] DEFAULT_ALLOWED_RESPONSE_CONTENT_TYPES

The default allowed "Content-Type" (MIME) header values of HTTP responses. Set to application/json and text/plain.

DEFAULT_ORIGIN

public static final String DEFAULT_ORIGIN

The default CORS "Origin" header value. Set to null (none).

DEFAULT_ACCEPT_COOKIES

public static final boolean DEFAULT_ACCEPT_COOKIES

The default HTTP cookie acceptance policy.

See Also:

Constant Field Values

DEFAULT_PRESERVE_OBJECT_MEMBER_ORDER

public static final boolean DEFAULT_PRESERVE_OBJECT_MEMBER_ORDER

The default policy for preserving the order of parsed JSON object members. Set to false (no preserve).

See Also:

Constant Field Values

DEFAULT_IGNORE_VERSION

public static final boolean DEFAULT_IGNORE_VERSION

The default policy for version 2.0 checking. Set to false (strict checking).

See Also:

Constant Field Values

DEFAULT_PARSE_NON_STD_ATTRIBUTES

public static final boolean DEFAULT_PARSE_NON_STD_ATTRIBUTES

The default policy for parsing non-standard attributes in JSON-RPC 2.0 messages. Set to false (non-standard attributes ignored).

See Also:

Constant Field Values

DEFAULT_CONNECT_TIMEOUT

public static final int DEFAULT_CONNECT_TIMEOUT

The default HTTP connect timeout. Set to zero (disabled).

See Also:

Constant Field Values

DEFAULT_READ_TIMEOUT

public static final int DEFAULT_READ_TIMEOUT

The default HTTP read timeout. Set to zero (disabled).

See Also:

Constant Field Values

DEFAULT_ENABLE_COMPRESSION

public static final boolean DEFAULT_ENABLE_COMPRESSION

The default HTTP GZIP and DEFLATE compression enable policy.

See Also:

Constant Field Values

DEFAULT_TRUST_ALL

public static final boolean DEFAULT_TRUST_ALL

The default policy for trusting self-signed certificates. Set to false (self-signed certificates not accepted).

See Also:

Constant Field Values

Constructor Detail

JSONRPC2SessionOptions

public JSONRPC2SessionOptions()

Creates a new default JSON-RPC 2.0 client session options instance.

The "Content-Type" (MIME) header value of HTTP POST requests will be set to "application/json". To change it use setRequestContentType(java.lang.String).

"Origin" HTTP headers will not be added. To add one use setOrigin(java.lang.String).

HTTP cookies will be ignored. To accept cookies, e.g. for browser-like session handling, use acceptCookies.

The allowed HTTP response content types are set to "application/json" and "text/plain". To change them use setAllowedResponseContentTypes(java.lang.String[]).

The parse order of JSON object members in JSON-RPC 2.0 response results will not be preserved. To change this behaviour use preserveParseOrder(boolean).

Strict 2.0 version checking will be performed. To ignore the JSON-RPC version attribute use ignoreVersion(boolean).

HTTP connect timeouts will be disabled. To specify a value use setConnectTimeout(int).

HTTP read timeouts will be disabled. To specify a value use setReadTimeout(int).

No proxy is used. To specify one use setProxy(java.net.Proxy).

HTTP response compression (GZIP or DEFLATE) is disabled. To enable it use enableCompression(boolean).

Self-signed X.509 certificates presented by the JSON-RPC 2.0 server will not be accepted. To relax certificate cheking use trustAllCerts(boolean).

Method Detail

getRequestContentType

public String getRequestContentType()

Gets the value of the "Content-Type" (MIME) header for HTTP POST requests.

Returns:

The "Content-Type" (MIME) header value, null if the header is not added to HTTP POST requests.

setRequestContentType

public void setRequestContentType(String contentType)

Sets the value of the HTTP "Content-Type" (MIME) header. Use this method if you wish to change the default "application/json" content type.

Parameters:

contentType - The value of the "Content-Type" (MIME) header in HTTP POST requests, null to suppress the header.

getOrigin

public String getOrigin()

Gets the value of the "Origin" HTTP header.

This header can be used to simulate Cross-Origin Resource Sharing (CORS) requests from a browser.

Returns:

The "Origin" header value, null if the header is not added to HTTP requests.

setOrigin

public void setOrigin(String origin)

Sets the value of the "Origin" HTTP header.

This header can be used to simulate Cross-Origin Resource Sharing (CORS) requests from a browser.

Parameters:

origin - The value of the "Origin" header in HTTP requests, null to suppress the header.

acceptCookies

public boolean acceptCookies()

Returns true if HTTP cookies are accepted, else false if they are ignored.

Returns:

true if HTTP cookies are accepted, else false.

acceptCookies

public void acceptCookies(boolean acceptCookies)

Specifies whether to accept HTTP cookies contained in the server response. Some JSON-RPC servers may use cookies instead of tokens passed through the JSON-RPC protocol itself to establish client sessions.

Parameters:

acceptCookies - true to accept HTTP cookies, else false to ignore them.

getAllowedResponseContentTypes

public String[] getAllowedResponseContentTypes()

Gets the allowed "Content-Type" (MIME) header values of HTTP responses.

The JSONRPC2Session.send(...) method will throw a JSONRPC2SessionException.UNEXPECTED_CONTENT_TYPE if the received HTTP response "Content-Type" (MIME) header value is not allowed.

Returns:

The allowed header values, if null any header value is allowed.

setAllowedResponseContentTypes

public void setAllowedResponseContentTypes(String[] contentTypes)

Sets the allowed "Content-Type" (MIME) header values of HTTP responses.

The JSONRPC2Session.send(...) method will throw a JSONRPC2SessionException.UNEXPECTED_CONTENT_TYPE if the received HTTP response "Content-Type" (MIME) header value is not allowed.

Parameters:

contentTypes - The allowed header values, null to allow any header value.

isAllowedResponseContentType

public boolean isAllowedResponseContentType(String contentType)

Checks if the specified HTTP "Content-Type" (MIME) header value is allowed.

Parameters:

contentType - The "Content-Type" (MIME) header value.

Returns:

true if the content type is allowed, else false.

preservesParseOrder

public boolean preservesParseOrder()

Returns true if the member order of parsed JSON objects in JSON-RPC 2.0 response results is preserved.

Returns:

true if the parse order of JSON object members is preserved, else false.

preserveParseOrder

public void preserveParseOrder(boolean preserve)

Controls the behaviour of the JSON parser when processing object members in JSON-RPC 2.0 response results. The default behaviour is to store the members in a java.util.HashMap in a non-deterministic order. To preserve the original parse order pass a boolean true to this method. Note that this will slow down parsing and retrieval performance somewhat.

Parameters:

preserve - If true the parse order of JSON object members will be preserved, else not.

ignoresVersion

public boolean ignoresVersion()

Returns true if strict parsing of received JSON-RPC 2.0 responses is disabled and the "jsonrpc" version attribute is not checked for "2.0" equality. Returns false if received JSON-RPC 2.0 responses must strictly conform to the JSON-RPC 2.0 specification.

Returns:

true if the "jsonrpc":"2.0" version attribute is ignored, false if parsing is strict.

ignoreVersion

public void ignoreVersion(boolean ignore)

Controls the strictness of the JSON-RPC 2.0 response parser. The default behaviour is to check responses for strict compliance to the JSON-RPC 2.0 specification. By passing a boolean true parsing is relaxed and the "jsonrpc" version attribute will not be checked for "2.0" equality.

Parameters:

ignore - true to ignore the 2.0 "jsonrpc":"2.0" version attribute, false for strict parsing.

parseNonStdAttributes

public void parseNonStdAttributes(boolean enable)

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

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 responses are parsed.

Returns:

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

setConnectTimeout

public void setConnectTimeout(int timeout)

Sets the HTTP connect timeout.

Parameters:

timeout - The HTTP connect timeout, in milliseconds. Zero implies the option is disabled (timeout of infinity).

Since:

1.8

getConnectTimeout

public int getConnectTimeout()

Gets the HTTP connect timeout.

Returns:

The HTTP connect timeout, in milliseconds. Zero implies the option is disabled (timeout of infinity).

Since:

1.8

setReadTimeout

public void setReadTimeout(int timeout)

Sets the HTTP read timeout.

Parameters:

timeout - The HTTP read timeout, in milliseconds. Zero implies the option is disabled (timeout of infinity).

Since:

1.8

getReadTimeout

public int getReadTimeout()

Gets the HTTP read timeout.

Returns:

The HTTP read timeout, in milliseconds. Zero implies the option is disabled (timeout of infinity).

Since:

1.8

setProxy

public void setProxy(Proxy proxy)

Sets an HTTP proxy.

Parameters:

proxy - The HTTP proxy to use, null if none.

Since:

1.10

getProxy

public Proxy getProxy()

Gets the HTTP proxy.

Returns:

The HTTP proxy to use, null if none.

Since:

1.10

enableCompression

public void enableCompression(boolean enable)

Enables or disables HTTP response compression using GZIP or DEFLATE content encoding. If compression is enabled but the HTTP server doesn't support compression this setting will have no effect.

Parameters:

enable - If true HTTP compression will be enabled, else compression will be disabled.

enableCompression

public boolean enableCompression()

Checks if HTTP response compression using GZIP or DEFLATE content encoding is enabled or disabled. If compression is enabled but the HTTP server doesn't support compression this setting will have no effect.

Returns:

true if HTTP compression is enabled, else false.

trustAllCerts

public void trustAllCerts(boolean trustAll)

Controls checking of X.509 certificates presented by the server when establishing a secure HTTPS connection. The default behaviour is to accept only certicates issued by a trusted certificate authority (CA), as determined by the default Java trust store. By passing a boolean false this security check is disabled and all certificates will be trusted, including self-signed ones. Use this for testing and development purposes only.

Parameters:

trustAll - If true all X.509 certificates presented by the web server will be trusted, including self-signed ones. If false the default security policy will be restored.

trustsAllCerts

public boolean trustsAllCerts()

Returns true if all X.509 certificates presented by the web server will be trusted, including self-signed ones. If false the default security policy applies.

Returns:

true if all X.509 certificates are trusted, else false.