Creating Reusable XML Maps

You can reuse XML maps by putting them into a map file, a file with an .xmlmap extension. While maps in map files function the same as those put into source code, map files have the added benefit of being available to multiple methods, callbacks and callback handlers, instead of just one. This means that you can reuse the maps in a map file from anywhere in your project, or from another project. In addition, by adding multiple maps to a map file, you can group related maps in separate map files.

Note: This topic describes the specific characteristics of XML map files. For more information about mapping tasks in general (which you can perform in both inline maps and map files), see How Do XML Maps Work?

Preparing to use a map file is a two-step process: creating the map file and invoking it from source code.

# Creating a Map File

As described in How Do I: Begin a Reusable XML Map?, you create a map file by adding a text file to you project and giving it an .xmlmap extension. The following example describes the contents of this file.

An XML map file must begin with the following <xm:map-file> tag. This indicates to WebLogic Workshop that maps are contained in the file; the tag also declares the "xm" prefix that delimits a namespace for map tags such as <xm:value>.

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

You may optionally follow the <xm:map-file> tag with the <xm:java-import> tag. Use the <xm:java-import> tag if the substitution directives in your maps will require Java classes not available in the scope of the method or callback that invokes the map. The following example imports the Date class and a user-defined class:

    <xm:java-import class="java.util.Date"/>
    <xm:java-import class="com.MyCompany.MyType"/>

The <xm:java-import> is similar to the Java import directive. However, note that you may use only fully-qualified class names in the class attribute — you may not use a * to import all classes in a package.

Each XML map in a map file is contained within <xm:xml-map> tags. The signature attribute of these tags defines the map's signature. This is not to be confused with the signature of a method or callback, although the two may be similar. An XML map's signature specifies the map's name. It is used when referring to the map and any parameters used by the map. The parameters correspond to substitution directives within the map itself. For example, to use the following map, you would invoke it as placeOrder, passing as data the parameter values of the method or callback from which you are invoking it. For more information on invoking a map in a map file, see the following section.

        <xm:xml-map signature="placeOrder(String serialNumber, int quantity)">
            <serialNumber>{serialNumber}</serialNumber>

            <quantity>{quantity}</quantity>
        </xm:xml-map>

You may put many of these XML maps into a single map file. Finally, an XML map file ends with the following </xm:map-file> tag:

    </xm:map-file>

# Invoking a Map in a Map File

You invoke a map in a map file through the <xm:use> tag or its syntax alternative (described at the end of this topic). The <xm:use> tag has one attribute, call, which is used to indicate the location of the map to invoke, as well as the values to pass as parameters.

In the following example, the partID and partQuantity parameters of the requestParts method are passed to a map called "placeOrder" (such as the map in the preceding example) that is in a map file called "CustomerRequests."

    /*

     * @jws:operation

     * @jws:parameter-xml xml-map::
     * <requestParts>
     *     {CustomerRequests.placeOrder(String partID, int partQuantity)}
     * </requestParts>
     * ::

    public void requestParts(String partID, int partQuantity)
    {...}

Note that the path to the map must be full enough to locate it. For example, if the map file were contained in parallel folder of a project called "CustomerMaps," and the project itself were called "OrderServices," the path used above might instead be:

    OrderServices.CustomerMaps.CustomerRequests.placeOrder(String partID, int partQuantity)

Related Topics

<xm:map-file> Tag

<xm:xml-map> Tag

<xm:java-import> Tag

<xm:use> Tag>