Manipulating JMS Message Headers and Message Properties in 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 JMS message headers and message properties on 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 the XML format of the message body, see Sending and Receiving XML Messages with a JMS Control.

# XML Messages and JMS Controls

A JMS control can send and receive text messages, XML messages, object messages or javax.jms.Message objects. While XML maps may be used to specify the message body only in JMS controls with message type "XML Map", XML maps may be used to control the message headers and message properties on JMS controls of any message type (Text, XML Map, Object or JMS Message).

Note: Due to a bug in the JMS control, if you use XML Maps to specify message headers or properties the message type will always be forced to type Text. This problem will be addressed in a future release.

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 Why Use XML Maps?

# Accessing Message Headers with XML Maps

You may access the headers of messages sent and received using the JMS control by using the @jws:jms-header tag.

You may use XML maps on methods to add headers to outgoing messages, optionally substituting the values of parameters to the method in the header. You may also use XML maps on the JMS control's callback to extract headers from incoming messages and assign the extracted values to the callback's parameters.

The example below demonstrates use of the @jws:jms-header tag to set and extract message headers.

# Accessing Message Properties with XML Maps

You may access the properties of messages sent and received using the JMS control by using the @jws:jms-property tag.

You may use XML maps on methods to add properties to outgoing messages, optionally substituting the values of parameters to the method in the property. You may also use XML maps on the JMS control's callback to extract properties from incoming messages and assign the extracted values to the callback's parameters.

The example below demonstrates use of the @jws:jms-property tag to set and extract message properties.

# The Edit Maps and Interface Dialog

The Edit Maps and Interface Dialog allows you to customize the parameter list and associated XML maps for a JMS control method or callback. To display the Edit Maps and Interface Dialog, double-click on the map icon associated with the method or callback you wish to customize.

The map icon for a JMS control method is shown here:

The map icon for a JMS control callback is shown here:

The Edit Maps and Interface dialog for the JMS control contains three tabbed panes that allow you to edit the XML maps for the message body (setting the @jws:jms-message tag's XML map), the message headers (setting the @jws:jms-header tag's XML map) and the message properties (setting the @jws:jms-property tag's XML map).

The Property XML pane of the Edit Maps and Interface Dialog for a JMS control method is shown here:

# Example

The example below demonstrates setting and extracting both message headers and message properties as well as specifying the XML format of the message body:

    /**
     * @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>
         *     <requestingAccount>{accountID}</requestingAccount>
         *   </property>
         * ::
         *
         * @jws:jms-message xml-map::
         *   <personIdentifier type={idType}>
         *     <identifier>{personID}</identifier>
         *   </personIdentifier>
         * ::
         */
        public void sendID(int accountID, String personID, String idType);

        public static interface Callback extends JMSControl.Callback
        {
             /**
             * @jws::jms-header xml-map::
             *   <header>
             *     <command>{command}</command>
             *   </header>
             * ::
             *
             * @jws::jms-property xml-map::
             *   <property>
             *     <requestingAccount>{accountID}</requestingAccount>
             *   </property>
             * ::
             *
             * @jws:jms-message xml-map::
             *   <person>
             *     <firstname>{fname}</firstname>
             *     <lastname>{lname}</lastname>
             *   </person>
             * ::
             */
            public void onNameReply(String receivedCommand, int accountID, String fname, String lname);
        }
    }

The sendID method will send a message whose body is an XML document with a <personIdentifier> top-level element. The value of sendID's personID parameter is substituted as the value of the <identifier> element. The personIdentifier element will also include an attribute type whose value is that of the idType method parameter.

The message will include a message header named command with the (hard-coded) value GetPerson. The message will also include a message property named requestingAccount, whose value will be the that of sendID's accountID parameter.

When a message is received by this JMS control, the onNameReply callback will be invoked. If the incoming message includes a header named command, the value of the header will be assigned to the receivedCommand parameter of onNameReply. If the incoming message contains a property named requestingAccount, the value of that property will be assigned to the accountID parameter of onNameReply. The values of the <firstname> and <lastname> elements in the message body will be assigned to the fname and lname parameters of onNameReply. Then onNameReply will be invoked with the newly assigned parameters.

Related Topics

Overview: Messaging Systems and JMS

SimpleJMS.jws Sample

CustomJMSClient.jws Sample

@jws:jms Tag

@jws:jms-message Tag

@jws:jms-header Tag

@jws:jms-property Tag