Chapter 8 Setting up the Message Service

Adding and configuring the message service parts

Once you have configured the message service, you can perform all administrative tasks using the CtsComponents::MessageService CORBA API--see Chapter 29, "Using the Message Service," in the EAServer Programmer's Guide for more information. You can also use Jaguar Manager to add and configure the message service parts:

Permanent destinations

To provide permanent destinations for JMS client applications, define message queues and message topics using Jaguar Manager. When you create a permanent destination, you can optimize its configuration properties, which benefits every JMS client application that uses the destination. Message queues and topics are both called message consumers.

Steps Adding a message queue

  1. Highlight Configured Queues, right-click, and select Add.
  2. In the New Queue dialog box, enter a name for the message queue.
  3. Click OK.

Steps Configuring a message queue's properties

  1. To edit properties for an active queue, select Active Queues; to edit properties for an inactive queue, select Configured Queues.
  2. Select a queue from the list, right-click, and select Message Properties.
  3. In the Queue Properties dialog box, select the Configuration tab.
  4. To edit a configuration property, click on its property value. The Modify Property dialog box opens.
  5. Edit the property value and click OK.
Property Datatype Default value Description
REQUIRES_ACKNOWLEDGE boolean false Set to true to guarantee that each persistent message is delivered at least once. Transient messages may be lost if a server fails.
REQUIRES_TRANSACTION boolean false Set to true to guarantee that a persistent message is delivered only once, which means that only one transaction can receive the message and successfully commit.
IGNORE_DUPLICATE_KEY boolean false Set to true to avoid duplicate messages when the message producer sends a message outside a transaction or forwards a message from a remote system. You can use this option with the CORBA API, where you can specify the message key before producing a message.
table string "none" To save the queue's messages in a database table other than message_queue, enter the table name.
maximum long 0 The maximum number of messages held in memory for an active queue; if set to zero or a negative number, there is no limit. When the limit is reached, messages are discarded in the order that they would have been retrieved.

If a persistent message is discarded from memory, you can still retrieve it from the database. Transient messages are not stored in the database, so if they are discarded from memory, they are lost.
timeout long 0 The number of seconds the queue remains in memory when it is not being accessed by a client and it has no registered listener; set to zero or a negative number for no timeout. Any transient messages that are in memory when a timeout occurs are discarded.
share boolean true Indicates whether multiple clients can simultaneously receive messages from the queue. When a queue is not shared, only one client at a time can receive messages from it. If other clients try to receive a message, they get an OBJECT_NOT_EXIST system exception.
store boolean true Indicates whether to store replicated transient messages that are added to the queue. To avoid duplicate message processing within a cluster where a shared queue may reside in memory on multiple servers, set to true.
qop string "none" Indicates the quality of protection required for the message queue object.

Steps Deactivating a message queue

  1. Select Active Queues.
  2. Select a queue from the list, right-click, and select Close.

Steps Deleting all the messages in a queue

  1. Select Active Queues.
  2. Select a queue from the list, right-click, and select Flush.

Steps Deleting a message queue

  1. Select Configured Queues.
  2. Select a queue from the list, right-click, and select Delete.

Steps Adding a topic

  1. Highlight Configured Topics, right-click, and select Add.
  2. In the New Topic dialog box, enter the topic name.
  3. Click OK.

Steps Configuring a topic

  1. To configure an active topic, select Active Topics; to configure an inactive topic, select Configured Topics.
  2. Select a topic from the list, right-click, and select Topic Properties.
  3. In the Topic Properties dialog box, select the Configuration tab.
  4. To edit the timeout property, click on the property value. A Modify Property dialog box opens.
  5. Edit the timeout value and click OK.
Property Datatype Default value Description
timeout long 0 Indicates the number of seconds the topic remains in memory when no active queues have selectors registered for the topic; set to zero or a negative number for no time out. Topics with no timeout are activated at server start-up.

Steps Deleting a topic

  1. Select Configured Topics.
  2. Select a topic from the list, right-click, and select Delete.

Note   The message service includes a message queue and a thread pool called "<system>" for tasks that require internal messaging, such as synchronizing a cluster. The <system> message queue and thread pool are visible in Jaguar Manager and as output from some jagtool commands.

Connection factories

To enable JMS applications to establish connections with the message service, create queue connection factories for PTP messaging, and create topic connection factories for Pub/Sub messaging.

Steps Adding a queue or topic connection factory

  1. To add a queue connection factory, select Queue Connection Factory; to add a topic connection factory, select Topic Connection Factory.
  2. Right-click and select Add.
  3. Enter a name for the connection factory and click OK.

Steps Configuring a connection factory's properties

  1. Select either Queue Connection Factory or Topic Connection Factory.
  2. Highlight the connection factory you want to configure, right-click, and select Connection Factory Properties.
  3. Select the Configuration tab and enter the connection factory properties:
    Property Datatype Default value Description
    CLIENT_ID string blank Used for topic connection factories only. It enables EAServer to uniquely identify a client if it disconnects and later reconnects. Every connection that is created using this connection factory inherits this ID. The CLIENT_ID is ignored for queue connections.
    CONFIG_QUEUE string blank When you access a queue or topic, its configuration properties are copied from this named queue.
    THREAD_POOL string blank The message service uses threads from this thread pool for client notification. Using a thread pool can significantly improve performance.
    IGNORE_DUPLICATE_KEY boolean true Indicates whether a message should be ignored if it is a duplicate.
    NO_IMPLICIT_CREATION boolean true Indicates whether a queue or topic that does not already exist should be implicitly created when a client attempts to access it.
    REQUIRES_ACKNOWLEDGE boolean false To optimize the performance of a JMS application, set to false. In this case, the message service does not acknowledge messages. If a connection terminates unexpectedly, messages may be lost.
    REQUIRES_TRANSACTION boolean true To force the methods publish, send, receive, and onMessage to participate in transactions, set to true. To improve throughput for bulk publishing, sending, or receiving transient messages, set to false.

    For information about using transactions, see Chapter 2, "Understanding Transactions and Component Lifecycles," in the EAServer Programmer's Guide.
    SHARED_LISTENER boolean false When set to true, all message consumers for a connection use the same message listener.

    A shared listener can greatly improve performance for nondurable topic subscribers by creating a single message queue for all the topic subscriptions. To use this feature, install a message listener on the first topic subscription, then each nondurable subscription that uses the connection, receives messages from this listener.

    EAServer imposes two restrictions for shared listeners:
    • Do not call setMessageListener with a null parameter. This shuts down the current listener, which may be in use by other subscribers.
    • Do not call setMessageListener with the name of another listener, which shuts down the current listener and register the new listener.
    SUPPORTS_TRANSACTION boolean true Determines whether JMS publish, send, receive, and onMessage calls use the SUPPORTS_TRANSACTION option.

    If you set this to false, it significantly improves throughput for transient message bulk processing.
    TRANSPARENT_FAILOVER boolean true Indicates whether JMS clients should allow transparent failover for message service operations. If set to false, a pinned object is used. If set to true, carefully consider the IGNORE_DUPLICATE_KEY setting.

Message selectors

To filter the messages you receive and to subscribe to specific message topics, add message selectors. You can add as many selectors as you want to each message queue.

Steps Adding a message selector

  1. If you are adding a selector to an active queue, select Active Queues; if you are adding a selector to an inactive queue, select Configured Queues.
  2. Select a message queue from the list, right-click, and select Queue Properties.
  3. In the Queue Properties dialog box, choose the Selectors tab.
  4. Click Add.
  5. In the New Selector dialog box, enter the selector. For example, to receive all published messages with the topic "StockPrice.SY", add this selector to the message queue: 
    StockPrice.SY


    A selector is an expression that contains an equality condition for a topic and possibly other conditions. Selectors must conform to the JMS selector specification, which is a subset of the SQL-92 syntax. See Chapter 29, "Using the Message Service," in the EAServer Programmer's Guide for more information.
  6. Click OK.

Steps Deleting a message selector

  1. If you are deleting a selector from an active queue, select Active Queues; if you are deleting a selector from an inactive queue, select Configured Queues.
  2. Select a message queue from the list, right-click, and select Queue Properties.
  3. In the Properties dialog box, click on the Selectors tab.
  4. Choose a selector from the list and click Delete.

Listeners

To provide asynchronous message notification, implement and install a message listener on a message queue. A message listener can be either:

For information on how to implement, install, and configure an MDB, see Chapter 29, "Using the Message Service," in the EAServer Programmer's Guide.

Steps Installing an EAServer message listener

  1. To install a listener on an active queue, select Active Queues; to install a listener on an inactive queue, select Configured Queues.
  2. Select a message queue from the list, right-click and select Properties.
  3. In the Properties dialog box, select the Listeners tab.
  4. Click Add.
  5. In the New Listener dialog box, enter a listener (component) that has been installed in EAServer. Use this format: package_name/component_name.
  6. Click OK.

Before you install the message listener component, configure it to support the MessageListener interface.

Steps Configuring a component to support the CtsComponents::MessageListener interface

  1. Select EAServer | Installed Packages | package_name | component_name, where package_name/component_name is the name of an installed message listener.
  2. Under the component, select Interfaces. Right-click and select Add Interfaces. This displays the Install Interfaces dialog box.
  3. In the Available IDL Interfaces drop-down list, select CtsComponents. This displays the list of CtsComponents interfaces.
  4. Select CtsComponents::MessageListener, and click Add. This moves the interface name to the Selected to Install list.
  5. Click Install.

Alternately, you can use the IDL editor and modify your component's existing interface to inherit from CtsComponents::MessageListener; for example: 

module msglistener
{
  interface Receiver : ::CtsComponents::MessageListener
  {
    ...
  }
};

Steps Deleting an EAServer message listener

  1. To delete a listener from a message queue, select either Active Queues or Configured Queues.
  2. Select a message queue from the list, right-click and select Properties.
  3. In the Properties dialog box, select the Listeners tab.
  4. Choose a listener from the list and click Delete.

Access roles

To control access to a message queue or topic, add one or more access roles. If more than one access role is assigned to a message consumer, a client needs to possess only one of the roles to access the queue or topic. If a message consumer has no assigned roles, any client can access it.

Steps Adding an access role

  1. To add an access role to a message consumer, select the appropriate folder:
    Message consumer Folder title
    Active queue Active Queues
    Inactive queue Configured Queues
    Active topic Active Topics
    Inactive topic Configured Topics
  2. Select a queue or topic from the list, right-click, and select Add.
  3. In the Properties dialog, select the Roles tab.
  4. Click Add.
  5. In the New Role dialog box, enter the role name. You can use a wildcard character ("*") when the queue or topic does not require a specific role. For subtopics that do not require a specific role, the name can end with the wildcard character; for example "StockPrice.*".
  6. Select the role type:
  7. Click OK.

Steps Deleting an access role from a message queue or topic

  1. To delete an access role from a message consumer, select the appropriate folder:
    Message consumer Folder title
    Active queue Active Queues
    Inactive queue Configured Queues
    Active topic Active Topics
    Inactive topic Configured Topics
  2. Select a message queue or topic from the list, right-click, and select Properties.
  3. In the Properties dialog box, select the Role tab.
  4. Select a role from the list and click Delete.

Thread pools

To provide asynchronous client and component notification, define thread pools and specify the number of threads dedicated to each type of notification.

Steps Adding a thread pool

  1. Select Thread Pools, right-click, and select Add.
  2. In the New Thread Pool dialog box, enter the name of the thread pool.
  3. Click OK.

Note  

Reader, writer, and worker threads To use a thread pool for client notification, set the value of readers to "3", writers to "2", and workers to "0". Based on your own performance measurements, increase the number of reader and writer threads if it improves throughput. Using thread pools to improve performance is generally suitable only for high-volume client notification with transient messages. When message delivery is transactional or IIOP/SSL via the QOP property, the thread pool's reader and writer threads are not used.

To use a thread pool for component notification, set the values of both readers and writers to "0". Set the value of workers to "1" unless you want to allow parallel message processing, in which case you would increase this value.

Steps Modifying the number of threads in a thread pool

  1. Select Thread Pools.
  2. Select a thread pool from the list, right-click, and select Thread Pool Properties.
  3. In the Thread Pool Properties dialog box, select the Configuration tab.
  4. To edit the number of threads, click on one of the property values.
    Property Datatype Default value Description
    readers long 0 The number of reader threads in the thread pool, which are used for client notification.
    writers long 0 The number of writer threads in the thread pool, which are used for client notification.
    workers long 0 The number of worker threads in the thread pool, which are used for component notification.
  5. Modify the property value and click OK.

Multiple MDB instances

To enable EAServer to create multiple instances of a message-driven bean (MDB):

  1. Create a thread pool for component notification, and set the workers property to a value greater than 1.
  2. Assign this thread pool to the MDB:
    1. In Jaguar Manager, highlight the MDB, and select File | Component Properties.
    2. On the MDB Type tab, append the name of the thread pool you just created to the Listener name. For example, if you created a thread pool called "threads1" and the Listener Name is MyPkg/MyComp, change the Listener Name to MyPkg/MyComp[threadsl] .
    See Chapter 29, "Using the Message Service," in the EAServer Programmer's Guide for more information about configuring MDBs.

Steps Deleting a thread pool

  1. Select Thread Pools.
  2. Select a thread pool from the list, right-click, and select Delete.

Dead queue

If the message service cannot deliver a message, it moves the message to the dead message queue. You can view a list of these messages, delete them, or resend them to their original destination.

Steps Viewing the dead message queue

  1. Select Dead Queues.
  2. To see a list of the dead messages, select Dead Queue from the list, right-click, and select List.

    To resend a dead message, select a message from the list and click Send.
  3. To delete the dead messages, select Dead Queue from the list, right-click, and select Delete All Dead Messages.

 

Copyright © 2002 Sybase, Inc. All rights reserved.