There are two kinds of maps you can create: parameter-xml and return-xml. As you might expect, you use a parameter-xml map when you want to map XML values to or from the parameters of a method, callback or callback handler; you use a return-xml map for the return values.
The following table describes where each kind of map is used.
Interface Member |
Direction of Message Travel |
Kind of Map to Use |
---|---|---|
Method of your service (JWS file) |
Incoming (from a client) |
parameter-xml |
|
Outgoing (toward a client) |
return-xml |
Callback of your service (JWS file) |
Incoming (from a client) |
return-xml |
|
Outgoing (toward a client) |
parameter-xml |
Method of a control (JCX file) |
Incoming (from the resource) |
return-xml |
|
Outgoing (toward the resource) |
parameter-xml |
Callback handler of your service (JWS file) |
Incoming (from the resource) |
parameter-xml |
|
Outgoing (toward the resource) |
return-xml |
For more information on handling incoming messages or shaping outgoing messages, see How Do I: Handle Incoming XML Messages of a Particular Shape? and How Do I: Ensure That Outgoing Messages Conform to a Particular Shape?
When mapping parameters with a parameter-xml map, you substitute parameter names for XML values. When mapping return values, you substitute the word return for XML values. The following example illustrates each; bold text indicates where substitutions occur.
For reference information, see @jws:parameter-xml Annotation and @jws:return-xml Annotation.
/** * @common:operation * @jws:parameter-xml xml-map:: * <getInventory> * <queryData> * <part>{serialNumber}</part> * </queryData> * </getInventory> * :: * @jws:return-xml xml-map:: * <getInventoryResponse> * <queryData> * <inventoryCount>{return}</inventoryCount> * </queryData> * </getInventoryReponse> * * :: */ public int getInventory(String serialNumber) {...}
Note: The root tags (such as the <queryData> tag in the preceding example) must be unique across maps within a given JWS file. Because of this, it is a good practice to place your map within tags whose names match your method name; after all, methods must also be unique.
How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog?