org.apache.qpid.qmf2.tools

Class QueueFuse

java.lang.Object

org.apache.qpid.qmf2.tools.QueueFuse

All Implemented Interfaces:

QmfCallback, QmfEventListener

public final class QueueFuse
extends Object
implements QmfEventListener

QueueFuse provides protection to message producers from consumers who can't consume messages fast enough.

With the default "reject" limit policy when a queue exceeds its capacity an exception is thrown to the producer. This behaviour is unfortunate, because if there happen to be multiple consumers consuming messages from a given producer it is possible for a single slow consumer to cause message flow to be stopped to all consumers, in other words a de-facto denial of service may take place.

In an Enterprise environment it is likely that this sort of behaviour is unwelcome, so QueueFuse makes it possible for queueThresholdExceeded Events to be detected and for the offending queues to have messages purged, thus protecting the other consumers by preventing an exception being thrown to the message producer.

The original intention with this class was to unbind bindings to queues that exceed the threshold. This method works, but it has a number of disadvantages. In particular there is no way to unbind from (and thus protect) queues bound to the default direct exchange, in addition in order to unbind it is necessary to retrieve binding and exchange information, both of which require further exchanges with the broker (which is not desirable as when the queueThresholdExceeded occurs we need to act pretty quickly). Finally as it happens it is also necessary to purge some messages after unbinding anyway as if this is not done the queue remains in the flowStopped state and producers will eventually time out and throw an exception if this is not cleared. So all in all simply purging each time we cross the threshold is simpler and has the additional advantage that if and when the consumer speeds up message delivery will eventually return to normal.

 Usage: QueueFuse [options] [broker-addr]...
 
 Monitors one or more Qpid message brokers for queueThresholdExceeded Events.

 If a queueThresholdExceeded Event occurs messages are purged from the queue,
 in other words this class behaves rather like a fuse 'blowing' if the
 threshold gets exceeded.

 If no broker-addr is supplied, QueueFuse connects to 'localhost:5672'.

 [broker-addr] syntax:

 [username/password@] hostname
 ip-address [:<port>]
 
 Examples:
 
 $ QueueFuse localhost:5672
 $ QueueFuse 10.1.1.7:10000
 $ QueueFuse guest/guest@broker-host:10000

 Options:
   -h, --help            show this help message and exit
   -f <filter>, --filter=<filter>
                         a list of comma separated queue names (regex are
                         accepted) to protect (default is to protect all).
   -p <PERCENT>, --purge=<PERCENT>\n" +
                         The percentage of messages to purge when the queue\n" +
                         threshold gets exceeded (default = 20%).\n" +
                         N.B. if this gets set too low the fuse may not blow.\n" +
   --sasl-mechanism=<mech>
                         SASL mechanism for authentication (e.g. EXTERNAL,
                         ANONYMOUS, PLAIN, CRAM-MD5, DIGEST-MD5, GSSAPI). SASL
                         automatically picks the most secure available
                         mechanism - use this option to override.
 

Author:

Fraser Adams

Constructor Summary

Constructors

Constructor and Description
QueueFuse(String url, String connectionOptions, List<Pattern> filter, float purge) Basic constructor.

Method Summary

Methods

Modifier and Type	Method and Description
static void	main(String[] args) Runs QueueFuse.
void	onEvent(WorkItem wi) Main Event handler.

Methods inherited from class java.lang.Object

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

Constructor Detail

QueueFuse

public QueueFuse(String url,
         String connectionOptions,
         List<Pattern> filter,
         float purge)

Basic constructor. Creates JMS Session, Initialises Destinations, Producers & Consumers and starts connection.

Parameters:

url - the connection URL.

connectionOptions - the options String to pass to ConnectionHelper.

filter - a list of regex Patterns used to choose the queues we wish to protect.

purge - the ratio of messages that we wish to purge if the threshold gets exceeded.

Method Detail

onEvent

public void onEvent(WorkItem wi)

Main Event handler.

Specified by:

onEvent in interface QmfEventListener

Parameters:

wi - a QMF2 WorkItem object

main

public static void main(String[] args)

Runs QueueFuse.

Parameters:

args - the command line arguments.