Introduction to XQuery Maps for Web Services

XQuery maps provide a way for you to reshape the XML messages that web services send or receive. You use an XQuery map as a kind of translation layer between a web service method or callback and the outside world (its client, or a resource). Applying an XQuery map allows you to change the shape of a message dictated by the WSDL into the shape you want to use in your java program.

Note: In previous versions of WebLogic Workshop, you did this kind of translation with an XML map. XML map functionality is deprecated as of WebLogic Platform 8.1; you should use XQuery maps for future development.

As you might imagine, an XQuery map indicates how data from one XML shape maps to the parts of another shape by using XQuery expressions. XQuery is a powerful syntax for specifying particular parts of an XML instance. At the simple end, XQuery is expressed in a simple, path-like syntax that may select (in the SQL sense) elements of a particular name. At the more complex end, XQuery supports expressions that declare variables, contain loop structures, and construct new XML shapes with the data they retrieve.

Note: Your XQuery map relies on the schema you compile by placing an XSD file in a schema project. Keep in mind that if you change the target namespace for a schema used by an XQuery map, you must also change the web service's xmlns property so that its values correspond to the new schema. Also, you will need to update any XQuery expressions that use the namespace so that they match as well.

You can get assistance creating an XQuery map by using the XQuery map dialog (although you can also type one manually). For more information, see How Do I: Add or Edit an XQuery Map with the XQuery Mapper Dialog?

When to Use an XQuery Map on a Web Service

You may want to apply an XQuery map if:

Web services you build with WebLogic Workshop communicate by sending and receiving XML messages. By default, WebLogic Server translates these messages to and from the types in your Java declaration according to a "natural" map—a format in which the parts of your Java declaration match the contents of the message.

In some cases, however, you may want to enable your service to receive or send messages that don't match—perhaps because you want your service to work well with a client or resource whose message format can not be changed. In these cases, mapping through XML maps and script provides a way to handle different message shapes without having to change your Java code.

There are two general cases in which you might want to provide your own maps:

You want to control the shape of the outgoing message, perhaps because the message's recipient requires a particular format.
You need to allow for a particular incoming XML message shape, and want to avoid changing your service's code.

For example, you might build a service that has appeal to a potential client whose XML message format is specific to their industry, but differs from what your service is designed to handle. You may want to make it easier for that client to use your service by handling their format rather than requiring them to conform to yours. By overriding natural mapping with your own XML map, you effectively create a translation layer that handles the format of their request messages while allowing your implementation code to remain unchanged.

More specifically, through XML maps you can:

Map specific XML element content and XML attribute values to Java method parameters and return values.
Handle more dramatic differences between natural mapping and required formats by diverting translation processing to a script or map that is external to your service method code.