# Creating a New WLI JMS Control

This topic describes how to create a new WLI JMS control.

To learn about WLI JMS controls, see WLI JMS Control.

### Creating a New WLI JMS Control

You can create a new WLI JMS control and add it to your business process. To define a new WLI JMS control:

1. Click Add on the Controls tab to display a list of controls that represent the resources with which your business process can interact.

Note: If the Controls tab is not visible in WebLogic Workshop, click View —> Windows —> Data Palette from the menu bar.

2. Choose Integration Controls to display the list of controls used for integrating applications.

3. Choose WLI JMS to display the Insert Control - WLI JMS dialog
4. In Step 1, in the Variable name for this control field, enter the name for your JMS control.
5. In Step 2, select the Create a new WLI JMS control to use radio button.
6. In the New JCX name field, enter the name of the new file.
7. Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
8. In Step 3, from the Message type drop-down list, select the type of message you want to process. For more information about the types of messages, see Specifying the Format of The Message Body.
9. From the JMS send destination type drop-down list, select either Queue or Topic, depending on the kind of messaging service you will be connecting to. For more information about messaging services, see Overview: Messaging Systems and JMS.
10. In the send-jndi-name field, type the name of the queue or topic that will send messages. If you do not know the name, click Browse and choose from the available list. You must specify the name of the send queue if the control is to be used to send messages.
11. From the JMS receive destination type drop-down list, select either Queue or Topic, depending on the kind of messaging service you will be connecting to. For more information about messaging services, see Overview: Messaging Systems and JMS.
12. In the receive-jndi-name field, type the name of the queue or topic that will receive messages. If you do not know the name, click Browse and choose from the available list. You must specify the name of the receive queue if the control is to be used to receive messages.
13. In the connection-factory field, type the name of the connection factory to create connections to the queue or topic. If you do not know the name, click Browse and choose from the available list.
14. Click Create. Alternatively, you may create a WLI JMS control JCX file manually. For example, you may copy an existing WLI JMS control JCX file and modify the copy.

### WLI JMS Control Methods

To learn about the methods available on the WLI JMS control, see the WliJMSControl Interface.

#### The JCX File for a WLI JMS Control

When you create a new WLI JMS control, you create a new JCX file in your project. The following is an example JCX file:

    package FunctionDemo;

    import com.bea.control.*;
    import com.bea.xml.*;
    import java.io.Serializable;

    /**
     *   @jc:jms send-type="queue" send-jndi-name="myqueue.async.request"
     *   receive-type="queue" receive-jndi-name="myqueue.async.response"
     *   connection-factory-jndi-name="weblogic.jws.jms.QueueConnFactory"
     */
    public interface SimpleQueueControl extends
     WliJMSControl,com.bea.control.ControlExtension
    {
        /**
         * this method will send a javax.jms.TextMessage to send-jndi-name
         */
        public void sendTextMessage(XmlObject payload);
        /**
         * this method will send a javax.jms.TextMessage to send-jndi-name
         */
        public void sendAnotherTextMessage(String payload);

        /**
         * If your control specifies receive-jndi-name,
         * that is your process expects to receive messages
         * from this control, you will need to implement callback handlers.
         */
        interface Callback extends WliJMSControl.Callback
        {
            /**
             * Define only 1 callback method here.
             *
             * This method defines a callback that can handle
             * text messages from receive-jndi-name
             */
            public void receiveTextMessage(XmlObject payload);
        }
    }

The JCX file contains the declaration of a Java interface with the name specified in the dialog. The interface extends the control base interface. Invoking any method in the JCX interface, other than the callback, results in a JMS message being sent to the specified queue or topic.

The contents of the WLI JMS control's JCX file depend on the selections made in the Insert WLI JMS dialog. The example above was generated in response to selection of Text/XML Bean as the Message type drop-down list.

#### Configuring the Properties of a JMS Control

Most aspects of a WLI JMS control can be configured from the Properties Editor in Design View. These properties are encoded in the JMS control's JCX file as attributes of the @jc:jms annotation. To retrieve current parameter settings, use the getControlProperties() method. (Note that this is a different method from the getProperties() method on the base JMS control which is used to get the JMS properties of the last message received.)

For detailed information on the @jc:jms annotation and its attributes, see @jc:jms Annotation.

You can also use the ControlContext interface for access to a control's properties at run time and for handling control events. Property values set by a developer who is using the control are stored as annotations on the control's declaration in a JWS, JSP, or JPD file, or as annotations on its interface, callback, or method declarations in a JCX file.

To learn how to create, configure and register JMS queues, topics and connection factories, see Programming WebLogic JMS at the following URL:

http://edocs.bea.com/wls/docs81/jms/index.html

Two queues are configured when WebLogic Workshop is installed, in order to support WLI 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 WLI JMS control deployed on a server should listen on a unique queue. If multiple WLI JMS controls on the same server are simultaneously listening on the same queue, the results may be unpredictable. See the WLI JMS Control Caveats section below for more information.

### Specifying the Format of The Message Body

Within a WLI 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 WLI JMS control can send the JMS message types TextMessage, ObjectMessage, BytesMessage, and JMSMessage. The WLI JMS control dynamically determines which type of message to send based on the configuration of the WLI JMS control method that was called. XML Object and XML typed variables use the text/XMLBean message type.

Note: You can send or receive any message type through send and receive methods that take a javax.jms.Message argument. (All message types extend javax.jms.Message.) To send an ObjectMessage, for example, call myControl.getSession() to get the JMS session, then call session.createObjectMessage(), and then send the message.

If the WLI JMS control method takes a single String or XMLObject argument, a javax.jms.TextMessage is sent.

If the WLI JMS control method takes a single argument of type java.lang.Object, a javax.jms.ObjectMessage is sent.

If the WLI JMS control method takes a single argument of type javax.jms.BytesMessage, a javax.jms.BytesMessage is sent.

If the WLI JMS control method takes a single argument of type javax.jms.Message, a JMS Message object is sent directly.

### Specifying Message Headers and Properties

To edit the parameter list controlling the message headers and message properties, display the control in the Design view, select a method, and edit the parameters using the Property Editor pane. You can set parameters programatically using the setProperties() method. To display current parameter settings, use the getControlProperties() method.

You can send additional properties using key-values pairs, using the annotation @jc:jms-property for each pair. You can also edit the parameters directly in the Source view.

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

### WLI JMS Control Caveats

Bear in mind the following caveats when you work with WLI 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 WLI JMS control and will violate this caveat.
- You may have only one callback defined for any WLI JMS control instance (receiveTextMessage, receiveBytesMessage, receiveObjectMessage or receiveJMSMesage, or a developer-defined callback).
- Note the difference between the getControlProperties() method used to get WLI JMS control properties and the getProperties() method on the base JMS control which is used to get the JMS properties of the last message received.
- If the underlying WLI 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 WLI JMS control infrastructure will continue attempting to process the message (unsuccessfully) forever. For information on setting the redelivery limit, see the"Programming WebLogic JMS at http://edocs.bea.com/wls/docs81/jms/index.html.

Related Topics

Overview: Messaging Systems and JMS

WLI JMS Control Interface

@jc:jms-headers Annotation

@jc:jms-property Annotation