Creating and Destroying Physical Destinations

The subcommand imqcmd create dst creates a new physical destination:

   imqcmd create dst  -t destType  -n destName
                      [ [-o property=value] … ]

You supply the destination type (q for a queue or t for a topic) and the name of the destination.

Naming Destinations

Destination names must conform to the rules described below for queue and topic destinations.

Supported Queue Destination Names

Queue destination names must conform to the following rules:

• It must contain only alphanumeric characters.

• It must not contain spaces.

• It must begin with an alphabetic character (A–Z, a–z), an underscore (_), or a dollar sign ($).

• It must not begin with the characters mq.

For example, the following command creates a queue destination named XQueue:

   imqcmd create dst  -t q  -n XQueue

Supported Topic Destination Names

Topic destination names must conform to the same rules as queue destinations, as specified in Supported Queue Destination Names, except that Message Queue also supports, in addition, topic destination names that include wildcard characters, representing multiple destinations. These symbolic names allow publishers to publish messages to multiple topics and subscribers to consume messages from multiple topics. Using symbolic names, you can create destinations, as needed, consistent with the wildcard naming scheme. Publishers and subscribers automatically publish to and consume from any added destinations that match the symbolic names. (Wildcard topic subscribers are more common than publishers.)

The format of a symbolic topic destination name consists of multiple segments, in which wildcard characters (*, **, >) can represent one or more segments of the name. For example, suppose you have a topic destination naming scheme as follows:

size.color.shape

where the topic name segments can have the following values:

• size: large, medium, small, ...

• color: red, green, blue, ...

• shape: circle, triangle, square, ...

Message Queue supports the following wildcard characters:

• * matches a single segment

• ** matches one or more segments

• > matches any number of successive segments

You can therefore indicate multiple topic destinations as follows:

large.*.circle would represent:

large.red.circle
large.green.circle
...

**.square would represent all names ending in .square, for example:

small.green.square
medium.blue.square
...

small.> would represent all destination names starting with small., for example:

small.blue.circle
small.red.square
...

To use this multiple destination feature, you create topic destinations using a naming scheme similar to that described above. For example, the following command creates a topic destination named large.green.circle:

   imqcmd create dst  -t t  -n large.green.circle

Client applications can then create wildcard publishers or wildcard consumers using symbolic destination names, as shown in the following examples:

Example 7–1 Wildcard Publisher

...
String DEST_LOOKUP_NAME = "large.*.circle";
Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME);
TopicPublisher myPublisher = mySession.createPublisher(t)
myPublisher.send(myMessage);

In this example, the broker will place a copy of the message in any destination that matches the symbolic name large.*.circle

Example 7–2 Wildcard Subscriber

...
String DEST_LOOKUP_NAME = "**.square";
Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME);
TopicSubscriber mySubscriber = mySession.createSubscriber(t);
Message m = mySubscriber.receive();

In this example, a subscriber will be created if there is at least one destination that matches the symbolic name **.square and will receive messages from all destinations that match that symbolic name. If there are no destinations matching the symbolic name, the subscriber will not be registered with the broker until such a destination exists.

If you create additional destinations that match a symbolic name, then wildcard publishers created using that symbolic name will subsequently publish to that destination and wildcard subscribers created using that symbolic name will subsequently receive messages from that destination.

In addition, Message Queue administration tools, in addition to reporting the total number of publishers (producers) and subscribers (consumers) for a topic destination, will also report the number of publishers that are wildcard publishers (including their corresponding symbolic destination names) and the number of subscribers that are wildcard subscribers (including their symbolic destination names), if any. See Viewing Physical Destination Information.

Setting Property Values

The imqcmd create dst command may also optionally include any property values you wish to set for the destination, specified with the -o option. For example, the following command creates a topic destination named hotTopic with a maximum message length of 5000 bytes:

   imqcmd create dst  -t t  -n hotTopic  -o maxBytesPerMsg=5000

See Chapter 17, Physical Destination Property Reference for reference information about the physical destination properties that can be set with this option. (For auto-created destinations, you set default property values in the broker’s instance configuration file; see Table 16–3 for information on these properties.)

Destroying Destinations

To destroy a physical destination, use the imqcmd destroy dst subcommand:

   imqcmd destroy dest  -t destType  -n destName

This purges all messages at the specified destination and removes it from the broker; the operation is not reversible.

For example, the following command destroys the queue destination named curlyQueue:

   imqcmd destroy dest  -t q  -n curlyQueue  -u admin

You cannot destroy the dead message queue.