Environment Variables Creating Queues and Topics Message Routing Example routing.properties Directing Routes Activating and Deactivating Routes Flow Control The Global Read Lock Local Read Locks Write Lock Properties ## Environment Variables Most administrative tasks described here use two environment variables: `DROPBOXMQ_HOME` and `DROPBOX_ROOT`. `DROPBOXMQ_HOME` is used to locate the DropboxMQ distribution directory and defaults to the parent directory of the directory containing the DropboxMQ tool in use. `DROPBOX_ROOT` specifies the parent directory containing the dropboxes to be administered. `DROPBOX_ROOT` defaults to the current working directory but should be set explicitly to assure administrative tasks are performed in the proper location.
UNIX: |  | `$ export DROPBOXMQ_HOME=/opt/dropboxmq` `$ export DROPBOX_ROOT=/dropbox` `$ export PATH=$DROPBOXMQ_HOME/bin:$PATH`
Windows: |  | `C:\> set DROPBOXMQ_HOME=C:\dropboxmq` `C:\> set DROPBOX_ROOT=C:\dropbox` `C:\> set PATH=%DROPBOXMQ_HOME%\bin;%PATH%`
NOTE: UNIX commands in this guide were written for the `/bin/sh` shell and its derivatives. ## Creating Queues and Topics Creating a dropbox for a queue or topic is as easy as creating a handful of directories in the shared `DROPBOX_ROOT` directory. Still the preferred mechanism for creating queues and topics is by calling `create-dropbox`.
`create-dropbox -? | -h | --help | /? | /h | /help` `Display this help text.` `create-dropbox { -q | --queue | /q | /queue } queue-name1` `{ -q | --queue | /q | /queue } queue-name2` `{ -t | --topic | /t | /topic } topic-name1` `{ -t | --topic | /t | /topic } topic-name2` `Create the one or more queues and/or topics listed.`
Here is how to create a queue called `TestQueue1`:
UNIX: |  | `$ create-dropbox --queue TestQueue1`
Windows: |  | `C:\> create-dropbox /queue TestQueue1`
Or a queue called `ThisQueue` and a topic called `ThatTopic` at the same time:
UNIX: |  | `$ create-dropbox -q ThisQueue -t ThatTopic`
Windows: |  | `C:\> create-dropbox /q ThisQueue /t ThatTopic`
## Message Routing DropboxMQ messages can be routed from one destination to another or simply routed to a holding location and consumed later. Routes are listed in a `routing.properties` file located in the `incoming` directory. Each route is defined by a name and a JMS message selector in the format of `{route-name}.selector={selector}`. An active consumer must attempt to consume messages for any routes to be used. When multiple routes are defined and active, selectors are applied in the alphabetical order of the names. If no selectors match a message, it is delivered to the consumer as normal. ### Example `routing.properties` The following property file defines two routes. The first route is named `route1` and will route messages with a priority less than `200` and a reply-to of `ReplyQueue1`. The second route is named `route2` and will route messages with a `JMSType` of `WorkOrder`, `Manifestdoc` or `CatalogQuery`. If both routes are active and a message arrives with priority of `250`, reply-to of `ReplyQueue1` and a type of `ManifestDoc`, the message will be routed to `route1` (`route1` comes before `route2` alphabetically).
`route1.selector=JMSPriority < 200 and JMSReplyTo \= 'ReplyQueue1'` `route2.selector=JMSType in ('WorkOrder', 'ManifestDoc', \` `'CatalogQuery')`
### Directing Routes When an active route has been selected, messages are moved to that route's directory. This directory is located in the `routing` directory of the dropbox and has the same name as the route defined in the `routing.properties` file. On UNIX file systems, this directory can actually be a symbolic link to another dropbox's `target` directory thereby causing messages to be routed from one dropbox to another. ### Activating and Deactivating Routes Once the route's selector is defined and the route's directory is in place, the route is ready to be activated. To activate a route, simply create an in-use file in the `routing` directory with a filename of the form `{route-name}.in-use`. The following example shows how to activate `route1` for `TestQueue1`:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming/routing` `$ touch route1.in-use`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming\routing` `C:\...\routing> echo route > route1.in-use`
To deactivating a route, remove the in-use file:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming/routing` `$ rm route1.in-use`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming\routing` `C:\...\routing> del route1.in-use`
## Flow Control DropboxMQ has several mechanisms for controlling if and how quickly messages are produced and consumed. It is important to note that these mechanisms are only implemented by DropboxMQ clients. Shell scripts or other non-JMS clients sending and receiving messages will not be affected by these locks and controls. Note: If any flow mechanisms are active, any affected DropboxMQ client will log a warning message once every five minutes per affected producer/consumer. ### The Global Read Lock The Global Read Lock, when in place, prevents all consumers from consuming messages. All DropboxMQ consumers that attempt to consume messages when the lock is place will behave exactly as though no messages exist. To create the Global Read Lock:
UNIX: |  | `$ cd $DROPBOX_ROOT` `$ touch global-read-lock`
Windows: |  | `C:\> cd %DROPBOX_ROOT%` `C:\dropbox> echo lock > global-read-lock`
To remove the Global Read Lock:
UNIX: |  | `$ cd $DROPBOX_ROOT` `$ rm global-read-lock`
Windows: |  | `C:\> cd %DROPBOX_ROOT%` `C:\dropbox> del global-read-lock`
### Local Read Locks Local Read Locks also prevent consumers from consuming messages, but these locks only affect consumers for a single destination. To create a Local Read Lock on the TestQueue1 queue:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming` `$ touch read-lock`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming` `C:\...\incoming> echo lock > read-lock`
To remove a Local Read Lock on the TestQueue1 queue:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming` `$ rm read-lock`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming` `C:\...\incoming> del read-lock`
### Write Lock Properties Write Lock Properties control if a producer attempting to send a message to a particular destination will be permitted to do so and if there will be any delay in doing so. Write locks can be dangerous because they can cause a DropboxMQ client to hang for an indeterminate amount of time. There are two values that can be specified in the Write Lock Properties:
Name: | `delay-milliseconds`
Type: | `long`
Default: | `-1` (indefinitely)
Example: | `8000` (8 seconds)
Specifies how long a producer will wait before being permitted to send a message. If `-1` is specified, the producer will wait indefinitely or until the `target-limit` requirement is met.
Name: | `target-limit`
Type: | `int`
Default: | `0`
Example: | `1000`
Specifies the maximum number of messages that can be waiting on a destination. If fewer than this number of messages are waiting in the `target` directory, any message will be sent without delay (regardless of the `delay-milliseconds` value). If `0` is specified, each message will be delayed by the time specified in `delay-milliseconds` (or indefinitely if `delay-milliseconds` is `-1`).
If the property file doesn't exist, messages are not delayed at all. If the property file exists, but no properties are defined, messages will be delayed indefinitely (values default to `delay-milliseconds` of `-1` and `target-limit` of 0). This means that all messages producers of a particular destination can be quickly locked out by simply touching a `write-lock.properties` file similarly to how `read-lock`s are created. To create a Write Lock Properties file on the TestQueue1 queue specifying an 8 second delay when more than 1000 messages exist:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming` `$ echo "delay-milliseconds=8000" > write-lock.properties` `$ echo "target-limit=1000" >> write-lock.properties`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming` `C:\...\incoming> echo delay-milliseconds=8000 > write-lock.properties` `C:\...\incoming> echo target-limit=1000 >> write-lock.properties`
To remove a Write Lock Properties file on the TestQueue1 queue:
UNIX: |  | `$ cd $DROPBOX_ROOT/TestQueue1/incoming` `$ rm write-lock.properties`
Windows: |  | `C:\> cd %DROPBOX_ROOT%\TestQueue1\incoming` `C:\...\incoming> del write-lock.properties`
NOTE: UNIX commands in this guide were written for the `/bin/sh` shell and its derivatives.