Merge pull request #420 from rabbitmq/rabbitmq-java-client-417-rpc-mandatory-flag

Add mandatory flag option to RpcClient

Author: michaelklishin

src/main/java/com/rabbitmq/client/RpcClient.java

@@ -27,6 +27,7 @@
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.concurrent.TimeoutException;
+import java.util.function.Function;
 
 import com.rabbitmq.client.impl.MethodArgumentReader;
 import com.rabbitmq.client.impl.MethodArgumentWriter;
@@ -58,6 +59,27 @@ public class RpcClient {
     private final int _timeout;
     /** NO_TIMEOUT value must match convention on {@link BlockingCell#uninterruptibleGet(int)} */
     protected final static int NO_TIMEOUT = -1;
+    /** Whether to publish RPC requests with the mandatory flag or not. */
+    private final boolean _useMandatory;
+
+    public final static Function<Object, Response> DEFAULT_REPLY_HANDLER = reply -> {
+        if (reply instanceof ShutdownSignalException) {
+            ShutdownSignalException sig = (ShutdownSignalException) reply;
+            ShutdownSignalException wrapper =
+                    new ShutdownSignalException(sig.isHardError(),
+                            sig.isInitiatedByApplication(),
+                            sig.getReason(),
+                            sig.getReference());
+            wrapper.initCause(sig);
+            throw wrapper;
+        } else if (reply instanceof UnroutableRpcRequestException) {
+            throw (UnroutableRpcRequestException) reply;
+        } else {
+            return (Response) reply;
+        }
+    };
+
+    private final Function<Object, Response> _replyHandler;
 
     /** Map from request correlation ID to continuation BlockingCell */
     private final Map<String, BlockingCell<Object>> _continuationMap = new HashMap<String, BlockingCell<Object>>();
@@ -67,6 +89,46 @@ public class RpcClient {
     /** Consumer attached to our reply queue */
     private DefaultConsumer _consumer;
 
+    /**
+     * Construct a {@link RpcClient} with the passed-in {@link RpcClientParams}.
+     *
+     * @param params
+     * @throws IOException
+     * @see RpcClientParams
+     * @since 5.6.0
+     */
+    public RpcClient(RpcClientParams params) throws
+            IOException {
+        _channel = params.getChannel();
+        _exchange = params.getExchange();
+        _routingKey = params.getRoutingKey();
+        _replyTo = params.getReplyTo();
+        if (params.getTimeout() < NO_TIMEOUT) {
+            throw new IllegalArgumentException("Timeout argument must be NO_TIMEOUT(-1) or non-negative.");
+        }
+        _timeout = params.getTimeout();
+        _useMandatory = params.shouldUseMandatory();
+        _replyHandler = params.getReplyHandler();
+        _correlationId = 0;
+
+        _consumer = setupConsumer();
+        if (_useMandatory) {
+            this._channel.addReturnListener(returnMessage -> {
+                synchronized (_continuationMap) {
+                    String replyId = returnMessage.getProperties().getCorrelationId();
+                    BlockingCell<Object> blocker = _continuationMap.remove(replyId);
+                    if (blocker == null) {
+                        // Entry should have been removed if request timed out,
+                        // log a warning nevertheless.
+                        LOGGER.warn("No outstanding request for correlation ID {}", replyId);
+                    } else {
+                        blocker.set(new UnroutableRpcRequestException(returnMessage));
+                    }
+                }
+            });
+        }
+    }
+
     /**
      * Construct a new RpcClient that will communicate on the given channel, sending
      * requests to the given exchange with the given routing key.
@@ -78,18 +140,16 @@ public class RpcClient {
      * @param replyTo the queue where the server should put the reply
      * @param timeout milliseconds before timing out on wait for response
      * @throws IOException if an error is encountered
+     * @deprecated use {@link RpcClient#RpcClient(RpcClientParams)} instead, will be removed in 6.0.0
      */
+    @Deprecated
     public RpcClient(Channel channel, String exchange, String routingKey, String replyTo, int timeout) throws
             IOException {
-        _channel = channel;
-        _exchange = exchange;
-        _routingKey = routingKey;
-        _replyTo = replyTo;
-        if (timeout < NO_TIMEOUT) throw new IllegalArgumentException("Timeout arguument must be NO_TIMEOUT(-1) or non-negative.");
-        _timeout = timeout;
-        _correlationId = 0;
-
-        _consumer = setupConsumer();
+        this(new RpcClientParams()
+            .channel(channel).exchange(exchange).routingKey(routingKey)
+            .replyTo(replyTo).timeout(timeout)
+            .useMandatory(false)
+        );
     }
 
     /**
@@ -106,7 +166,9 @@ public RpcClient(Channel channel, String exchange, String routingKey, String rep
      * @param routingKey the routing key
      * @param replyTo the queue where the server should put the reply
      * @throws IOException if an error is encountered
+     * @deprecated use {@link RpcClient#RpcClient(RpcClientParams)} instead, will be removed in 6.0.0
      */
+    @Deprecated
     public RpcClient(Channel channel, String exchange, String routingKey, String replyTo) throws IOException {
         this(channel, exchange, routingKey, replyTo, NO_TIMEOUT);
     }
@@ -123,7 +185,9 @@ public RpcClient(Channel channel, String exchange, String routingKey, String rep
      * @param exchange the exchange to connect to
      * @param routingKey the routing key
      * @throws IOException if an error is encountered
+     * @deprecated use {@link RpcClient#RpcClient(RpcClientParams)} instead, will be removed in 6.0.0
      */
+    @Deprecated
     public RpcClient(Channel channel, String exchange, String routingKey) throws IOException {
         this(channel, exchange, routingKey, "amq.rabbitmq.reply-to", NO_TIMEOUT);
     }
@@ -142,7 +206,9 @@ public RpcClient(Channel channel, String exchange, String routingKey) throws IOE
      * @param routingKey the routing key
      * @param timeout milliseconds before timing out on wait for response
      * @throws IOException if an error is encountered
+     * @deprecated use {@link RpcClient#RpcClient(RpcClientParams)} instead, will be removed in 6.0.0
      */
+    @Deprecated
     public RpcClient(Channel channel, String exchange, String routingKey, int timeout) throws IOException {
         this(channel, exchange, routingKey, "amq.rabbitmq.reply-to", timeout);
     }
@@ -213,7 +279,7 @@ public void handleDelivery(String consumerTag,
     public void publish(AMQP.BasicProperties props, byte[] message)
         throws IOException
     {
-        _channel.basicPublish(_exchange, _routingKey, props, message);
+        _channel.basicPublish(_exchange, _routingKey, _useMandatory, props, message);
     }
 
     public Response doCall(AMQP.BasicProperties props, byte[] message)
@@ -242,18 +308,7 @@ public Response doCall(AMQP.BasicProperties props, byte[] message, int timeout)
             _continuationMap.remove(replyId);
             throw ex;
         }
-        if (reply instanceof ShutdownSignalException) {
-            ShutdownSignalException sig = (ShutdownSignalException) reply;
-            ShutdownSignalException wrapper =
-                new ShutdownSignalException(sig.isHardError(),
-                                            sig.isInitiatedByApplication(),
-                                            sig.getReason(),
-                                            sig.getReference());
-            wrapper.initCause(sig);
-            throw wrapper;
-        } else {
-            return (Response) reply;
-        }
+        return _replyHandler.apply(reply);
     }
 
     public byte[] primitiveCall(AMQP.BasicProperties props, byte[] message)

src/main/java/com/rabbitmq/client/RpcClientParams.java

@@ -0,0 +1,193 @@
+// Copyright (c) 2007-Present Pivotal Software, Inc.  All rights reserved.
+//
+// This software, the RabbitMQ Java client library, is triple-licensed under the
+// Mozilla Public License 1.1 ("MPL"), the GNU General Public License version 2
+// ("GPL") and the Apache License version 2 ("ASL"). For the MPL, please see
+// LICENSE-MPL-RabbitMQ. For the GPL, please see LICENSE-GPL2.  For the ASL,
+// please see LICENSE-APACHE2.
+//
+// This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND,
+// either express or implied. See the LICENSE file for specific language governing
+// rights and limitations of this software.
+//
+// If you have any questions regarding licensing, please contact us at
+// [email protected].
+
+package com.rabbitmq.client;
+
+import java.util.function.Function;
+
+/**
+ * Holder class to configure a {@link RpcClient}.
+ *
+ * @see RpcClient#RpcClient(RpcClientParams)
+ * @since 5.6.0
+ */
+public class RpcClientParams {
+
+    /**
+     * Channel we are communicating on
+     */
+    private Channel channel;
+    /**
+     * Exchange to send requests to
+     */
+    private String exchange;
+    /**
+     * Routing key to use for requests
+     */
+    private String routingKey;
+    /**
+     * Queue where the server should put the reply
+     */
+    private String replyTo = "amq.rabbitmq.reply-to";
+    /**
+     * Timeout in milliseconds to use on call responses
+     */
+    private int timeout = RpcClient.NO_TIMEOUT;
+    /**
+     * Whether to publish RPC requests with the mandatory flag or not.
+     */
+    private boolean useMandatory = false;
+    /**
+     * Behavior to handle reply messages.
+     */
+    private Function<Object, RpcClient.Response> replyHandler = RpcClient.DEFAULT_REPLY_HANDLER;
+
+    /**
+     * Set the channel to use for communication.
+     *
+     * @return
+     */
+    public Channel getChannel() {
+        return channel;
+    }
+
+    public RpcClientParams channel(Channel channel) {
+        this.channel = channel;
+        return this;
+    }
+
+    /**
+     * Set the exchange to send requests to.
+     *
+     * @return
+     */
+    public String getExchange() {
+        return exchange;
+    }
+
+    public RpcClientParams exchange(String exchange) {
+        this.exchange = exchange;
+        return this;
+    }
+
+    public String getRoutingKey() {
+        return routingKey;
+    }
+
+    /**
+     * Set the routing key to use for requests.
+     *
+     * @param routingKey
+     * @return
+     */
+    public RpcClientParams routingKey(String routingKey) {
+        this.routingKey = routingKey;
+        return this;
+    }
+
+    public String getReplyTo() {
+        return replyTo;
+    }
+
+    /**
+     * Set the queue where the server should put replies on.
+     * <p>
+     * The default is to use
+     * <a href="https://www.rabbitmq.com/direct-reply-to.html">Direct Reply-to</a>.
+     * Using another value will cause the creation of a temporary private
+     * auto-delete queue.
+     * <p>
+     * The default shouldn't be changed for performance reasons.
+     *
+     * @param replyTo
+     * @return
+     */
+    public RpcClientParams replyTo(String replyTo) {
+        this.replyTo = replyTo;
+        return this;
+    }
+
+    public int getTimeout() {
+        return timeout;
+    }
+
+    /**
+     * Set the timeout in milliseconds to use on call responses.
+     *
+     * @param timeout
+     * @return
+     */
+    public RpcClientParams timeout(int timeout) {
+        this.timeout = timeout;
+        return this;
+    }
+
+    /**
+     * Whether to publish RPC requests with the mandatory flag or not.
+     * <p>
+     * Default is to not publish requests with the mandatory flag
+     * set to true.
+     * <p>
+     * When set to true, unroutable requests will result
+     * in {@link UnroutableRpcRequestException} exceptions thrown.
+     * Use a custom reply handler to change this behavior.
+     *
+     * @param useMandatory
+     * @return
+     * @see #replyHandler(Function)
+     */
+    public RpcClientParams useMandatory(boolean useMandatory) {
+        this.useMandatory = useMandatory;
+        return this;
+    }
+
+    /**
+     * Instructs to use the mandatory flag when publishing RPC requests.
+     * <p>
+     * Unroutable requests will result in {@link UnroutableRpcRequestException} exceptions
+     * thrown. Use a custom reply handler to change this behavior.
+     *
+     * @return
+     * @see #replyHandler(Function)
+     */
+    public RpcClientParams useMandatory() {
+        return useMandatory(true);
+    }
+
+    public boolean shouldUseMandatory() {
+        return useMandatory;
+    }
+
+    public Function<Object, RpcClient.Response> getReplyHandler() {
+        return replyHandler;
+    }
+
+    /**
+     * Set the behavior to use when receiving replies.
+     * <p>
+     * The default is to wrap the reply into a {@link com.rabbitmq.client.RpcClient.Response}
+     * instance. Unroutable requests will result in {@link UnroutableRpcRequestException}
+     * exceptions.
+     *
+     * @param replyHandler
+     * @return
+     * @see #useMandatory()
+     * @see #useMandatory(boolean)
+     */
+    public RpcClientParams replyHandler(Function<Object, RpcClient.Response> replyHandler) {
+        this.replyHandler = replyHandler;
+        return this;
+    }
+}