com.rabbitmq.tools.jsonrpc

Class JsonRpcClient

java.lang.Object

com.rabbitmq.client.RpcClient

com.rabbitmq.tools.jsonrpc.JsonRpcClient

All Implemented Interfaces:

AutoCloseable, InvocationHandler

public class JsonRpcClient
extends RpcClient
implements InvocationHandler

JSON-RPC is a lightweight RPC mechanism using JSON as a data language for request and reply messages. It is rapidly becoming a standard in web development, where it is used to make RPC requests over HTTP. RabbitMQ provides an AMQP transport binding for JSON-RPC in the form of the JsonRpcClient class.

JSON-RPC services are self-describing - each service is able to list its supported procedures, and each procedure describes its parameters and types. An instance of JsonRpcClient retrieves its service description using the standard system.describe procedure when it is constructed, and uses the information to coerce parameter types appropriately. A JSON service description is parsed into instances of ServiceDescription. Client code can access the service description by reading the serviceDescription field of JsonRpcClient instances.

JsonRpcClient delegates JSON parsing and generating to a JsonRpcMapper.

By default only a safe set of return types is accepted from the remote service description (primitives, String, Map, List, and common boxed types). Services that return custom types must pass an explicit allowlist via the constructors that accept allowedReturnTypes.

See Also:

call(String, Object[]), JsonRpcMapper, JacksonJsonRpcMapper

Nested Class Summary

Nested classes/interfaces inherited from class com.rabbitmq.client.RpcClient

RpcClient.Response

Field Summary

Fields inherited from class com.rabbitmq.client.RpcClient

DEFAULT_REPLY_HANDLER, NO_TIMEOUT

Constructor Summary

Constructors

Constructor and Description
JsonRpcClient(Channel channel, String exchange, String routingKey)
JsonRpcClient(Channel channel, String exchange, String routingKey, int timeout) Construct a new JsonRpcClient using the safe default return-type allowlist.
JsonRpcClient(Channel channel, String exchange, String routingKey, int timeout, JsonRpcMapper mapper) Construct a new JsonRpcClient using the safe default return-type allowlist.
JsonRpcClient(Channel channel, String exchange, String routingKey, int timeout, JsonRpcMapper mapper, Set<Class<?>> allowedReturnTypes) Construct a new JsonRpcClient with an explicit allowlist of permitted return types.
JsonRpcClient(RpcClientParams rpcClientParams, JsonRpcMapper mapper) Construct a new JsonRpcClient that only accepts return types from the built-in safe set (primitives, String, Map, List, common boxed types).
JsonRpcClient(RpcClientParams rpcClientParams, JsonRpcMapper mapper, Set<Class<?>> allowedReturnTypes) Construct a new JsonRpcClient with an explicit allowlist of permitted return types.

Method Summary

Modifier and Type	Method and Description
Object	call(String[] args) Deprecated. This method will be removed in the next major version
Object	call(String method, Object[] params) Public API - builds, encodes and sends a JSON-RPC request, and waits for the response.
static Object	coerce(String val, String type) Deprecated. This method will be removed in the next major version
<T> T	createProxy(Class<T> klass) Public API - gets a dynamic proxy for a particular interface class.
ServiceDescription	getServiceDescription() Public API - gets the service description record that this service loaded from the server itself at construction time.
Object	invoke(Object proxy, Method method, Object[] args) Public API - implements InvocationHandler.invoke.

Methods inherited from class com.rabbitmq.client.RpcClient

close, doCall, doCall, getChannel, getConsumer, getContinuationMap, getCorrelationId, getExchange, getRoutingKey, incrementingCorrelationIdSupplier, incrementingCorrelationIdSupplier, mapCall, mapCall, primitiveCall, primitiveCall, primitiveCall, publish, responseCall, responseCall, setupConsumer, stringCall

Methods inherited from class java.lang.Object

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

Constructor Detail

JsonRpcClient

public JsonRpcClient(RpcClientParams rpcClientParams,
                     JsonRpcMapper mapper)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Construct a new JsonRpcClient that only accepts return types from the built-in safe set (primitives, String, Map, List, common boxed types).

Services that declare custom return types will cause construction to fail with an IllegalStateException. Use JsonRpcClient(RpcClientParams, JsonRpcMapper, Set) to allow additional types.

Throws:

IllegalStateException - if the service description contains a return type not in the allowlist

IOException

JsonRpcException

TimeoutException

JsonRpcClient

public JsonRpcClient(RpcClientParams rpcClientParams,
                     JsonRpcMapper mapper,
                     Set<Class<?>> allowedReturnTypes)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Construct a new JsonRpcClient with an explicit allowlist of permitted return types.

The provided types are merged with the built-in safe set, so common types (String, Map, primitives, etc.) do not need to be listed explicitly.

Parameters:

allowedReturnTypes - additional return types to accept from the remote service description, on top of the built-in safe set

Throws:

IllegalStateException - if the service description contains a return type not in the allowlist

IOException

JsonRpcException

TimeoutException

JsonRpcClient

public JsonRpcClient(Channel channel,
                     String exchange,
                     String routingKey,
                     int timeout,
                     JsonRpcMapper mapper)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Construct a new JsonRpcClient using the safe default return-type allowlist.

Throws:

TimeoutException - if a response is not received within the timeout specified, if any

IllegalStateException - if the service description contains a return type not in the allowlist

IOException

JsonRpcException

JsonRpcClient

public JsonRpcClient(Channel channel,
                     String exchange,
                     String routingKey,
                     int timeout,
                     JsonRpcMapper mapper,
                     Set<Class<?>> allowedReturnTypes)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Construct a new JsonRpcClient with an explicit allowlist of permitted return types.

Parameters:

allowedReturnTypes - additional return types to accept from the remote service description, on top of the built-in safe set

Throws:

TimeoutException - if a response is not received within the timeout specified, if any

IllegalStateException - if the service description contains a return type not in the allowlist

IOException

JsonRpcException

JsonRpcClient

public JsonRpcClient(Channel channel,
                     String exchange,
                     String routingKey,
                     int timeout)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Construct a new JsonRpcClient using the safe default return-type allowlist.

Throws:

TimeoutException - if a response is not received within the timeout specified, if any

IOException

JsonRpcException

JsonRpcClient

public JsonRpcClient(Channel channel,
                     String exchange,
                     String routingKey)
              throws IOException,
                     JsonRpcException,
                     TimeoutException

Throws:

IOException

JsonRpcException

TimeoutException

Method Detail

coerce

@Deprecated
public static Object coerce(String val,
                                        String type)
                                 throws NumberFormatException

Deprecated. This method will be removed in the next major version

Private API - used by call(String[]) to ad-hoc convert strings into the required data types for a call. This method is deprecated because it uses homegrown JSON utilities that don't deal correctly with complex types. The JacksonJsonRpcMapper has been introduced to handle primitive and complex types, as well as primitive wrappers correctly.

Throws:

NumberFormatException

call

public Object call(String method,
                   Object[] params)
            throws IOException,
                   JsonRpcException,
                   TimeoutException

Public API - builds, encodes and sends a JSON-RPC request, and waits for the response.

Returns:

the result contained within the reply, if no exception is found

Throws:

JsonRpcException - if the reply object contained an exception

TimeoutException - if a response is not received within the timeout specified, if any

IOException

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable

Public API - implements InvocationHandler.invoke. This is useful for constructing dynamic proxies for JSON-RPC interfaces.

Specified by:

invoke in interface InvocationHandler

Throws:

Throwable

createProxy

public <T> T createProxy(Class<T> klass)
                  throws IllegalArgumentException

Public API - gets a dynamic proxy for a particular interface class.

Throws:

IllegalArgumentException

call

@Deprecated
public Object call(String[] args)
                        throws NumberFormatException,
                               IOException,
                               JsonRpcException,
                               TimeoutException

Deprecated. This method will be removed in the next major version

Public API - as call(String, Object[]), but takes the method name from the first entry in args, and the parameters from subsequent entries. All parameter values are passed through coerce() to attempt to make them the types the server is expecting. This method is deprecated because it uses homegrown JSON utilities that don't deal correctly with complex types. The JacksonJsonRpcMapper has been introduced to handle primitive and complex types, as well as primitive wrappers correctly.

Returns:

the result contained within the reply, if no exception is found

Throws:

JsonRpcException - if the reply object contained an exception

NumberFormatException - if a coercion failed

TimeoutException - if a response is not received within the timeout specified, if any

IOException

See Also:

coerce(java.lang.String, java.lang.String)

getServiceDescription

public ServiceDescription getServiceDescription()

Public API - gets the service description record that this service loaded from the server itself at construction time.