Deprecated. XML Maps are deprecated as of the WebLogic Platform 8.1 release. For new code, use XQuery maps. For more information, see Introduction to XQuery Maps.

# 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. You can 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 section describes the four circumstances under which an outgoing XML message can leave from your web 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 the following targets:

- 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 JCX file that defines the control. Remember that the JCX 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 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 Web 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 JCX file that defines the control. Remember that the JCX 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. To learn more about the Edit Maps and Interface dialog, 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

JCX File: Extending Controls the topic titles linked to and from are different