Queues

The queue types provided by WebSphere MQ Everyplace are described briefly in Chapter 5, Queues, of the WebSphere MQ Everyplace Application Programming Guide. The simplest of these is a local queue that is implemented in class MQeQueue and is managed by class MQeQueueAdminMsg. All other types of queue inherit from MQeQueue. For each type of queue there is a corresponding administration message that inherits from MQeQueueAdminMsg. The following sections describe the administration of the various types of queues.

Local queue

You can create, update, delete and inquire on local queues and their descendents using administration actions provided in WebSphere MQ Everyplace. The basic administration mechanism is inherited from MQeAdminMsg.

The name of a queue is formed from the target queue manager name, for a local queue this is the name of the queue manager that owns the queue, and a unique name for the queue on that queue manager. Two fields in the administration message are used to uniquely identify the queue, these are the ASCII fields Admin_Name and Queue_QMgrName. You can use the setName( queueManagerName, queueName) method to set these two fields in the administration message.

The diagram below shows an example of a queue manager configured with a local queue. Queue manager qm1 has a local queue named invQ. The queue manager name characteristic of the queue is qm1, which matches the queue manager name. Figure 13 shows a local queue:

Figure 13. Local queue

top

Message Store

Local queues require a message store to store their messages. Each queue can specify what type of store to use, and where it is located. Use the queue characteristic Queue_FileDesc to specify the type of message store and to provide parameters for it. The field type is ascii and the value must be a file descriptor of the form:
adapter class:adapter parameters
or
adapter alias:adapter parameters

For example:

MsgLog:d:\QueueManager\ServerQM12\Queues

WebSphere MQ Everyplace Version 2.0.0.4 provides two adapters, one for writing messages to disk and one for storing them in memory. By creating an appropriate adapter, messages can be stored in any suitable place or medium (such as DB2(R) database or writable CDs).

The choice of adapter determines the persistence and resilience of messages. For instance if a memory adapter is used then the messages are only as resilient as the memory. Memory may be a much faster medium than disk but is highly volatile compared to disk. Hence the choice of adapter is an important one.

If you do not provide message store information when creating a queue, it defaults to the message store that was specified when the queue manager was created.

Take the following into consideration when setting the Queue_FileDesc field:

Creating a local queue

The following code fragment demonstrates how to create a local queue:

/**
 * Create a new local queue 
 */
protected void createQueue(MQeQueueManager localQM,
                           String          qMgrName,       
                           String          queueName,
                           String          description,
                           String          queueStore
 	) throws Exception
{
  /*
   * Create an empty queue admin message and parameters field
   */
  MQeQueueAdminMsg msg = new MQeQueueAdminMsg();
  MQeFields parms = new MQeFields();
 
  /*
   * Prime message with who to reply to and a unique identifier
   */
  MQeFields msgTest = primeAdminMsg( msg );
 
  /*
   * Set name of queue to manage
   */
  msg.setName( qMgrName, queueName );
 
  /*
   * Add any characteristics of queue here, otherwise
   * charateristics will be left to default values.
   /
  if ( description != null )	// set the description ?
    parms.putUnicode( MQeQueueAdminMsg.Queue_Description, 
                      description);
 
  if ( queueStore != null ) 	// Set the queue store ?
    // If queue store includes directory and file info then it
    // must be set to the correct style for the system that the
    // queue will reside on e.g \ or /
    parms.putAscii(MQeQueueAdminMsg.Queue_FileDesc, 
                   queueStore );
  /* 
   * Other queue characteristics like queue depth, message expiry
   * can be set here ...
   */
 
  /*
   * Set the admin action to create a new queue
   */
  msg.create( parms );
 
  /*
   *  Put the admin message to the admin queue (not assured delivery)
   */
  localQM.putMessage( qMgrName, 
                      MQe.Admin_Queue_Name, 
                      msg, 
                      null, 
                      0);
}
 
 

Queue security

Access and security are owned by the queue and may be granted for use by a remote queue manager (when connected to a network), allowing these other queue managers to send or receive messages to the queue. The following characteristics are used in setting up queue security:

Other queue characteristics

You can configure queues with many other characteristics such as the maximum number of messages that are permitted on the queue. For a description of these, see the MQeQueueAdminMsg section of the WebSphere MQ Everyplace Java Programming Reference.

Aliases

Queue names can have aliases similar to those described for connections in Aliases. The code fragment in the connections section alias example shows how to setup aliases on a connection, setting up aliases on a queue is the same except that an MQeQueueAdminMsg is used instead of an MQeConnectionAdminMsg.

Action restrictions

Certain administrative actions can only be performed when the queue is in a predefined state, as follows:

Action_Update

Action_Delete
The queue cannot be deleted if the queue is in use or if there are messages on the queue

If the request requires that the queue is not in use, or that it has zero messages, the administration request can be retried, either when the queue manager restarts or at regular time intervals. See The basic administration request message for details on setting up an administration request retry.

Home-server queue

Home-server queues are implemented by the MQeHomeServerQueue class. They are managed with the MQeHomeServerQueueAdminMsg class which is a subclass of MQeRemoteQueueAdminMsg. The only addition in the subclass is the Queue_QTimerInterval characteristic. This field is of type int and is set to a millisecond timer interval. If you set this field to a value greater than zero, the home-server queue checks the home server every n milliseconds to see if there are any messages waiting for collection. Any messages that are waiting are delivered to the target queue. A value of 0 for this field means that the home-server is only polled when the MQeQueueManager.triggertransmission method is called

Note:
If a home-server queue fails to connect to its store-and-forward queue (for instance if the store-and-forward queue is unavailable when the home server queue starts) it will stop trying until a trigger transmit call is made.

Figure 14. Home-server queue

top

The name of the home-server queue is set as follows:

The queue manager where the home-server queue resides must have a connection configured to the home-server queue manager.

Figure 14 shows an example of a queue manager qm3 that has a home-server queue SFQ configured to collect messages from its home-server queue manager qm2.

The configuration consists of:

Any messages that are directed to queue manager qm3 through qm2 are stored on the store-and-forward queue SFQ on qm2 until the home-server queue on qm3 collects them.

WebSphere MQ bridge queue

A WebSphere MQ bridge queue is a remote queue definition that refers to a queue residing on a WebSphere MQ queue manager. The queue holding the messages resides on the WebSphere MQ queue manager, not on the local queue manager.

Figure 15. WebSphere MQ bridge queue

Diagram showing the use of an WebSphere MQ bridge queue described in detail below.

The definition of the bridge queue requires that bridge, WebSphere MQ queue manager proxy, and client connection names are specified to uniquely identify a client connection object in the bridge object hierarchy. Refer to Figure 47 for more information. This information identifies how the WebSphere MQ bridge accesses the WebSphere MQ queue manager, to manipulate a WebSphere MQ queue.

The WebSphere MQ bridge queue provides the facility to put to a queue on a queue manager that is not directly connected to the WebSphere MQ bridge. This allows a message to be sent to a WebSphere MQ queue manager (the target) routed through another WebSphere MQ queue manager. The WebSphere MQ bridge queue takes the name of the target queue manager and the intermediate queue manager is named by the WebSphere MQ queue manager proxy.

For a complete list of the characteristics used by the WebSphere MQ bridge queue, refer to MQeMQBridgeQueueAdminMsg in the com.ibm.mqe.bridge section of WebSphere MQ Everyplace Java Programming Reference.

Table 10 details the list of operations supported by the WebSphere MQ bridge queue, once it has been configured:

Table 10. Message operations supported by WebSphere MQ--bridge queue

Type of operation Supported by WebSphere MQ bridge queue
getMessage() yes*
putMessage() yes
browseMessage() Yes*
browseAndLockMessage no
Note: * These functions have restrictions on their use. Refer to Chapter 4, Messaging, of the WebSphere MQ Everyplace Application Programming Guide.

If an application attempts to use one of the unsupported operations, an MQeException of Except_NotSupported is returned.

When an application puts a message to the bridge queue, the bridge queue takes a logical connection to the WebSphere MQ queue manager from the pool of connections maintained by the bridge's client connection object. The logical connection to WebSphere MQ is supplied by either the WebSphere MQ Java Bindings classes, or the WebSphere MQ Classes for Java. The choice of classes depends on the value of the hostname field in the WebSphere MQ queue manager proxy settings. Once the WebSphere MQ bridge queue has a connection to the WebSphere MQ queue manager, it attempts to put the message to the WebSphere MQ queue.

An WebSphere MQ bridge queue must always have an access mode of synchronous and cannot be configured as an asynchronous queue. This means that, if your put operation is directly manipulating an WebSphere MQ bridge queue and returns success, your message has passed to the WebSphere MQ system while your process was waiting for the put operation to complete.

If you do not wish to use synchronous operations against the WebSphere MQ bridge queue, you may set up an asynchronous remote queue definition that refers to the WebSphere MQ bridge queue. Refer to Chapter 7, Message Delivery, of the WebSphere MQ Everyplace Application Programming Guide for information on asynchronous message delivery. Alternatively, you can set up a store-and-forward queue, and home-server queue. These two alternative configurations provide the application with an asynchronous queue to which it can put messages. With these configurations, when your putMessage() method returns, the message may not necessarily have passed to the WebSphere MQ queue manager.

An example of WebSphere MQ bridge queue usage is described in Configuration example.

Administration queue

The administration queue is implemented in class MQeAdminQueue and is a subclass of MQeQueue so it has the same features as a local queue. It is managed using administration class MQeAdminQueueAdminMsg.

If a message fails because the resource to be administered is in use, it is possible to request that the message be retried. The basic administration request message provides details on setting up the maximum number attempts count. If the message fails due to the managed resource not being available and the maximum number of attempts has not been reached, the message is left on the queue for processing at a later date. If the maximum number of attempts has been reached, the request fails with an MQeException. By default the message is retried the next time the queue manager is started. Alternatively a timer can be set on the queue that processes messages on the queue at specified intervals. The timer interval is specified by setting the long field Queue_QTimerInterval field in the administration message. The interval value is specified in milliseconds.



© IBM Corporation 2002, 2003. All Rights Reserved