JSONRPC2SessionOptions (JSON-RPC 2.0 Client)

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.thetransactioncompany.jsonrpc2.client
Class JSONRPC2SessionOptions

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

public class JSONRPC2SessionOptions
extends java.lang.Object
extends java.lang.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.
Trust all X.509 server certificates (for HTTPS connections), including self-signed.

Since:: 1.4
Version:: 1.7 (2011-08-23)
Author:: Vladimir Dzhuvinov

Field Summary
`static boolean`	`DEFAULT_ACCEPT_COOKIES` The default HTTP cookie acceptance policy.
`static java.lang.String[]`	`DEFAULT_ALLOWED_RESPONSE_CONTENT_TYPES` The default allowed "Content-Type" (MIME) header values of HTTP responses.
`static java.lang.String`	`DEFAULT_CONTENT_TYPE` The default "Content-Type" (MIME) header value of HTTP POST requests.
`static boolean`	`DEFAULT_IGNORE_VERSION` The default policy for version 2.0 checking.
`static java.lang.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 boolean`	`DEFAULT_TRUST_ALL` The default policy for trusting self-signed certificates.

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

Method Summary
`void`	`acceptCookies(boolean acceptCookies)` Specifies whether to accept HTTP cookies contained in the server response.
`boolean`	`acceptsCookies()` Returns `true` if HTTP cookies are accepted, else `false` if they are ignored.
`java.lang.String[]`	`getAllowedResponseContentTypes()` Gets the allowed "Content-Type" (MIME) header values of HTTP responses.
`java.lang.String`	`getOrigin()` Gets the value of the "Origin" HTTP header.
`java.lang.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(java.lang.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(java.lang.String[] contentTypes)` Sets the allowed "Content-Type" (MIME) header values of HTTP responses.
`void`	`setOrigin(java.lang.String origin)` Sets the value of the "Origin" HTTP header.
`void`	`setRequestContentType(java.lang.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 java.lang.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 java.lang.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 java.lang.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_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).

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 java.lang.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(java.lang.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 java.lang.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(java.lang.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.

acceptsCookies

public boolean acceptsCookies()

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 java.lang.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(java.lang.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(java.lang.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.

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.