Applying parameter-xml and return-xml Maps

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 (CTRL 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?

# Syntax for parameter-xml and return-xml Maps

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 Tag and @jws:return-xml Tag.

    /**
     * @jws: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.

Related Topics

How Do XML Maps Work?

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