Why Use XML Maps?

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.

Note: To view the natural map for a Java declaration, open the web service in Design View, then double-click the method, callback, or callback handler whose map you want to see. In the Edit Maps and Interface dialog, with the Default option selected, you can view the natural map for either parameters or return value. If the XML messages sent and received by this member of your service will not match this format, then you will probably need to create a custom map with an XML map or script.

# What's the Difference Between Using an XML Map and Using Script?

XML maps and script used for mapping accomplish the same general goal, but maps do it more simply while script does it more powerfully. One rule of thumb might be to first consider using a map, creating one with the Edit Maps and Interface dialog, then incorporate script if it appears that the shape of the XML message differs too greatly from types in your Java declaration. Note that to use script, you must also be familiar with the ECMAScript language.

Because maps resemble the message to which they are mapping, working with maps can feel like a natural way to express how parts of your Java declaration correspond to the message format. Creating a map is a little like aligning two sections of a puzzle that have been put together independently.

In contrast, creating a script for mapping is more like cutting out a brand new puzzle based on a picture of what it should look like, then assembling the pieces into a completed whole. With the extension to the ECMAScript language provided with WebLogic Workshop (including the ability to handle XML as a native data type), you can construct outgoing XML messages from scratch or access incoming messages as you would other data structures. ECMAScript is capable of handling pretty much all of your mapping needs. If you are familiar with ECMAScript, there is no reason why you couldn't use script in every case.

# How Do I Get Started Creating an XML Map or Script?

One good way to start creating the map is to begin with the XML schema — or an example — of the message format your map will accommodate. Looking at the schema, identify the parts of the message that correspond to the parts of your Java declaration. (You can learn more about XML schema at Introduction to XML.) If you will be mapping from an incoming message, ask yourself which elements and attributes will contain data that will be needed by your Java code; if you are mapping to an outgoing message, decide how the data in your Java declaration that will be sent to recipients should be parsed into the structure of the XML message.

Once you have an understanding of how the message shape and your Java declaration correspond to one another, you are ready to begin creating an XML map. In practice, for simple needs, you may find it easiest to always begin an XML map with the Edit Maps and Interface dialog, as described in How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog? However, there are a couple of questions you should answer before setting out to make a map, especially as your web service's needs become more complex.

- Decide whether the map should be implemented inline with Java source code or as a standalone map file.

Storing your XML map inline with service class source code is convenient from an editing perspective; storing the map in a separate file makes it reusable with other methods, even other web services. For more information on implementing inline XML maps, see How Do I: Add or Edit an XML Map with the Edit Maps and Interface Dialog? For more information on creating standalone maps, see How Do I: Begin a Reusable XML Map?

- Decide whether it will be necessary to manipulate the shape of the XML message with script.

The differences between Java types in a given implementation and the shape of an XML message may be so dramatic that it is not possible to create a map without manipulating the shape of the XML with script. When your needs require that you manipulate the shape of XML messages, WebLogic Workshop provides extensions to the ECMAScript language through which you can manipulate XML documents as you would other data structures. For more information, see Using Script Functions From XML Maps.

Related Topics

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

Using Script Functions From XML Maps