How Do I: Handle Incoming XML Messages of a Particular Shape?

When your service must handle a particular incoming XML message shape, you can create an XML map as an translation layer between the incoming message and the Java parameters that your method expects. XML maps are particularly useful in cases where a web service you develop must respond to messages whose shape is beyond your control. Maps enable you to handle those messages without changing your code.

In the simplest example, you specify this mapping with substitution directive such as {} for the XML element value you want to map. In the following example, parameters in the declaration are mapped to element and attribute values.

    /**
     * @jws:operation
     * @jws:parameter-xml xml-map::
     *   <searchRequest>
     *     <partName partID="{serialNumber}">{productName}</partName>
     *     <number>{quantity}</number>
     *   </searchRequest>
     * ::
     */
    public String searchRequest (String productName, String serialNumber, int quantity)

Note: You will find an introduction to XML maps at Why Use XML Maps?

Depending on how the incoming message arrives at your service, you will create a map that converts an XML message into the parameters of your Java method. The following lists the four circumstances under which an incoming XML message can arrive at your service, and describes which kind of map you should use for each.

Note: For each of the incoming message source described in this topic, there is a related outgoing message source. For more information on mapping to shape outgoing messages, see How Do I: Ensure that Outgoing XML Messages Conform to a Particular Shape.

An incoming message can arrive:

- From a client as a call to a method of your service.

Use a parameter-xml map on your web service's method. You may want to map data in the incoming XML message to the Java types of your method's parameters.

- As a callback received from a control.

Use a parameter-xml map on the callback from your control. When your service implements a callback handler you need to map the XML input from that control into the parameters of the callback handler Java function.

Note: When you edit a map associated with a control, you are modifying the CTRL file that defines the control. Remember that the CTRL file may be used by other web services. If you wish to edit maps on a control without affecting other web services, you should create a new control that is not shared.

For more information about callbacks, see Using Callbacks to Notify Clients of Events.

- The return value of a method call to a control.

Use a return-xml map on the control method. When your service calls a method of a control, you may need to map the returned XML message to the Java return type.

Note: When you edit a map associated with a control, you are modifying the CTRL file that defines the control. Remember that the CTRL file may be used by other web services. If you wish to edit maps on a control without affecting other web services, you should create a new control that is not shared.

- As the return value of a callback on the client.

Use a return-xml map on a callback from your service to a client to map the XML return message from the call into the Java return value of the callback.

In practice, you apply an XML map in roughly the same way (using the same syntax and tags) regardless of the message's source. The Edit Maps and Interface dialog provides an easy way to begin an XML map.

For more information, see How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog?

Related Topics

Why Use XML Maps?

How Do I: Ensure That Outgoing XML Conforms to a Particular Shape?

How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog?

Using Callbacks to Notify Clients of Events