Interface JsonRpcClient<T extends Type>

Type Parameters:

T - Type that can be used (in addition to Class) to declare expected result types for JSON-RPC method calls.

All Superinterfaces:

AsyncSupport, AutoCloseable, JsonRpcTransport<T>

All Known Implementing Classes:

BitcoinClient, BitcoinExtendedClient, DefaultRpcClient, RxBitcoinClient

public interface JsonRpcClient<T extends Type>
extends JsonRpcTransport<T>, AutoCloseable

JSON-RPC client interface. Implementations map JSON responses to JsonRpcResponse and JSON results to an expected Java type specified by either a Class or by type T. In the default implementation DefaultRpcClient, T is Jackson's JavaType.

This interface is independent of the JSON conversion library (e.g. Jackson) and is independent of the JsonRpcTransport. For historical reasons the interface is mostly synchronous, but AsyncSupport makes it easier to add use of CompletableFuture for special cases. In the future this interface may change to natively asynchronous.

Both JSON-RPC 1.0 and JSON-RPC 2.0 are supported. Implementations should also be (via configuration, perhaps) lenient enough to support Bitcoin Core and similar servers that don't follow the JSON-RPC specifications exactly.

See Also:

• JSON-RPC 1.0 Specification (2005)
• JSON-RPC 2.0 Specification

Nested Class Summary

Nested classes/interfaces inherited from interface AsyncSupport

AsyncSupport.ThrowingSupplier<T>, AsyncSupport.TransientErrorFilter

Method Summary

Modifier and Type	Method	Description
default JsonRpcRequest	buildJsonRequest(String method, Object... params)
default JsonRpcRequest	buildJsonRequest(String method, List<Object> params)	Create a JsonRpcRequest from method and parameters
default void	close()	Default no-op implementation of AutoCloseable.close().
T	collectionTypeForClasses(Class<? extends Collection> collectionClazz, Class<?> clazz)
T	collectionTypeForClasses(Class<? extends Collection> collectionClazz, T itemType)
T	defaultType()
JsonRpcMessage.Version	getJsonRpcVersion()	Return the JSON-RPC version used by the implementation
T	responseTypeFor(Class<?> resultType)
T	responseTypeFor(T resultType)
default <R> R	send(String method, Class<R> resultType, Object... params)
default <R> R	send(String method, Class<R> resultType, List<Object> params)	JSON-RPC remote method call that returns 'response.result`
default Object	send(String method, Object... params)	Call an RPC method and return default object type.
default Object	send(String method, List<Object> params)	Call an RPC method and return default object type.
default Object	send(String method, T resultType, Object... params)	Varargs version
default Object	send(String method, T resultType, List<Object> params)	JSON-RPC remote method call that returns response.result
default <R> CompletableFuture<R>	sendAsync(String method, Class<R> resultType, Object... params)
default <R> CompletableFuture<R>	sendAsync(String method, Class<R> resultType, List<Object> params)
default <R> CompletableFuture<R>	sendAsync(String method, List<Object> params)
default <R> CompletableFuture<R>	sendAsync(String method, T resultType, Object... params)
default <R> CompletableFuture<R>	sendAsync(String method, T resultType, List<Object> params)
T	typeForClass(Class<?> clazz)

Methods inherited from interface AsyncSupport

getDefaultAsyncExecutor, supplyAsync, supplyAsync

Methods inherited from interface JsonRpcTransport

getServerURI, sendRequestForResponse, sendRequestForResponseAsync, syncGet

Method Details

getJsonRpcVersion

JsonRpcMessage.Version getJsonRpcVersion()

Return the JSON-RPC version used by the implementation

Returns:

JSON-RPC version

send

default Object send(String method,
 List<Object> params)
             throws IOException,
JsonRpcStatusException

Call an RPC method and return default object type.

Caller should cast returned object to the correct type.

Useful for:

• Dynamically-dispatched JSON-RPC methods calls via Groovy subclasses
• Simple (not client-side validated) command line utilities
• Functional tests that need to send incorrect types to the server to test error handling

Parameters:

method - JSON RPC method call to send

params - JSON RPC parameters as a `List`

Returns:

the 'response.result' field of the JSON RPC response cast to type R

Throws:

IOException - network error

JsonRpcStatusException - JSON RPC status error

sendAsync

default <R> CompletableFuture<R> sendAsync(String method,
 List<Object> params)

send

default Object send(String method,
 Object... params)
             throws IOException,
JsonRpcStatusException

Call an RPC method and return default object type.

Convenience version that takes params as array/varargs.

Parameters:

method - JSON RPC method call to send

params - JSON RPC parameters as array or varargs

Returns:

the 'response.result' field of the JSON RPC response cast to type R

Throws:

IOException - network error

JsonRpcStatusException - JSON RPC status error

send

default <R> R send(String method,
 Class<R> resultType,
 Object... params)
            throws IOException,
JsonRpcStatusException

Throws:

IOException

JsonRpcStatusException

sendAsync

default <R> CompletableFuture<R> sendAsync(String method,
 Class<R> resultType,
 Object... params)

send

default <R> R send(String method,
 Class<R> resultType,
 List<Object> params)
            throws IOException,
JsonRpcStatusException

JSON-RPC remote method call that returns 'response.result`

Type Parameters:

R - Type of result object

Parameters:

method - JSON RPC method call to send

resultType - desired result type as a Java class object

params - JSON RPC params

Returns:

the 'response.result' field of the JSON RPC response converted to type R

Throws:

IOException

JsonRpcStatusException

sendAsync

default <R> CompletableFuture<R> sendAsync(String method,
 Class<R> resultType,
 List<Object> params)

sendAsync

default <R> CompletableFuture<R> sendAsync(String method,
 T resultType,
 List<Object> params)

send

default Object send(String method,
 T resultType,
 List<Object> params)
             throws IOException,
JsonRpcStatusException

JSON-RPC remote method call that returns response.result

Parameters:

method - JSON RPC method call to send

resultType - desired result type as a Jackson JavaType object

params - JSON RPC params

Returns:

the 'response.result' field of the JSON RPC response converted to type R

Throws:

IOException

JsonRpcStatusException

send

default Object send(String method,
 T resultType,
 Object... params)
             throws IOException,
JsonRpcStatusException

Varargs version

Throws:

IOException

JsonRpcStatusException

sendAsync

default <R> CompletableFuture<R> sendAsync(String method,
 T resultType,
 Object... params)

buildJsonRequest

default JsonRpcRequest buildJsonRequest(String method,
 List<Object> params)

Create a JsonRpcRequest from method and parameters

Parameters:

method - name of method to call

params - parameter Java objects

Returns:

A ready-to-send JsonRpcRequest

buildJsonRequest

default JsonRpcRequest buildJsonRequest(String method,
 Object... params)

close

default void close()

Default no-op implementation of AutoCloseable.close(). Subclasses can override if they have something they need to close properly.

Specified by:

close in interface AutoCloseable

defaultType

T defaultType()

responseTypeFor

T responseTypeFor(T resultType)

responseTypeFor

T responseTypeFor(Class<?> resultType)

typeForClass

T typeForClass(Class<?> clazz)

collectionTypeForClasses

T collectionTypeForClasses(Class<? extends Collection> collectionClazz,
 Class<?> clazz)

collectionTypeForClasses

T collectionTypeForClasses(Class<? extends Collection> collectionClazz,
 T itemType)