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.

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.

Here is how to create a queue called TestQueue1:

Or a queue called ThisQueue and a topic called ThatTopic at the same time:

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).

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:

To deactivating a route, remove the in-use file:

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:

To remove the 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:

To remove a Local Read Lock on the TestQueue1 queue:

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:

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-locks are created.

To create a Write Lock Properties file on the TestQueue1 queue specifying an 8 second delay when more than 1000 messages exist:

To remove a Write Lock Properties file on the TestQueue1 queue:

NOTE: UNIX commands in this guide were written for the /bin/sh shell and its derivatives.