Creating a New JMS Control

This topic describes how to create a new JMS control.

To learn about JMS controls, see JMS Control: Using Java Message Service Queues and Topics from Your Web Service.

To learn about WebLogic Workshop controls, see Controls: Using Resources from a Web Service.

# Creating a New JMS Control

You can create a new JMS control and add it to your web service by using the Add JMS Control Dialog. The Add JMS Control Dialog can be accessed via the Service menu on the Menu Bar; via the right-button context menu on the service in the Design View; or via the Add Control option menu in the upper right corner of Design View.

To learn more about the Add JMS Control Dialog, see Add JMS Control Dialog.

Alternatively, you may create a JMS control CTRL file manually. For example, you may copy an existing JMS control CTRL file and modify the copy.

## The CTRL File for JMS Control

If you create a new JMS control CTRL file using the Add JMS Control dialog with the settings shown above, the new CTRL file will look like this:

    import weblogic.jws.control.JMSControl;
    import java.io.Serializable;
    /**
     *   @jws:jms type="queue" send-jndi-name="jms.SimpleJmsQ" receive-jndi-name="jms.SimpleJmsQ"
     *   connection-factory-jndi-name="weblogic.jws.jms.QueueConnectionFactory"
     */
    public interface SimpleQueueControl extends JMSControl
    {
        /**
         * this method will send a javax.jms.TextMessage to send-jndi-name
         */
        public void sendTextMessage(String payload);
        /**
         * If your control specifies receive-jndi-name, that is your JWS expects to receive messages
         * from this control, you will need to implement callback handlers.
         */
        interface Callback extends JMSControl.Callback
        {
            /**
             * Define only 1 callback method here.
             *
             * This method defines a callback that can handle text messages from receive-jndi-name
             */
             public void receiveTextMessage(String payload);
        }
    }

The CTRL file contains the declaration of a Java interface with the name specified in the dialog. The interface extends the JMSControl base interface.

The contents of the JMS control's CTRL file depend on the selections made in the Add JMS Control dialog. The example above was generated in response to selection of Text as the Message type drop-down list.

## Configuring the Properties of a JMS Control

Most aspects of a JMS control can be configured from the Properties Pane in Design View. If you select a JMS control instance in Design View, the Properties Pane will display the following properties:

These properties are encoded in the JMS control's CTRL file as attributes of the @jws:jms Javadoc tag.

For detailed information on the @jws:jms tag and its attributes, see @jws:jms Tag.

To learn how to create, configure and register JMS queues, topics and connection factories, please consult the WebLogic Server documentation on Programming WebLogic JMS.

Two queues are configured when WebLogic Workshop is installed, in order to support JMS control samples. These are named SimpleJmsQ and CustomJmsCtlQ. The connection factory that provides connections to these queues has the JNDI name weblogic.jws.jms.QueueConnectionFactory. These resources may be used for experimentation.

Note: Every JMS control deployed on a server should listen on a unique queue. If multiple JMS controls on the same server are simultaneously listening on the same queue, the results may be unpredictable. See the JMS Control Caveats section below for more information.

## Adding a Method or Callback in Design View

If you are editing a web service in Design View and you wish to add a method or callback to a JMS control your web service is using, you may add the method directly by right-clicking on the JMS control instance in Design View.

In the example above, the CustomJMSClient web service is using a JMS control whose instance name is myCustomQ. Right-clicking on the myCustomQ object will present a menu that contains the Add Method and Add Callback actions. Select the Add Method action to add a method to the JMS control of which myCustomQ is an instance. Select the Add Callback action to add a callback to the JMS control of which myCustomQ is an instance.

Note: The JMS control variable declared in a web service's JWS file is an instance of a JMS control. The actual control is defined in a CTRL file. When you add a method or callback to a JMS control from Design View, the method or callback is added to the CTRL file. The method or callback will subsequently be available in all web services that are using that JMS control.

Note: You are free to remove the default method and/or callback in a JMS control.

Note: A JMS control may define only one callback.

When a method or callback is added, it will initially have no parameters and no associated XML maps.

# Specifying the Format of The Message Body

Within a JMS control, you may define multiple methods and one callback. All methods will send or publish to the queue or topic named by send-jndi-name, if present.

JMS defines several message types that may be sent and or published. The JMS control can send the JMS message types TextMessage, ObjectMessage and Message. The JMS control dynamically determines which type of message to send based on the configuration of the JMS control method that was called.

If the JMS control method takes any XML map (@jws:jms-message, @jws:jms-header or @jws:jms-property), a TextMessage is sent containing the payload, headers and properties specified by the XML maps. To learn how to use XML maps to control the message payload, see Sending and Receiving XML Messages with a JMS Control.

If the JMS control method takes a single String argument and has no XML maps, a TextMessage is sent.

If the JMS control method takes a single argument of a type other than String or javax.jms.Message and has no XML maps, an ObjectMessage is sent.

If the JMS control method takes a single argument of type javax.jms.Message and has no XML maps, that Message object is sent directly.

# Specifying Message Headers and Properties

To edit the parameter list and associated XML maps controlling the message headers and message properties, see Manipulating JMS Message Headers and Message Properties in a JMS Control.

# Accessing Remote JMS Resources

The JNDI names specified for send-jndi-name, receive-jndi-name and connection-factory may refer to remote JMS resources. The fully specified form of a JMS resource names is:

jms:{provider-host}/{factory-resource}/{dest-resource}?{provider-parameters}

For example:

jms://host:7001/cg.jms.QueueConnectionFactory/jws.MyQueue?URI=/drt/Bank.jws

or:

jms://host:7001/MyProviderConnFactory/MyQueue?SECURITY_PRINCIPAL=foo&SECURITY_CREDENTIALS=bar

# JMS Control Caveats

Bear in mind the following caveats when you work with JMS controls:

- If you have multiple web services (multiple types, not instances) that reference the same receive-jndi-name for a queue, you must use the receive-selector attribute such that the web services partition all received messages into disjoint sets. If this is not handled properly, messages for a particular conversation may be sent to a control instance that does not participate in that conversation. Note that if you rename a web service that uses a JMS control without undeploying the initial version, the initial version and the new version will be using an identically configured JMS control and will violate this caveat.

- You may have only one callback defined for any JMS control instance (receiveTextMessage, receiveMessage, receiveObjectMessage or receiveJMSMesage, or a developer-defined callback).

- If the underlying JMS control infrastructure receives a message that it cannot deliver to a control instance (e.g. no conversation ID for a control that listens to a queue), it will throw an exception from the JMSControl.onMessage method. This will cause the current transaction to be rolled back. The behavior after that depends on how the administrator set up the JMS destination. Ideally, it should be set up to have a small retry count and an error destination.

Note: If the destination is configured with a large (or no) retry count and no error destination, the JMS control infrastructure will continue attempting to process the message (unsuccessfully) forever.

Related Topics

Overview: Messaging Systems and JMS

@jws:jms-header Tag

@jws:jms-property Tag

@jws:jms-message Tag

JMSControl Interface