Package org.consensusj.jsonrpc

Interface JsonRpcClient<T extends Type>

All Superinterfaces:

AsyncSupport, AutoCloseable, JsonRpcTransport<T>

All Known Implementing Classes:

BitcoinClient, BitcoinExtendedClient, DefaultRpcClient, EthereumClient, NamecoinClient, RxBitcoinClient

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

JSON-RPC client interface. This interface is independent of the JSON conversion library (the default implementation uses Jackson) and HTTP client library (currently HttpURLConnection). 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 org.consensusj.jsonrpc.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 <R> R	send(String method, Object... params)	Call an RPC method and return default object type.
default <R> R	send(String method, List<Object> params)	Call an RPC method and return default object type.
default <R> R	send(String method, T resultType, Object... params)	Varargs version
default <R> R	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 org.consensusj.jsonrpc.AsyncSupport

getDefaultAsyncExecutor, supplyAsync, supplyAsync

Methods inherited from interface org.consensusj.jsonrpc.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 <R> R 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

Type Parameters:

R - Type of result object

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 <R> R 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.

Type Parameters:

R - Type of result object

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 <R> R send(String method,
 T 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 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 <R> R 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()
            throws Exception

Default no-op implementation of AutoCloseable.close(). Classes should override when they have something they need to close properly.

Specified by:

close in interface AutoCloseable

Throws:

IOException - if something happens during close

Exception

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)