How Do I: Ensure that Outgoing XML Messages Conform to a Particular Shape?

When your service must generate a particular outgoing XML message shape, you can create an XML map as an translation layer between the specific Java types of your service's implementation and the corresponding outgoing message. XML maps are particularly useful in cases where a web service you develop must generate messages whose shape is beyond your control. Maps enable you to control the shape of those messages without changing the implementation of your class.

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

Depending on how the outgoing message leaves your service, you will create either a parameter-xml map or a return-xml map. The following lists the four circumstances under which an outgoing XML message can leave at your service, and describes which kind of map you should use for each.

Note: For each of the outgoing message sources described in this topic, there is a related incoming message source. For more information on mapping to handle incoming messages, see How Do I: Handle XML Messages of a Certain Shape?

An outgoing message can be sent:

- To a client as the returned response to a call to a method of your service.

Use a return-xml map on your web service's method. Here, you need to map data from your method's return value to the desired outgoing message shape.

- As a return value of a callback sent to your service by a control.

Use a return-xml map on the callback handler for the control's callback. When your service implements a callback handler to respond to a callback sent by a control (including another service), that handler may return a value you must map to the outgoing message.

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.

- As the call from your web service to a control's method.

Some control types allow you to specify XML maps to be applied to method calls to that control. This is most typically used with Service controls, which represent another web service.

Use a parameter-xml map on the control's method. When your service calls a method of another service, you must pass any needed parameter values with the method call. You can map the Java types of the parameters to the desired message shape.

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 a callback sent to a client.

Use a parameter-xml map on the callback. Given that this sort of callback (the kind sent from your service to clients) is an aspect of the interface your service defines, it is likely that you will control the message format, thus eliminating the need for an XML map. However, when the need arises you can map the Java types of your callback's parameters to a desired outgoing message shape.

The Edit Maps and Interface dialog provides a convenient 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: Handle XML Messages of a Certain Shape?

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

Using Callbacks to Notify Clients of Events