Sending and Receiving XML Messages with a JMS Control

This topic describes how to use XML maps to translate between the Java objects that are method and callback parameters in the JMS control's interface and the body of messages sent and received by the control.

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

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

To learn how to manipulate message headers and message properties (as opposed to the message body), see Manipulating JMS Message Headers and Message Properties in a JMS Control.

# XML Messages and JMS Controls

A JMS control can send and receive one of text messages, XML messages, object messages or javax.jms.Message objects. If you create the JMS control using the Add JMS Control Dialog, the JMS control's CTRL file will contain the appropriate code to send and receive messages of the type selected from the Message type drop-down list in the Add JMS Control dialog.

If the JMS control is configured with the XML Map message type, the JMS control converts between the Java types in the control’s method interface and XML messages using XML maps that you specify.

XML maps are used throughout WebLogic Workshop to convert XML messages to Java objects and vice versa. To learn about general XML map concepts, see How Do XML Maps Work?

# Specifying XML Maps for JMS Control Methods and Callbacks

You may specify the XML maps that are used to control the message body, message headers and message properties using the Edit Maps and Interface dialog. To learn how to display and use the Edit Maps and Interface dialog, see The Edit Maps and Interface Dialog.

## Example

The example below is the CTRL file generated if you select XML Map from the Message type drop-down list in the Add JMS Control dialog (instructional comments have been removed from the generated code for brevity):

    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="cg.jms.QueueConnectionFactory"
     */
    public interface SimpleXMLMapControl extends JMSControl
    {
        /**
         * @jws:jms-message xml-map::
         * <YourOuterTag>
         *   <SampleParameter1>{param1}</SampleParameter1>
         *   <SampleParameter2>{param2}</SampleParameter2>
         * </YourOuterTag>::
         */
        public void sendMessage(String param1, String param2);

       interface Callback extends JMSControl.Callback
        {
            /**
             * @jws:jms-message xml-map::
             * <YourOuterTag>
             *   <SampleParameter1>{param1}</SampleParameter1>
             *   <SampleParameter2>{param2}</SampleParameter2>
             * </YourOuterTag>
             * ::
             */
             public void receiveMessage(String param1, String param2);
        }
    }

The generated code contains a method named sendMessage and a callback named receiveMessage. JMS controls that pass XML messages may define one or more methods of any name and signature. So you may change the name of the generated method and add other methods to the generated interface. You should replace the existing parameter list (param1, param2) with whatever parameter list you require, then refer to the parameters in the XML map.

JMS controls may also define a single callback of any name and signature. You may change the name and signature of the generated callback.

The example above shows XML maps applied to the message body, using the @jws:jms-message tag; the message body may be manipulated with XML maps only if the JMS control was created with the XML Map message type.

To learn how to manipulate the XML message format, see Sending and Receiving XML Messages with a JMS Control.

XML maps may also be used to control the message headers (using the @jws:jms-header tag) and message properties (using the @jms:jws-property tag) on JMS controls of any message type (Text, XML Map, Object or JMS Message). To learn how to manipulate message headers and message properties, see Manipulating JMS Message Headers and Message Properties in a JMS Control.

## Example of Customized XML Map JMS Control

The following is an example of a JMS control that defines a sendID method and an onNameReply callback:

    /**
     * @jws:jms type="queue"
     *          send-jndi-name="OutQueue"
     *          receive-jndi-name="InQueue"
     */
    public interface GetPersonControl extends JMSControl
    {
        /**

        * @jws::jms-header xml-map::

        *   <header>

        *     <command>GetPerson</command>

        *   </header>

        * ::

        *
         * @jws::jms-property xml-map::

        *   <property>

        *     <requesterID>123</requesterID>

        *   </property>

        * ::

        *

        * @jws:jms-message xml-map::
         *   <person>
         *     <identifier>{personID}</identifier>
         *   </person>
         * ::
         *
         */
        public void sendID(String personID);

        public static interface Callback extends JMSControl.Callback
        {
             /**
             * @jws:jms-message xml-map::
             *   <person>
             *     <firstname>{firstname}</firstname>
             *     <lastname>{lastname}</lastname>
             *   </person>::
             */
            public void onNameReply(String firstname, String lastname);
        }
    }

The sendID method sends a message to the queue named OutQueue.

The @jws:jms-header tag sets message headers in the outgoing message. This example includes a JMS message header named command with the hard-coded value GetPerson in the outgoing XML message. The outermost element of the XML map for @jws:jms-header must be <header>.

The @jws:jms-property tag sets message properties in the outgoing message. This example includes a JMS message property named requesterID with the hard-coded value 123 in the outgoing XML message. The outermost element of the XML map for @jws:jms-property must be <property>.

The @jws:jms-message tag formats the message body. The message body will consist of the XML document fragment defined by the XML map, with the indicated substitution.

There is an additional tag, @jws:jms-header, that can format message headers. All three of these tags work the same way.

The onNameReply callback uses an XML map defined with the @jws:jms-message tag to extract data from the incoming XML message and transfer it to the Java parameters of the callback.

To learn more about the @jws:jms-header tag, see @jws:jms-header Tag.

To learn more about the @jws:jms-property tag, see @jws:jms-property Tag.

To learn more about the @jws:jms-message tag, see @jws:jms-message Tag.

# Related Topics

Overview: Messaging Systems and JMS

Sending and Receiving XML Messages with a JMS Control

Manipulating JMS Message Headers and Message Properties in a JMS Control

SimpleJMS.jws Sample

CustomJMSClient.jws Sample

@jws:jms Tag