# Supported and Unsupported Messaging Scenarios

The JMS control enables WebLogic Workshop applications to interact with messaging systems that provide a JMS implementation. This topic describes specific messaging scenarios that are supported by the JMS control, including sending messages to a queue, enabling two-way messaging with queues, publishing to a topic, and subscribing to a topic. It also describes the scenario of receiving unsolicited messages from a queue, which is not supported by the JMS control.

## Supported Messaging Scenarios

The JMS specification supports a wide variety of messaging scenarios. Some scenarios that are possible in standalone applications are not possible in the WebLogic Workshop environment.

The messaging scenarios in the following sections are supported by the JMS control. For descriptions of messaging scenarios that are not supported by the JMS control, see A Messaging Scenario Not Supported by the JMS Control below.

### Sending Messages to a Queue

An application can send messages to a JMS queue using a JMS control. The administrator who configures the target JMS queue determines the delivery guarantee policies, but in all cases the application does not receive a reply and the queue must exist and be registered in the JNDI registry in order to convey messages.

To send messages to a queue:

1. On the JMS control, specify the name of the target JMS queue by setting the value of the send-jndi-name attribute of the @jc:jms annotation. To learn how to create a JMS control, see Creating a New JMS Control.
2. From your application, call either the JMS control's default method (sendTextMessage, sendBytesMessage, sendObjectMessage or sendJMSMessage, depending on the message type selected when the control was created), or a custom method you have defined for the JMS control.

The following is an example of sending messages to a queue:

    public class MyService {

        /**
         *   @common:control
         */
        private MyQueueControl myQueue;

        /**
         * @common:operation
         */
        public void sendID(String personID)
        {
            myQueue.sendTextMessage( personID );
        }
    }

### Enabling Two-Way Messaging with Queues

Using a JMS control, an application can send messages to one queue and receive reply messages on another queue. A single JMS control might have both send and receive queues configured, and applications can then send and receive via the same control.

Two-way messaging requires that every received messages be correlated with the instance of the application that sent the original outgoing message. This correlation is typically managed for you by the JMS control, so no action is necessary on your part. To learn more about message correlation, see the explanation of the send-correlation-property and receive-correlation-property attributes for the @jc:jms annotation.

To enable two-way messaging with queues:

1. On the JMS control, specify the name of the JMS queue to which you want to send messages by setting the value of the send-jndi-name attribute on the @jc:jms annotation.

2. Specify the name of the JMS queue from which you want to receive messages by setting the value of the receive-jndi-name attribute on the @jc:jms annotation.

3. To send a message from your web service, call the JMS control's default method (sendTextMessage, sendBytesMessage, sendObjectMessage or sendJMSMessage depending on the message type selected when the control was created), or a custom method you have defined for the JMS control.

4. To be notified when messages are received on the receive queue, implement a callback handler for the JMS control’s callback (receiveTextMessage, receiveBytesMessage, receiveObjectMessage or receiveJMSMessage depending on the message type selected when the control was created), or a custom callback you have defined for the JMS control.

The following is an example enabling two-way messaging:

    public class MyService {

        /**
         *   @common:control
         */
        private MyQueueControl myQueue;

        /**
         * @common:operation
         */
        public void sendID(String personID) throws Exception
        {
            myQueue.sendTextMessage( personID );
        }

        myQueue_receiveTextMessage(String message)
        {
            // message has arrived from queue, perform desired operations
        }
    }

### Publishing to a Topic

A web service, using a JMS control, can publish messages to a JMS topic. The web service will not receive a reply. The topic must exist and be registered in the JNDI registry.

To publish to a topic:

1. On the JMS control, specify the name of the target JMS topic by setting the value of the send-jndi-name attribute of the @jc:jms annotation.

2. From your web service, call the JMS control's default method (sendTextMessage, sendMessage, sendObjectMessage or sendJMSMessage depending on the message type selected when the control was created); or a custom method you have defined for the JMS control.

The following is an example of publishing to a topic:

    public class MyService {

        /**
         *   @common:control
         */
        private MyTopicControl myTopic;

        /**
         * @common:operation
         */
        public void sendID(String personID) throws Exception
        {
            myTopic.sendTextMessage( personID );
        }
    }

### Subscribing to a Topic

A web service, using a JMS control, can subscribe to messages on a JMS topic as long as the topic exists and is registered in the JNDI registry. Only messages sent after the web service has subscribed to the topic will be received.

To subscribe to a topic:

1. On the JMS control, specify the name of the target JMS topic by setting the value of the receive-jndi-name attribute on the @jc:jms annotation.
2. From your application, call the JMS control's subscribe method.
3. To be notified when messages are received on the receive topic, implement a callback handler for the JMS control’s callback (receiveTextMessage, receiveMessage, receiveObjectMessage or receiveJMSMessage depending on the message type selected when the control was created); or a custom callback you have defined for the JMS control.
4. To automatically subscribe to a topic when the JMS control is first initialized, set the auto-topic-subscribe attribute of the @jc:jms annotation to true.
5. To stop being notified when messages are received on the receive topic, call the JMS control's unsubscribe method.

The following is an example of subscribing to a topic:

    public class TopicForwardingService {

       /**
         * @common:control

        */
        private MyTopicControl myTopic;

       /**
         * @common:operation
         * @jws:conversation phase=start
         */
        public void registerListener()
        {
            myTopic.subscribe();
        }

       /**
         * @common:operation
         * @jws:conversation phase="finish"
         */
        public void unregisterListener()
        {
            // This isn't strictly necessary, the JWS will always
            // be unsubscribed on conversation finish.
            myTopic.unsubscribe();
        }

       myTopic_receiveTextMessage(String message)
        {
            // message has arrived from queue, perform desired operations
        }
    }

## A Messaging Scenario Not Supported by the JMS Control

Some scenarios that are possible in standalone applications are not possible in the WebLogic Workshop environment. The following messaging scenario is not supported by the JMS control.

### Receiving Unsolicited Messages from a Queue

An application, via a JMS control, specifies a receive queue and subsequently receives unsolicited messages from that queue. An application must be performing work on behalf of a specific client and, in asynchronous situations, as part of a specific conversation. When an unsolicited message is received from a queue, it is not possible for the JMS control to determine the appropriate conversation or client with which to correlate unsolicited incoming messages.

Note: You can receive unsolicited messages in a web service, but the web service must be a direct JMS client (that is, it must not be using a JMS control for the queue in question). To learn how to use JMS directly, please consult the WebLogic Server documentation topic "Programming WebLogic JMS".

Related Topics

JMS Control

Using WebLogic Built-In Controls

Overview: Messaging Systems and JMS

@jc:jms Annotation

@jc:jms-headers Annotation

@jc:jms-property Annotation