Managing Queues

Queues provide the facility for users to store messages in an intermediate location sent by an external party, and access them on-demand. The EI Message Broker profile uses a Message Queue to facilitate this feature, and all operations are carried out on that message queue. The queuing feature is similar to an inbox where anyone can send messages to and only the owner can consume the messages. Queues enable users to publish messages and receive them in the order that they are sent. These queues are natively persistent, which indicates that even after shutting down the server or a sudden crash happens, the messages still remain in the queue ready to be delivered.

You can easily manage queues using the management console of the EI Message Broker profile. This includes adding new queues, removing queues, viewing their contents and more. You can also specify advanced queue configurations to improve performance and functionality when you set up an instance of EI Message Broker profile.

Following are the tasks you can perform to manage queues in the management console:

Prerequisites

The possibility to work with queues are strictly secured by role-based permissions. Therefore, a user needs to be linked to a role with the relevant permissions in order to start managing queues in the EI Message Broker profile. See the following links for details on how roles and permissions are set up for a user.

• Find out about the permissions required for working with queues.
• Creating roles and assigning permissions.
• Creating users and assigning roles.

Creating new queues

A new queue can be created using multiple methods. See the following sections for details:

Adding queues from the management console

The following steps describe how to add a queue using the management console. External applications can also add queues programmatically.

1. On the Main tab in the management console, click Queues -> Add.

2. Enter a name for the topic in the Queue Name field. 

   Note the following for queue names:

   • The queue name cannot contain any of following symbols: ~!@#;%^*()+={}|<>"' or spaces. 
   • Do not include "/" literals or prefix the name with "tmp_". 
   • The “/” symbol (TENANT_SEPARATOR) can only be used to separate the tenant domain from the queue name when creating queues from external clients.

3. Now you need to grant permissions for users in your system to publish messages to the queue and consume messages from the queue. You will be granting these permissions to users based on the user's role. As shown below, all the user roles in your tenant domain will be listed. You can select the relevant check box against each role:

   • If the Consume check box is selected, the users linked to the role has permission to consume messages from the queue.
   • If the Publish check box is selected, the users linked to the role has permission to publish messages to the queue.

   
   If you want to create new user roles as queue publishers and queue consumers, see the documentation on creating users and roles.

   By default, publishing and consuming permissions for queues (including JMS client queues) are granted only to the role to which the queue creator belongs. If required, the admin user can change these permissions (Configure > Users and Roles > Roles).

4. Click Add Queue.

5. If the queue is added successfully, a message appears. Click OK to view the Queue List where the newly added queue is listed:
   

Add queues through client subscriptions

When a JMS client subscribes to the broker (EI Message Broker profile), the queue that is specified in the subscription will be automatically created in the broker (if it doesn't already exist). However, note that the subscriber client should connect to EI Message Broker with user credentials that have permission to create new queues in the broker. See the prerequisites section above for information on granting permissions to users.

For example consider the jndi.properties file given below, which specifies the connection details of a subscriber client connecting to the EI Message Broker. As shown here, the client will be connecting to the queue named 'NewQueue' with the user 'sam'. If a queue by the name of 'NewQueue' does not exist in the broker at the time of establishing this connection, and if the user 'sam' has permission to create new queues in the broker, a new queue will be created automatically.

# register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.QueueConnectionFactory = amqp://sam:sam@clientID/carbon?brokerlist='tcp://localhost:5675'
 
# register some queues in JNDI using the form
# queue.[jndiName] = [physicalName]
queue.NewQueue=NewQueue

Adding queues at server start

The EI Message Broker profile allows you to create queues automatically when the server is started. This can be done by updating the qpid-virtualhosts.xml file with the information about the queue you want created. 

Follow the steps given below.

1. Open the qpid-virtualhosts.xml file from the <EI_HOME>/wso2/broker/conf/advanced directory.

2. Add a queue by adding a new code block under <queues>. See the following example, where a durable queue by the name of 'my-simple-queue' is added.

   <queue>
      <name>my-simple-queue</name>
      <my-simple-queue>
         <exchange>amq.direct</exchange>
         <durable>true</durable>
      </my-simple-queue>
   </queue>

   Given below are the descriptions of the elements used above.

   • <queue>: This is the container element that holds the queue definition.
   • <name>: This element is used to give a name for the queue. In this example it is 'my-simple-queue'.
   • <my-simple-queue>: Once you define the queue name using the <name> element, you must open another element using the queue name as illustrated in this example. 
   • <exchange>: Queues created in the broker will communicate with external clients through an exchange definition. This element should be set to amq.direct.
   • <durable>: This is also a mandatory element, which specifies that the queue should be durable.

3. You must now add an exchange configuration corresponding to the amq.direct exchange that you used when defining the queue.

   <exchange>
      <type>direct</type>
      <name>amq.direct</name>
      <durable>true</durable>
   </exchange>

4. Save the information.
5. Start the server and log in to the management console.
6. You can now view and manage the 'my-simple-queue' queue from the management console. See the section below on viewing queues for more information.

Viewing the message count

To view the message count:

1. Access the Queue List by clicking Queues -> List on the Main tab.
2. The list of queues and the number of messages received will be indicated in the Message Count field.

This field displays the approximate number of persistent messages that have not been delivered to the client. However, note that if the number of messages flowing through the queue is high, the message count may be a higher value than the number of messages that remained in the store when the page was loaded.

Viewing the queue contents

To view the contents of a queue:

1. Access the Queue List by clicking Queues -> List on the Main tab.
2. Click Browse for a particular queue and the contents will be listed. See the following example:
   
3. The table shows information about each message in the queue, including the content type and timestamp of the message. To view the message's body content, click more... in the Message Summary column.

Publishing messages to queues 

You can simulate how messages are published to a queue by sending a sample text using the management console. Follow the steps given below.

1. Access the Queue List by clicking Queues -> List on the Main tab.
2. Click Publish Messages for the relevant queue.
3. In the Send Message page that opens, enter values for the following properties:
   • Correlation ID: The correlation ID for the message, which can be an application-specific 'String' value set by the user. This is not a mandatory field. This property is used for linking one message with another. According to the JMS specification, it typically links a reply message with its requesting message.
   • JMS Type: A 'String' value to define the message type if required. This is not a mandatory field.
   • Number of Messages (Required) : The number of sample messages to be sent to the queue. This field is mandatory.
   • Message Body: The text content of the sample message. This is not a mandatory field as the body will be containing a text called 'Type Message Here..' in case user doesn't add a message body.
4. Click Send Message. You can then verify that the messages were delivered by checking the queue contents.

Purging queues

To purge queues from the server:

1. Access the Queue List by clicking Queues -> List on the Main tab.
2. Click Purge Messages for the relevant queue. This will remove all the messages from the queue and set the message count to zero.

Deleting queues 

To delete queues from the server:

1. Access the Queue List by clicking Queues -> List on the Main tab.
2. Click Delete for the relevant queue. This will remove all the persistent messages from the server.