WebSphere

Fan Out mediation primitive

Use the Fan Out mediation primitive to create different messages from a repeating element in the input message. Also, use the Fan Out mediation primitive, together with the Fan In mediation primitive, to aggregate (combine) service responses.

Introduction

You can use the Fan Out mediation primitive to iterate through an input message that contains a repeating element, and store each instance of the repeating element in the service message object (SMO) context. The Fan Out mediation primitive does not change the body of the input message.

The Fan Out mediation primitive has the following modes:
  • Default mode sends the entire input message once.
  • Iterate mode lets you iterate through a single input message that contains a repeating element. Every occurrence in the repeating element, which you specify using an XPath, is processed.

The Fan Out mediation primitive has one input terminal (in), two output terminals (out and noOccurrences), and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message.

If an exception occurs during the processing of the input message, the fail terminal propagates the input message, together with any exception information.

In default mode, the out terminal is used to propagate the input message and the terminal is fired only once. In iterate mode, the out terminal is also used to propagate the input message, but the terminal is fired once for each occurrence of the repeating element. Each time the terminal is fired the value of the current element is placed in the FanOutContext. The noOccurrences terminal is only used in iterate mode, and is used if the input message does not contain any occurrences in the repeating element.

Details

When in iterate mode the out terminal is fired once for each occurrence of the repeating element that you specify, using an XPath expression. Each occurrence of the repeating element is stored in a FanOutContext field.

If you use a Fan Out mediation primitive followed by a Fan In mediation primitive, you can aggregate the responses from two or more service invocations; the group of mediation primitives that occur between a Fan Out and a Fan In is called an aggregation block. If an aggregation block contains Service Invoke mediation primitives on multiple branches, and the Service Invoke primitives are configured for asynchronous invocation, the service calls are processed in parallel. The parallel processing occurs in the following way: there is only one thread, but that thread makes all the service calls and then checks for the responses. You can configure when the responses are checked, using the Batch Count property.

Usage

You can use the Fan Out and Fan In mediation primitives to aggregate the responses from two service invocations into one output message. For example, you could retrieve a customer credit score from two credit agencies, then average the two scores.

The shared context area of the SMO is for storing aggregation data between a Fan Out primitive and a Fan In primitive. The shared context is a thread-based storage area that is shared in the same thread. The content of the shared context business object does not persist across a request flow and a response flow, through callout invocation. Whatever data is in the shared context of the request flow cannot be reused during the response flow. Therefore, you can only aggregate in a particular flow: a Fan In mediation primitive in a response flow cannot be used to aggregate messages from a Fan Out mediation primitive in a request flow.

Like the transient and correlation context, the shared context is defined as a user-provided business object on the input node of the mediation flow. After you have defined the shared context you can use it to store data during aggregation operations. You need to design the shared context business object carefully, to ensure it is suitable for all aggregation scenarios in a specific flow.

The Fan In primitive allows for the aggregation of data that results from the use of a Fan Out primitive. You can aggregate data by processing the shared context, using transformations or mappings in other mediation primitives.

Fan Out can be used on its own, or with the Fan In mediation primitive. After a Fan In primitive has been associated with a Fan Out primitive, its properties appear with the properties of the Fan Out primitive.
Note: The Fan In mediation primitive cannot be used without the Fan Out mediation primitive.

Properties

Once mode
The input message is propagated only once, from the out terminal, this is the default mode. Whatever the mode, the body of the input message is propagated unchanged.
Iterate mode: for each element in XPath expression
The iterate mode requires you to specify the XPath location of a repeating element in the input message.
XPath
When in iterate mode the out terminal is fired once for each occurrence of the repeating element that you specify, using an XPath expression. For example, if the body of the SMO contained the following repeating element /body/input/accounttype[], then an input message might contain the following account types: /body/input/accounttype[0]=gold and /body/input/accounttype[1]=platinum. If you set the XPath to /body/input/accounttype[], the out terminal would be fired twice: once with the FanOutContext containing gold and once with the FanOutContext containing platinum. If the input message does not contain any occurrences in the repeating element, the noOccurrences terminal is fired.
Batch Count
This property only applies to Fan Out mediations that are part of an aggregation. The purpose of this property is to control the rate at which asynchronous responses (for any asynchronous Service Invoke requests made in the aggregation block) are collected and processed.
Note: The value of this property does not affect the number of times the Fan Out will fire.

An integer of 0 equates to: Check for asynchronous responses after all messages have been fired. Therefore, the Fan Out mediation primitive fires all aggregation iterations before checking for any asynchronous service responses.

An integer of greater than 0 equates to: Check for asynchronous responses after {n} messages have been fired, where you can specify the value of {n}. This allows you to specify how many messages should be fired before asynchronous responses are handled. For example, a count of 1 would fire a single aggregation iteration and all resulting service responses would be received and processed before starting the next aggregation iteration (this is the default). The service responses would all be received before starting the next iteration. A count of 2 means there would be a maximum of two firings of the Fan Out output terminal before all service responses were collected. If the number of output terminal firings was not an exact multiple of 2 then any service responses resulting from the final firing would still be collected and processed as normal.

Table 1. Fan Out mediation primitive properties
Property Valid Values Default
once Boolean: true or false true
for each element in XPath expression XPath  
Batch Count Integer value of 0

Check for asynchronous responses after all messages have been fired

 
Integer value greater than 0

Check for asynchronous responses after {n} messages have been fired

 

Considerations

Consider the following when using the Fan Out mediation primitive:

Example of data aggregation

The following example shows two service calls being made and their responses being stored in the shared context. The shared context is then used to create a final message. The Fan Out mediation primitive is used in the default mode, and the Fan In mediation primitive has a Count property of 2. This is a simplified example, and does not show all the terminal wiring.
  1. FanOut1 fires the input terminal of XSLT1.
  2. XSLT1 creates the appropriate request message for Service A, and fires the input terminal of ServiceInvoke1.
  3. ServiceInvoke1 calls Service A, and fires the input terminal of XSLT3.
  4. XSLT3 maps the response from Service A into the shared context and fires the input terminal of FanIn1, for the first time.
  5. Because the FanIn1 count value has not been reached the mediation flow tracks back to the flow path split, at FanOut1.
  6. FanOut1 fires the input terminal of XSLT2.
  7. XSLT2 creates the appropriate request message for Service B, and fires the input terminal of ServiceInvoke2.
  8. ServiceInvoke2 calls Service B, and fires the input terminal of XSLT4.
  9. XSLT4 maps the response from Service B into the shared context and fires the input terminal of FanIn1 for the second time.
  10. The FanIn1 decision point is now met (the count value has been reached). Therefore, the FanIn1 primitive fires the input terminal of XSLT5.
  11. XSLT5 uses the shared context to create a new message body in the SMO.
Figure 1. Aggregating data using Fan Out, XSLT, Service Invoke and Fan In. The Fan Out mediation primitive is wired to two XSL Transformation (XSLT) mediation primitives. Each XSLT mediation primitive is wired to a different Service Invoke, which calls a service. The Service Invokes are wired to different XSLT mediation primitives, and these are both wired to one Fan In mediation primitive. The Fan In waits until both service invocations have been completed before firing a final XSLT mediation primitive.
The figure shows how you can aggregate data using a Fan Out mediation primitive and a Fan In mediation primitive.

reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:39:56 BST (DRAFT)


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.wbit.help.medprim620.doc/ref/rwesb_FanOutmediationprimitive.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).
iDoc on