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 – add one message queue for each message recipient. To identify the subject of messages to which you want to subscribe, add message topics. You can also create message queues and topics using the CORBA API or the Java Message Service (JMS) createQueue and createTopic methods. Although these JMS methods are not portable, creating message queues and topics programmatically can significantly reduce the system administrator’s work.

• Connection factories – queue connection factories enable JMS client applications to establish point-to-point (PTP) connections with the message service. Topic connection factories enable JMS client applications to establish publish/subscribe (Pub/Sub) connections with the message service.

• Message selectors – to specify which messages you want to receive, add message selectors to message queues.

• Message listeners – to provide asynchronous message notification for clients and components, implement a message listener, and install it on a message queue.

• Access roles – to restrict access to a message queue or to grant one user access to another user’s queue, add access roles to the message queue. To restrict access to messages with particular topics, add access roles to the topic.

• Thread pools – define thread pools to handle client and component notification.

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.

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.

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

Deactivating a message queue

1. Select Active Queues.

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

Deleting all the messages in a queue

1. Select Active Queues.

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

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

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.

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

Deleting a topic

1. Select Configured Topics.

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

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.

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.

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

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

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, 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:

• An EJB 2.0 message-driven bean (MDB) that implements the javax.jms.MessageListener interface, or

• An EAServer class that implements the CtsComponents::MessageListener interface; this is called an EAServer message listener.

For information on how to implement, install, and configure an MDB, see Chapter 31, “Using the Message Service,” in the EAServer Programmer’s Guide.

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

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

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

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

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, 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:

   • Consumer To receive messages from the queue, or to receive messages with the specified topic.

   • Producer To publish or send messages to the queue, or to publish or send messages with the specified topic.

   • Security To administer roles for the message queue or topic.

7. Click OK.

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

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.

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

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.

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 © 2005. Sybase Inc. All rights reserved.