How Do I: Begin a Reusable XML Map?

You can store XML map code in a file separate from your JWS or CTRL file. This enables you to call a map from code in multiple services and use a map in multiple projects. When creating an XML map file, you add a new file to your project, give it an .xmlmap extension, and add code to make it a self-contained map file. To use a map in a XMLMAP file, you refer to it from within a parameter-xml or return-xml map using the <xm:use> map tag.

Note: Whenever possible, it is a good practice to create and debug an XML map with the Edit Maps and Interface dialog because it provides code completion and error checking. You can then remove the map to a separate file and enclose it with the tags needed to make it self-contained. For more information on the Edit Maps and Interface dialog, see How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog?

For more detailed information on what makes up an XML map file, see Creating Reusable Maps.

To Create an XMLMAP file

1. In Design View, choose File-->New File. The Create New File dialog appears.

2. Click Text.

3. In the File name field, type the name of the XMLMAP file.

Note: If this map file will contain multiple maps, you may want to give it a name that conveys a sense of the maps as a group, such as POMaps for maps that handle purchase orders.

4. In the File extension field, type xmlmap, which is the extension all XMLMAP files use.

5. Click OK. The new map file opens in Source View.

6. Enter the following at the top of the newly created empty map file:

    <xm:map-file xmlns:xm="http://www.bea.com/2002/04/xmlmap/">

This identifies the file as a map file.

7. After this line, begin a new map with code similar to the following, replacing text as described below:

        <xm:xml-map signature="mapName(datatype parameter)">
            ...text of the XML map...
       </xm:xml-map>
    </xm:map-file>

- mapName — Enter a name for this map that is unique in the context of this file. There may be multiple maps in the file, each with different names.

- datatype parameter — Enter parameters for this map's signature. Note that the parameter names specified in the map’s signature attribute do not need to match the parameter names of the method to which the map is being associated. However, the types of the parameters in the map signature and in the invocations of the map must agree in both type and order — in other words, the same rules apply as when making a method call.

For more information on constructing the text of an XML map, see How Do XML Maps Work? and Matching XML Shapes.

8. Enter additional maps as needed, enclosing each map between <xm:xml-map> tags as in the preceding steps.

9. End the map file with an </xm:map-file> tag.

Here is an example of code you might create with this procedure:

        <xm:map-file xmlns:xm="http://www.bea.com/2002/04/xmlmap/">
            <xm:xml-map signature="placeOrder(String partID, int quantity)">
                ... text of the XML map...
            </xm:xml-map>
        </xm:map-file>

To Refer to a Map in a XMLMAP File from Within an XML Map

1. Locate the source code for the method or callback that will use an XML map that is stored in the map file.

2. Immediately preceding the method's declaration, in the Javadoc comment containing attributes, enter the following, replacing sample text as described below:

    /*
     * @jws:mode-xml xml-map::
     *   <methodName>
     *     <xm:use call="MapFileName.mapName(datatype parameter)"/>
     *   </methodName>
     * ::
     */

- mode — This should be "parameter" or "return," depending on which sort of map this is.

- methodName — The name of the method or callback to which this map call applies. For example, if the method declaration following this annotation is public String reportRequest(String applicantSSN), methodName would be reportRequest.

- MapFileName — The name of the XMLMAP file you created. Note that it may be necessary to prepend path information, as described in Creating Reusable XML Maps.

- mapName — The name of the map to be used. This name corresponds to the mapName in the preceding procedure.

- datatype parameter — Parameters from the declaration of your method or callback if this is a parameter-xml map; if this is a return-xml map, the parameter here takes form: datatype return, where "return" is literal.

Here is an example of code to invoke a parameter-xml map:

        /*
         * @jws:parameter-xml xml-map::
         *   <methodName>
         *     <xm:use call="CustomerRequests.placeOrder(String)"/>
         *   </methodName>
         * ::
         */

Related Topics

Creating Reusable XML Maps

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