public class Subscription

Summary

Manages a subscription to a queue.

Remarks

This convenience class abstracts away from much of the detail involved in receiving messages from a queue.

Once created, the Subscription consumes from a queue (using a QueueingBasicConsumer). Received deliveries can be retrieved by calling Next(), or by using the Subscription as an IEnumerator in, for example, a foreach loop.

Note that if the "noAck" option is enabled (which it is by default), then received deliveries are automatically acked within the server before they are even transmitted across the network to us. Calling Ack() on received events will always do the right thing: if "noAck" is enabled, nothing is done on an Ack() call, and if "noAck" is disabled, IModel.BasicAck() is called with the correct parameters.

Property Summary

Flags Type Name Summary
public virtual final IBasicConsumer Consumer (r)

Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.

public virtual final string ConsumerTag (rw)

Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.

public virtual final BasicDeliverEventArgs LatestEvent (rw)

Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, the end of the subscription has been reached, or the most recent value has already been Ack()ed. See also the documentation for Ack().

public virtual final IModel Model (rw)

Retrieve the IModel our subscription is carried by.

public virtual final bool NoAck (rw)

Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.

public virtual final string QueueName (rw)

Retrieve the queue name we have subscribed to.

Constructor Summary

Flags Name Summary
public Subscription(IModel model, string queueName)

Creates a new Subscription in "noAck" mode, consuming from a named queue.

public Subscription(IModel model, string queueName, bool noAck)

Creates a new Subscription, with full control over both "noAck" mode and the name of the queue.

public Subscription(IModel model, string queueName, bool noAck, string consumerTag)

Creates a new Subscription, with full control over both "noAck" mode, the name of the queue, and the consumer tag.

Method Summary

Flags Name Summary
public virtual final void Ack()

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

public virtual final void Ack(BasicDeliverEventArgs evt)

If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from ; otherwise, sends nothing to the server. if is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

public virtual final void Close()

Closes this Subscription, cancelling the consumer record in the server.

public virtual final void Nack(bool requeue)

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, false, requeue). Causes LatestEvent to become null.

public virtual final void Nack(bool multiple, bool requeue)

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, multiple, requeue). Causes LatestEvent to become null.

public virtual final void Nack(BasicDeliverEventArgs evt, bool multiple, bool requeue)

If we are not in "noAck" mode, calls IModel.BasicNack with the delivery-tag from ; otherwise, sends nothing to the server. if is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

public virtual final BasicDeliverEventArgs Next()

Retrieves the next incoming delivery in our subscription queue.

public virtual final bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

Property Detail

public virtual final IBasicConsumer Consumer (r)

Summary

Retrieve the IBasicConsumer that is receiving the messages from the server for us. Normally, you will not need to access this property - use Next() and friends instead.

public virtual final string ConsumerTag (rw)

Summary

Retrieve the consumer-tag that this subscription is using. Will usually be a server-generated name.

public virtual final BasicDeliverEventArgs LatestEvent (rw)

Summary

Returns the most recent value returned by Next(), or null when either no values have been retrieved yet, the end of the subscription has been reached, or the most recent value has already been Ack()ed. See also the documentation for Ack().

public virtual final IModel Model (rw)

Summary

Retrieve the IModel our subscription is carried by.

public virtual final bool NoAck (rw)

Summary

Returns true if we are in "noAck" mode, where calls to Ack() will be no-ops, and where the server acks messages before they are delivered to us. Returns false if we are in a mode where calls to Ack() are required, and where such calls will actually send an acknowledgement message across the network to the server.

public virtual final string QueueName (rw)

Summary

Retrieve the queue name we have subscribed to.

Constructor Detail

Subscription

public Subscription(IModel model, string queueName)

Parameters
Name Type
model IModel
queueName string

Summary

Creates a new Subscription in "noAck" mode, consuming from a named queue.

Subscription

public Subscription(IModel model, string queueName, bool noAck)

Parameters
Name Type
model IModel
queueName string
noAck bool

Summary

Creates a new Subscription, with full control over both "noAck" mode and the name of the queue.

Subscription

public Subscription(IModel model, string queueName, bool noAck, string consumerTag)

Parameters
Name Type
model IModel
queueName string
noAck bool
consumerTag string

Summary

Creates a new Subscription, with full control over both "noAck" mode, the name of the queue, and the consumer tag.

Method Detail

Ack

public virtual final void Ack()

Flags public virtual final
Return type void

Summary

If LatestEvent is non-null, passes it to Ack(BasicDeliverEventArgs). Causes LatestEvent to become null.

Ack

public virtual final void Ack(BasicDeliverEventArgs evt)

Flags public virtual final
Return type void
Parameters
Name Type
evt BasicDeliverEventArgs

Summary

If we are not in "noAck" mode, calls IModel.BasicAck with the delivery-tag from ; otherwise, sends nothing to the server. if is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

Remarks

Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour

Close

public virtual final void Close()

Flags public virtual final
Return type void

Summary

Closes this Subscription, cancelling the consumer record in the server.

Nack

public virtual final void Nack(bool requeue)

Flags public virtual final
Return type void
Parameters
Name Type
requeue bool

Summary

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, false, requeue). Causes LatestEvent to become null.

Nack

public virtual final void Nack(bool multiple, bool requeue)

Flags public virtual final
Return type void
Parameters
Name Type
multiple bool
requeue bool

Summary

If LatestEvent is non-null, passes it to Nack(BasicDeliverEventArgs, multiple, requeue). Causes LatestEvent to become null.

Nack

public virtual final void Nack(BasicDeliverEventArgs evt, bool multiple, bool requeue)

Flags public virtual final
Return type void
Parameters
Name Type
evt BasicDeliverEventArgs
multiple bool
requeue bool

Summary

If we are not in "noAck" mode, calls IModel.BasicNack with the delivery-tag from ; otherwise, sends nothing to the server. if is the same as LatestEvent by pointer comparison, sets LatestEvent to null.

Remarks

Passing an event that did not originate with this Subscription's channel, will lead to unpredictable behaviour

Next

public virtual final BasicDeliverEventArgs Next()

Flags public virtual final
Return type BasicDeliverEventArgs

Summary

Retrieves the next incoming delivery in our subscription queue.

Remarks

Returns null when the end of the stream is reached and on every subsequent call. End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

Updates LatestEvent to the value returned.

Does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

Next

public virtual final bool Next(int millisecondsTimeout, out BasicDeliverEventArgs result)

Flags public virtual final
Return type bool
Parameters
Name Type
millisecondsTimeout int
result out BasicDeliverEventArgs

Summary

Retrieves the next incoming delivery in our subscription queue, or times out after a specified number of milliseconds.

Remarks

Returns false only if the timeout expires before either a delivery appears or the end-of-stream is reached. If false is returned, the out parameter "result" is set to null, but LatestEvent is not updated.

Returns true to indicate a delivery or the end-of-stream.

If a delivery is already waiting in the queue, or one arrives before the timeout expires, it is removed from the queue and placed in the "result" out parameter. If the end-of-stream is detected before the timeout expires, "result" is set to null.

Whenever this method returns true, it updates LatestEvent to the value placed in "result" before returning.

End-of-stream can arise through the action of the Subscription.Close() method, or through the closure of the IModel or its underlying IConnection.

This method does not acknowledge any deliveries at all (but in "noAck" mode, the server will have auto-acknowledged each event before it is even sent across the wire to us).

A timeout of -1 (i.e. System.Threading.Timeout.Infinite) will be interpreted as a command to wait for an indefinitely long period of time for an item or the end of the stream to become available. Usage of such a timeout is equivalent to calling Next() with no arguments (modulo predictable method signature differences).