WebSphere Message Broker, Version 8.0.0.7 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Changes in behavior in message maps converted from legacy message maps

From WebSphere® Message Broker Version 8 onwards, you transform data graphically by using a message map. These maps are managed through the Graphical Data Mapping editor. You define your transformation logic by using XPath 2.0 expressions. You can also call Java methods, ESQL procedures, or complex XPath expressions by using specialized transforms such as the Custom Java, Custom XPath, or Custom ESQL transforms.

Behavior changes during the development phase

Nulls behavior

When you convert a legacy message map that includes handling for nilled elements, check how a message map handles NULL values. For more information, see Handling nulls in graphical data maps.

  • In ESQL, a special NULL value is defined, and is distinct from empty. When you assign NULL to a named element, or set the element from the returned NULL value of a called ESQL function, you delete the element from the tree.

    In a message map, the ESQL NULL produces an empty element, or an empty element with the xsi:nil attribute set when the element is defined as nillable in the model. Consequently, in some cases the output of the map might include unexpected empty elements that can cause processing problems, including XML schema validation violations. Such problems typically occur when an ESQL user-defined function that returns ESQL NULL in some conditions is called. To avoid these problems, add a condition to the Custom Transform to prevent it from being invoked if it would return NULL.

Mapping from missing inputs

In an ESQL-based legacy message map, writing a NULL to an output element does not create the element. When a legacy message map runs certain transforms, and the input data is missing, the input is set as NULL and hence no output element is created. In the converted message map, these cases can produce an empty output element:
  • For transforms that are completely self-defined, such as Move, and if the input and output elements are defined as optional (minOccurs=0), the converted message map handles the missing input element, and no output element is created.
  • If the output element is defined as mandatory, the element is created in order to conform to the schema model.
  • For transforms that are internally defined to produce some output value even if the input element is missing (such as Custom ESQL, Custom Java, or Submap), the converted message map cannot automatically handle the missing input element. In this situation, you can add a condition such as fn:exists($input) to prevent these transforms producing the empty output element.

Assigning literal values to output elements

Use the Assign transform to set literal values in output elements. The Assign transform uses a string representation, which is assigned to the relevant output element and so must be formatted according to its type. The property value does not need to be in quotation marks, as any quotation marks would be passed as part of the string value. To provide an explicitly typed value, use the xs:<type> Cast transform with no input wiring.

Literals in conditional expressions

You could build expressions in the legacy message mapping editor that implied a type cast and used the underlying string value representation.

The Graphical Data Mapping editor uses XPath expression syntax and enforces strict typing. For example, testing a Boolean-typed element for the string literal value true would cause a type exception.

You can use the xs:<type> functions in your expressions to avoid these incorrect typing issues.

Java methods in conditional expressions

A legacy message map allows the use of Java methods with MbElement parameters types. The Graphical Data Mapping editor uses standard XPath expression execution and can only support Java methods with standard Java parameter types; see Configuring conditional mappings.

Complex type text values in condition expression

A legacy message map does not require the user to be explicit when accessing mixed content text values from a complex type element in a condition expression.

The Graphical Data Mapping editor is based on standard XPath syntax, and requires the explicit use of /text() to signify that the mixed content text value is to be used. As a result, a converted map with a conditional expression that referenced mixed content text values might fail until the path expression is extended to add the missing /text().

Literals in submap calls

The legacy message map editor did not correctly validate the typing of submap inputs. Users could edit the normal element path value of a submap input, and instead provide an untyped literal value.

The Graphical Data Mapping editor requires that all submap inputs are wired to an appropriately typed input element.

"For each index" counter variables

Some transformations require the use of the "For each index" counter value. The WebSphere Message Broker Version 6.1 and WebSphere Message Broker Version 7 message map provided the msgmap:occurrence function to obtain the current loop count. The Graphical Data Mapping editor provides a For loop counter variable which can be used to provide equivalent function. The name of this variable is fixed format $<For each primary input element name>-index can be obtained using content assist ctrl-space in the relevant "ForEach transform" Filter properties expression panel, or in the content assist in any nested transforms.

Behavior changes during the deployment phase

From WebSphere Message Broker Version 8 onwards, message maps can be deployed only as source. You must provide any of the following resources before deploying your solution:
  • For text and binary messages, you must provide the DFDL schema file or the message set that defines your input and output messages.
  • For XML messages, you must provide the XML schema files that define your input and output messages.

If your message is modeled in a message set, the message map requires the message set schema (.xsdzip file) to be deployed to run your message map. If your existing message set is used for text and binary formats only, you can deploy your message map with only a .dictionary file in the integration node archive (BAR). In this case, you must modify the message set to additionally set the XMLNSC domain support option, so it is added to a BAR with both a .dictionary file and .xsdzip file. If this option is not set, a warning is displayed in the Problems view, along with a quick fix action.

Behavior changes at run time

  • From WebSphere Message Broker Version 8 onwards, the Graphical Data Mapping editor has a dedicated Java™ based run time. As a result, map execution benefits from full support for XPath 2.0 and Java JIT optimization, which offers increased reliability.
  • A message map can be invoked only from a Mapping node.
  • A submap can be invoked only from a top level message map, that is, a map consumed by a Mapping node.

  • The message map runs in the Java virtual machine of the integration node. You must ensure that the integration node is configured correctly. For more information, see Setting the JVM heap size.
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2016Copyright IBM Corporation 1999, 2016.

        
        Last updated:
        
        Last updated: 2016-05-23 14:48:27


Concept topicConcept topic | Version 8.0.0.7 | br40815_