public class SimpleRpcClient

Summary

Implements a simple RPC client.

Remarks

This class sends requests that can be processed by remote SimpleRpcServer instances.

The basic pattern for accessing a remote service is to determine the exchange name and routing key needed for submissions of service requests, and to construct a SimpleRpcClient instance using that address. Once constructed, the various Call() and Cast() overloads can be used to send requests and receive the corresponding replies.

            	string queueName = "ServiceRequestQueue"; // See also Subscription ctors
            	using (IConnection conn = new ConnectionFactory()
            	                                .CreateConnection(serverAddress)) {
            	    using (IModel ch = conn.CreateModel()) {
            	        SimpleRpcClient client =
            	            new SimpleRpcClient(ch, queueName);
            	        client.TimeoutMilliseconds = 5000; // optional
            
            	        /// ... make use of the various Call() overloads
            	    }
            	}
            

Instances of this class declare a queue, so it is the user's responsibility to ensure that the exchange concerned exists (using IModel.ExchangeDeclare) before invoking Call() or Cast().

This class implements only a few basic RPC message formats - to extend it with support for more formats, either subclass, or transcode the messages before transmission using the built-in byte[] format.

See

Property Summary

Flags Type Name Summary
public PublicationAddress Address (rw)

Retrieve or modify the address that will be used for the next Call() or Cast().

public IModel Model (rw)

Retrieve the IModel this instance uses to communicate.

public Subscription Subscription (rw)

Retrieve the Subscription that is used to receive RPC replies corresponding to Call() RPC requests. May be null.

public int TimeoutMilliseconds (rw)

Retrieve or modify the timeout (in milliseconds) that will be used for the next Call().

Event Summary

Type Name Summary
EventHandler Disconnected

This event is fired whenever Call() detects the disconnection of the underlying Subscription while waiting for a reply from the service.

EventHandler TimedOut

This event is fired whenever Call() decides that a timeout has occurred while waiting for a reply from the service.

Constructor Summary

Flags Name Summary
public SimpleRpcClient(IModel model)

Construct an instance with no configured Address. The Address property must be set before Call() or Cast() are called.

public SimpleRpcClient(IModel model, string queueName)

Construct an instance that will deliver to the default exchange (""), with routing key equal to the passed in queueName, thereby delivering directly to a named queue on the AMQP server.

public SimpleRpcClient(IModel model, string exchange, string exchangeType, string routingKey)

Construct an instance that will deliver to the named and typed exchange, with the given routing key.

public SimpleRpcClient(IModel model, PublicationAddress address)

Construct an instance that will deliver to the given address.

Method Summary

Flags Name Summary
public virtual BasicDeliverEventArgs Call(IBasicProperties requestProperties, byte[] body)

Sends a byte[]/IBasicProperties RPC request, returning full information about the delivered reply as a BasicDeliverEventArgs.

public virtual byte[] Call(IBasicProperties requestProperties, byte[] body, out IBasicProperties replyProperties)

Sends a byte[] message and IBasicProperties header, returning both the body and headers of the received reply.

public virtual byte[] Call(byte[] body)

Sends a simple byte[] message, without any custom headers or properties.

public virtual object[] Call(object[] args)

Sends a "jms/stream-message"-encoded RPC request, and expects an RPC reply in the same format.

public virtual void Cast(IBasicProperties requestProperties, byte[] body)

Sends an asynchronous/one-way message to the service.

public void Close()

Close the reply subscription associated with this instance, if any.

public virtual void OnDisconnected()

Signals that the Subscription we use for receiving our RPC replies was disconnected while we were waiting.

public virtual void OnTimedOut()

Signals that the configured timeout fired while waiting for an RPC reply.

Property Detail

public PublicationAddress Address (rw)

Summary

Retrieve or modify the address that will be used for the next Call() or Cast().

Remarks

This address represents the service, i.e. the destination service requests should be published to. It can be changed at any time before a Call() or Cast() request is sent - the value at the time of the call is used by Call() and Cast().

public IModel Model (rw)

Summary

Retrieve the IModel this instance uses to communicate.

public Subscription Subscription (rw)

Summary

Retrieve the Subscription that is used to receive RPC replies corresponding to Call() RPC requests. May be null.

Remarks

Upon construction, this property will be null. It is initialised by the protected virtual method EnsureSubscription upon the first call to Call(). Calls to Cast() do not initialise the subscription, since no replies are expected or possible when using Cast().

public int TimeoutMilliseconds (rw)

Summary

Retrieve or modify the timeout (in milliseconds) that will be used for the next Call().

Remarks

This property defaults to System.Threading.Timeout.Infinite (i.e. -1). If it is set to any other value, Call() will only wait for the specified amount of time before returning indicating a timeout.

See also TimedOut event and OnTimedOut().

Event Detail

EventHandler Disconnected

Summary

This event is fired whenever Call() detects the disconnection of the underlying Subscription while waiting for a reply from the service.

Remarks

See also OnDisconnected(). Note that the sending of a request may result in OperationInterruptedException before the request is even sent.

EventHandler TimedOut

Summary

This event is fired whenever Call() decides that a timeout has occurred while waiting for a reply from the service.

Remarks

See also OnTimedOut().

Constructor Detail

SimpleRpcClient

public SimpleRpcClient(IModel model)

Parameters
Name Type
model IModel

Summary

Construct an instance with no configured Address. The Address property must be set before Call() or Cast() are called.

SimpleRpcClient

public SimpleRpcClient(IModel model, string queueName)

Parameters
Name Type
model IModel
queueName string

Summary

Construct an instance that will deliver to the default exchange (""), with routing key equal to the passed in queueName, thereby delivering directly to a named queue on the AMQP server.

SimpleRpcClient

public SimpleRpcClient(IModel model, string exchange, string exchangeType, string routingKey)

Parameters
Name Type
model IModel
exchange string
exchangeType string
routingKey string

Summary

Construct an instance that will deliver to the named and typed exchange, with the given routing key.

SimpleRpcClient

public SimpleRpcClient(IModel model, PublicationAddress address)

Parameters
Name Type
model IModel
address PublicationAddress

Summary

Construct an instance that will deliver to the given address.

Method Detail

Call

public virtual BasicDeliverEventArgs Call(IBasicProperties requestProperties, byte[] body)

Flags public virtual
Return type BasicDeliverEventArgs
Parameters
Name Type
requestProperties IBasicProperties
body byte[]

Summary

Sends a byte[]/IBasicProperties RPC request, returning full information about the delivered reply as a BasicDeliverEventArgs.

Remarks

This is the most general/lowest-level Call()-style method on SimpleRpcClient. It sets CorrelationId and ReplyTo on the request message's headers before transmitting the request to the service via the AMQP server. If the reply's CorrelationId does not match the request's CorrelationId, ProtocolViolationException will be thrown.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Call

public virtual byte[] Call(IBasicProperties requestProperties, byte[] body, out IBasicProperties replyProperties)

Flags public virtual
Return type byte[]
Parameters
Name Type
requestProperties IBasicProperties
body byte[]
replyProperties out IBasicProperties

Summary

Sends a byte[] message and IBasicProperties header, returning both the body and headers of the received reply.

Remarks

Sets the "replyProperties" outbound parameter to the properties of the received reply, and returns the byte[] body of the reply.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Both sets "replyProperties" to null and returns null when either the request timed out or we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Call

public virtual byte[] Call(byte[] body)

Flags public virtual
Return type byte[]
Parameters
Name Type
body byte[]

Summary

Sends a simple byte[] message, without any custom headers or properties.

Remarks

Delegates directly to Call(IBasicProperties, byte[]), and discards the properties of the received reply, returning only the body of the reply.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Call

public virtual object[] Call(object[] args)

Flags public virtual
Return type object[]
Parameters
Name Type
args object[]

Summary

Sends a "jms/stream-message"-encoded RPC request, and expects an RPC reply in the same format.

Remarks

The arguments passed in must be of types that are representable as JMS StreamMessage values, and so must the results returned from the service in its reply message.

Calls OnTimedOut() and OnDisconnected() when a timeout or disconnection, respectively, is detected when waiting for our reply.

Returns null if the request timed out or if we were disconnected before a reply arrived.

The reply message, if any, is acknowledged to the AMQP server via Subscription.Ack().

Cast

public virtual void Cast(IBasicProperties requestProperties, byte[] body)

Flags public virtual
Return type void
Parameters
Name Type
requestProperties IBasicProperties
body byte[]

Summary

Sends an asynchronous/one-way message to the service.

Close

public void Close()

Flags public
Return type void

Summary

Close the reply subscription associated with this instance, if any.

Remarks

Simply delegates to calling Subscription.Close(). Clears the Subscription property, so that subsequent Call()s, if any, will re-initialize it to a fresh Subscription instance.

OnDisconnected

public virtual void OnDisconnected()

Flags public virtual
Return type void

Summary

Signals that the Subscription we use for receiving our RPC replies was disconnected while we were waiting.

Remarks

Fires the Disconnected event.

OnTimedOut

public virtual void OnTimedOut()

Flags public virtual
Return type void

Summary

Signals that the configured timeout fired while waiting for an RPC reply.

Remarks

Fires the TimedOut event.