Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic JMS

# Using Multicasting with WebLogic Server

Multicasting enables the delivery of messages to a select group of hosts that subsequently forward the messages to subscribers. The following sections provide information on the benefits, limitations, and configuration of using mutlticasing with WebLogic Server:

- Benefits of using Multicasting
- Limitations of using Multicasting
- Configuring Multicasting for WebLogic Server

# Benefits of using Multicasting

The benefits of multicasting include:

- Near real-time delivery of messages to host group.
- High scalability due to the reduction in the amount of resources required by the JMS server to deliver messages to subscribers.

# Limitations of using Multicasting

The limitations of multicasting include:

- Multicast messages are not guaranteed to be delivered to all members of the host group. For messages requiring reliable delivery and recovery, you should not use multicasting.
- For interoperability with different versions of WebLogic Server, clients cannot have an earlier release of WebLogic Server installed than the host. They must all have at least the same version or higher.

For an example of when multicasting might be useful, consider a stock ticker. When accessing stock quotes, timely delivery is more important than reliability. When accessing the stock information in real-time, if all or a portion of the contents is not delivered, the client can simply request the information to be resent. Clients would not want to have the information recovered, in this case, as by the time it is redelivered, it would be out-of-date.

# Configuring Multicasting for WebLogic Server

The following figure illustrates the steps required to set up multicasting.

Figure 7-1 Setting Up Multicasting

Note: Multicasting is only supported for the Pub/Sub messaging model, and only for non-durable subscribers.

Monitoring statistics are not provided for multicast sessions or consumers.

## Prerequisites for Multicasting

Before setting up multicasting, the connection factory and destination must be configured to support multicasting, as follows:

- For each connection factory, the system administrator configures the maximum number of outstanding messages that can exist on a multicast session and whether the most recent or oldest messages are discarded in the event the maximum is reached. If the message maximum is reached, a `DataOverrunException` is thrown, and messages are automatically discarded. These attributes are also dynamically configurable, as described in Dynamically Configuring Multicasting Configuration Attributes.
- For each destination, the Multicast Address (IP), Port, and TTL (Time-To-Live) attributes are specified. To better understand the TTL attribute setting, see Example: Multicast TTL.

Note: It is strongly recommended that you seek the advice of your network administrator when configuring the multicast IP address, port, and time-to-live attributes to ensure that the appropriate values are set.

For more information, see "Configure topic multicast parameters" in the Administration Console Online Help.

## Step 1: Set Up the JMS Application, Creating Multicast Session and Topic Subscriber

Set up the JMS application as described in Setting Up a JMS Application. However, when creating sessions, as described in Step 3: Create a Session Using the Connection, specify that the session would like to receive multicast messages by setting the `acknowledgeMode` value to `MULTICAST_NO_ACKNOWLEDGE`.

Note: Multicasting is only supported for the Pub/Sub messaging model for non-durable subscribers. An attempt to create a durable subscriber on a multicast session will cause a `JMSException` to be thrown.

For example, the following method illustrates how to create a multicast session for the Pub/Sub messaging model.

>     tsession = tcon.createTopicSession(
>      false,
>      WLSession.MULTICAST_NO_ACKNOWLEDGE
>     );

Note: On the client side, each multicasting session requires one dedicated thread to retrieve messages off the socket. Therefore, you should increase the JMS client-side thread pool size to adjust for this. For more information on adjusting the thread pool size, see the "Tuning Thread Pools and EJB Pools" section in the "WebLogic JMS Performance Guide" white paper, http://dev2dev.bea.com/resourcelibrary/whitepapers/index.jsp#server, which discusses tuning JMS client-side thread pools.

In addition, create a topic subscriber, as described in Create TopicPublishers and TopicSubscribers.

For example, the following code illustrates how to create a topic subscriber:

`tsubscriber = tsession.createSubscriber(myTopic);`

Note: The `createSubscriber()` method fails if the specified destination is not configured to support multicasting.

## Step 2: Set Up the Message Listener

Multicast topic subscribers can only receive messages asynchronously. If you attempt to receive synchronous messages on a multicast session, a `JMSException` is thrown.

Set up the message listener for the topic subscriber, as described in Receiving Messages Asynchronously.

For example, the following code illustrates how to establish a message listener:

>     tsubscriber.setMessageListener(this);

When receiving messages, WebLogic JMS tracks the order in which messages are sent by the destinations. If a multicast subscriber's message listener receives the messages out of sequence, resulting in one or more messages being skipped, a `SequenceGapException` will be delivered to the `ExceptionListener` for the session(s) present. If a skipped message is subsequently delivered, it will be discarded. For example, in the following figure, the subscriber is receiving messages from two destinations simultaneously.

Figure 7-2 Multicasting Sequence Gap

Upon receiving the "4" message from Destination 1, a `SequenceGapException` is thrown to notify the application that a message was received out of sequence. If subsequently received, the "3" message will be discarded.

Note: The larger the messages being exchanged, the greater the risk of encountering a SequenceGapException.

## Dynamically Configuring Multicasting Configuration Attributes

During configuration, for each connection factory the system administrator configures the following information to support multicasting:

- Messages maximum specifying the maximum number of outstanding messages that can exist on a multicast session.
- Overrun policy specifying whether recent or older messages are discarded in the event the messages maximum is reached.

If the messages maximum is reached, a `DataOverrunException` is thrown and messages are automatically discarded based on the overrun policy. Alternatively, you can set the messages maximum and overrun policy using the `Session` set methods.

The following table lists the `Session` set and get methods for each dynamically configurable attribute.

Table 7-1 Message Producer Set and Get Methods

Attribute | Set Method | Get Method
--- | --- | ---
Messages Maximum | `public void setMessagesMaximum( int messagesMaximum ) throws JMSException` | `public int getMessagesMaximum( ) throws JMSException`
Overrun Policy | `public void setOverrunPolicy ( int overrunPolicy ) throws JMSException` | `public int getOverrunPolicy( ) throws JMSException`

Note: The values set using the set methods take precedence over the configured values.

For more information about these `Session` class methods, see the weblogic.jms.extensions.WLSession Javadoc. For more information on these multicast configuration attributes, see "Configure topic multicast parameters" in the Administration Console Online Help.

## Example: Multicast TTL

Note: The following example is a very simplified illustration of how the Multicast TTL (time-to-live) destination configuration attribute impacts the delivery of messages across routers. It is strongly advised that you seek the assistance of your network administrator when configuring the multicast TTL attribute to ensure that the appropriate value is set.

The Multicast TTL is independent of the message time-to-live.

The following example illustrates how the Multicast TTL destination configuration attribute impacts the delivery of messages across routers.

For more information, see "Configure topic multicast parameters" in the Administration Console Online Help.

Consider the following network diagram.

Figure 7-3 Multicast TTL Example

In the figure, the network consists of three subnets: Subnet A containing the multicast publisher, and Subnets B and C each containing one multicast subscriber.

If the Multicast TTL attribute is set to 0 (indicating that the messages cannot traverse any routers and are delivered on the current subnet only), when the multicast publisher on Subnet A publishes a message, the message will not be delivered to any of the multicast subscribers.

If the Multicast TTL attribute is set to 1 (indicating that messages can traverse one router), when the multicast publisher on Subnet A publishes a message, the multicast subscriber on Subnet B will receive the message.

Similarly, if the Multicast TTL attribute is set to 2 (indicating that messages can traverse two routers), when the multicast publisher on Subnet A publishes a message, the multicast subscribers on Subnets B and C will receive the message.