Just as with XML maps you create, ECMAScript you write for mapping acts as a translation layer. For example, in a map designed to translate an incoming XML message to Java, you can include a reference to a script function that is designed to do a calculation, separate or combine pieces of data, and so on. Some tasks, such as calculations, can't be done in XML maps without script. And sometimes the shape of the XML message differs so dramatically from the shape suggested by the Java declaration that there is no easy way to map them except by enhancing the map with script.
You store an ECMAScript function for mapping in a JSX file. From your XML map you point to the function. A map with a reference to a script function might look like this example:
A script function for mapping is designed to map an incoming XML message to Java or to map Java to outgoing XML—but not both. The function referred to by this example maps XML to Java. In fact, the function's actual name (in the JSX file) is convertOrderFromXML. At run time, WebLogic Server invokes the function when translating data from XML. Here is what the function's actual declaration looks like:
Notice anything unusual? You probably noticed that the single xml parameter in this function declaration doesn't match the items in parenthesis (currentOrder and currentCustomer) in the convertOrder example above. In the example, the items in parenthesis tell WebLogic Server which parts of the Java declaration the script should handle; currentOrder and currentCustomer are parameters of the Java method to which this XML map applies. If this map were designed to handle the method's return value—say, to map it to an outgoing XML message—the item in the parenthesis would simply be return. The function itself is more straightforward:
If this is a little confusing, the following diagrams might help. The first one shows mapping for parameters of a method in a web service; the second show mapping for the method's return value. In the first, XML is translated to Java; in the second, Java is translated to XML.