Configuring the message service  Viewing messages and statistics

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 31, “Using the Message Service,” in the EAServer Programmer’s Guide for more information. You can also use EAServer 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 EAServer 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.

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

StepsConfiguring 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 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. The properties are defined in Table 8-1.

Table 8-1: Message queue properties

Property

Datatype

Default value

Description

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.

maximum

long

0

The maximum number of messages held in memory for an active queue. When the limit is reached, messages are discarded in the order that they would have been retrieved.

The default of 0, or a negative size value, specifies that there is no limit on the number of transient messages in the queue. In this case, the number of persistent messages in the queue is limited by the default.maximum setting in the MessageServiceConfig.props file—see “Configuring the message service”.

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.

qop

string

“none”

Indicates the quality of protection required for the message queue object.

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.

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.

table

string

“none”

To save the queue’s messages in a database table other than message_queue, enter the table name.

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.

StepsDeactivating a message queue

  1. Select Active Queues.

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

StepsDeleting all the messages in a queue

  1. Select Active Queues.

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

StepsDeleting a message queue

  1. Select Configured Queues.

  2. Remove any listeners attached to the queue as follows:

    1. Highlight the message queue, and select File | Properties.

    2. In the Properties dialog box, select the Listeners tab.

    3. Highlight the listener name and click Delete.

  3. Right-click the queue and select Delete.

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

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

StepsDeleting a topic

  1. Select Configured Topics.

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

NoteThe 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 EAServer Manager and as output from some jagtool commands. You cannot change the configuration of the <system> thread pool. You can change some properties of the <system> message queue, but only by changing the settings in the MessageServiceConfig.props file—see “Configuring the message service”.


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.

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

StepsConfiguring 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 Properties.

  3. Select the Configuration tab and enter the connection factory properties described in Table 8-2.

    Table 8-2: 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.

    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.

    THREAD_POOL

    string

    blank

    The message service uses threads from this thread pool for client notification. Using a thread pool can significantly improve performance.

    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.

StepsAdding 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, and select File | 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 31, “Using the Message Service,” in the EAServer Programmer’s Guide for more information.

  6. Click OK.

StepsDeleting 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, and select File | 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 31, “Using the Message Service,” in the EAServer Programmer’s Guide.

StepsInstalling 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, and select File | Properties.

  3. In the Queue 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[threadpool_name]
    

    where package_name is the package name, component_name is the component name, and threadpool_name is an optional thread pool name. You can create thread pools in EAServer Manager as described in “Thread pools”. The thread pool must have one or more worker threads.

    NoteA thread pool with multiple worker threads enables the message listener to process multiple messages at the same time.

    If you do not specify the name of a thread pool, the message listener uses the <system> default thread pool, which has a single worker thread.

  6. Click OK.

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

StepsConfiguring 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
  {
    ...
  }
};

StepsDeleting 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, and select File | 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 message queues and topics, add one or more access roles. If more than one access role is assigned to a message queue or topic, a client must possess only one of the roles to access the queue or topic. If a message queue or topic has no assigned roles, any client can access it.

StepsAdding 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, and select File | 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.

StepsDeleting 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, and select File | 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.

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

NoteReader, 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.

StepsModifying the number of threads in a thread pool

  1. Select Thread Pools.

  2. Select a thread pool from the list, and select File | 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 EAServer Manager, highlight the MDB, and select File | 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 31, “Using the Message Service,” in the EAServer Programmer’s Guide for more information about configuring MDBs.

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

StepsViewing 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 © 2005. Sybase Inc. All rights reserved. Viewing messages and statistics