Class JsonRpcClient

  • All Implemented Interfaces:
    java.lang.AutoCloseable, java.lang.reflect.InvocationHandler

    public class JsonRpcClient
    extends RpcClient
    implements java.lang.reflect.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.

    See Also:
    call(String, Object[]), JsonRpcMapper, JacksonJsonRpcMapper
    • Field Detail

      • LOGGER

        private static final org.slf4j.Logger LOGGER
      • serviceDescription

        private ServiceDescription serviceDescription
        Holds the JSON-RPC service description for this client.
    • Constructor Detail

      • JsonRpcClient

        public JsonRpcClient​(Channel channel,
                             java.lang.String exchange,
                             java.lang.String routingKey,
                             int timeout,
                             JsonRpcMapper mapper)
                      throws java.io.IOException,
                             JsonRpcException,
                             java.util.concurrent.TimeoutException
        Construct a new JsonRpcClient, passing the parameters through to RpcClient's constructor. The service description record is retrieved from the server during construction.
        Throws:
        java.util.concurrent.TimeoutException - if a response is not received within the timeout specified, if any
        java.io.IOException
        JsonRpcException
      • JsonRpcClient

        public JsonRpcClient​(Channel channel,
                             java.lang.String exchange,
                             java.lang.String routingKey,
                             int timeout)
                      throws java.io.IOException,
                             JsonRpcException,
                             java.util.concurrent.TimeoutException
        Construct a new JsonRpcClient, passing the parameters through to RpcClient's constructor. The service description record is retrieved from the server during construction.
        Throws:
        java.util.concurrent.TimeoutException - if a response is not received within the timeout specified, if any
        java.io.IOException
        JsonRpcException
      • JsonRpcClient

        public JsonRpcClient​(Channel channel,
                             java.lang.String exchange,
                             java.lang.String routingKey)
                      throws java.io.IOException,
                             JsonRpcException,
                             java.util.concurrent.TimeoutException
        Throws:
        java.io.IOException
        JsonRpcException
        java.util.concurrent.TimeoutException
    • Method Detail

      • coerce

        @Deprecated
        public static java.lang.Object coerce​(java.lang.String val,
                                              java.lang.String type)
                                       throws java.lang.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:
        java.lang.NumberFormatException
      • checkReply

        private java.lang.Object checkReply​(JsonRpcMapper.JsonRpcResponse reply)
                                     throws JsonRpcException
        Private API - parses a JSON-RPC reply object, checking it for exceptions.
        Returns:
        the result contained within the reply, if no exception is found Throws JsonRpcException if the reply object contained an exception
        Throws:
        JsonRpcException
      • call

        public java.lang.Object call​(java.lang.String method,
                                     java.lang.Object[] params)
                              throws java.io.IOException,
                                     JsonRpcException,
                                     java.util.concurrent.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
        java.util.concurrent.TimeoutException - if a response is not received within the timeout specified, if any
        java.io.IOException
      • invoke

        public java.lang.Object invoke​(java.lang.Object proxy,
                                       java.lang.reflect.Method method,
                                       java.lang.Object[] args)
                                throws java.lang.Throwable
        Public API - implements InvocationHandler.invoke. This is useful for constructing dynamic proxies for JSON-RPC interfaces.
        Specified by:
        invoke in interface java.lang.reflect.InvocationHandler
        Throws:
        java.lang.Throwable
      • createProxy

        public <T> T createProxy​(java.lang.Class<T> klass)
                          throws java.lang.IllegalArgumentException
        Public API - gets a dynamic proxy for a particular interface class.
        Throws:
        java.lang.IllegalArgumentException
      • call

        @Deprecated
        public java.lang.Object call​(java.lang.String[] args)
                              throws java.lang.NumberFormatException,
                                     java.io.IOException,
                                     JsonRpcException,
                                     java.util.concurrent.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
        java.lang.NumberFormatException - if a coercion failed
        java.util.concurrent.TimeoutException - if a response is not received within the timeout specified, if any
        java.io.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.
      • retrieveServiceDescription

        private void retrieveServiceDescription()
                                         throws java.io.IOException,
                                                JsonRpcException,
                                                java.util.concurrent.TimeoutException
        Private API - invokes the "system.describe" method on the server, and parses and stores the resulting service description in this object. TODO: Avoid calling this from the constructor.
        Throws:
        java.util.concurrent.TimeoutException - if a response is not received within the timeout specified, if any
        java.io.IOException
        JsonRpcException