How Do XML Maps Work?

XML maps and script act as a translation layer between your web service (JWS file) and the network that carries XML messages between your service and components with which it communicates. You create maps or script to tell WebLogic Server how types in your Java declaration correspond to the contents of the XML message. At run time WebLogic Server executes your map or script when it passes XML messages between your service and the network.

You can include an XML map in a JWS or CTRL file, immediately preceding the Java declaration with which it is intended to be used. You can also create an XML map or script in a separate file and reference it from an annotation preceding the declaration.

For a more detailed overview of what happens when a map or script executes, see Using Script Functions from XML Maps.

A given method or callback may have two XML maps: one to map parameter values and one to map return values — these are called the parameter-xml map and the return-xml map, respectively. For example, consider a method declaration such as the following:

    public String searchRequest(String productName, String serialNumber, int quantity)

The parameters in this declaration are serialNumber and quantity; the return type is a String. The default maps will look something like the following.

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

Notice in this example that the XML element and attribute names —<searchRequest>, <productName>, serialNumber, <return>, and so on — reflect what is in the method signature. Also, the method's parameters are enclosed in {} as substitutions to capture what will arrive in the message as actual values.

Note: While this map is stored in an annotation immediately preceding the declaration to which the map applies, you can also store the map in a separate XMLMAP file, then refer to it from the annotation in your JWS file. For more information about storing maps in a separate file, see Creating Reusable XML Maps.

This default parameter-xml map assumes that an XML message carrying an incoming method call will look like the following:

    <searchRequest>
        <productName serialNumber="12345">Widget</productName>
        <quantity>3</quantity>
    </searchRequest>

But imagine a case in which a client wants to use your service, but they are already committed to a different message format based on an agreement within their clients' industry. For example, a message from them might appear as follows:

    <queryData>
        <partName partID="12345">Widget</partName>
        <partQuantity>3</partQuantity>
    </queryData>

This is just the sort of situation that XML maps are designed to address. For the searchRequest method, you could design a map that resembled the XML format used by expected request messages. That map would substitute element content, attribute values, and the like with bracketed placeholders directing that content and those values to parameters of the method. An example of a parameter-xml map for the searchRequest method might appear as follows:

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

Because XML maps are designed according to the expected shape of an XML message, the process of creating an XML map always begins with an example XML document of the sort to be matched. For example, if the map is being created in keeping with a client's constraints for the shape of XML message, obtaining an example message from the client should be the first step.

Note: The root tags (such as the <searchRequest> 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.

# Maps in Source Code and Maps in Map Files

You can put XML maps you create in one of two places. First, they can be placed inline with your Java source code (for ease of editing). They can also be placed in a separate map file (for reusability).

When you put a map inline in Java source code, you use the Edit Maps and Interface dialog. The dialog puts the map you create immediately preceding the declaration for the method, callback, or callback handler to which the map applies. When put in this location, the map may only be used with the corresponding Java declaration. However, you may also find that putting the map preceding the declaration makes it easier to find and edit. For example, an XML map put with source code is readily available for editing with the Edit Maps and Interface dialog simply by double-clicking the corresponding map icon in Design View.

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

When creating a separate map file, you create a text file with an .xmlmap extension and put XML maps into it. Putting maps into a separate map file enables you to use that file as a common resource; it can be used with, for example, all of the methods, callbacks and callback handlers in a web service.

Note that the code providing map functionality is the same for an XML map in a map file as it is for a map in source code. In other words, you can create a map and put it with your Java source code, then later move it to a map file without making changes to the way the map works. Map code in a map file differs only in that it must be enclosed in an <xm:xml-map> tag that enables you to invoke it from source code.

For more specific information on map files, see Creating Reusable XML Maps.

Related Topics

Matching XML Shapes