WebSphere

Service Invoke mediation primitive

Use the Service Invoke mediation primitive to call a service from inside a mediation flow. If the service returns a fault, you can retry the same service or call another service.

Introduction

The Service Invoke mediation primitive lets you call a service from inside a mediation flow, rather than waiting until the end of the mediation flow and using the callout mechanism. The input message is used to call the service and, if the call is successful, the response is used to create the output message. If the call is unsuccessful you can retry the same service, or call another service.

You can have multiple Service Invoke mediation primitives inside one mediation flow. Therefore, you can have a series of service calls. You can use the Service Invoke mediation primitive in a request or response mediation flow.

Generally, the initial service that the Service Invoke mediation primitive calls is defined by the reference operation, which is a combination of the Reference Name property and the Operation Name property. For a Service Invoke mediation primitive in a subflow, the reference is defined on the subflow and resolved to a reference in the parent flow when an instance of the subflow is created.

The Service Invoke mediation primitive has one input terminal (in) and multiple output terminals. There is a fail terminal (fail) for unmodeled faults, and one output terminal for each modeled fault. Modeled faults are those that are explicitly listed in a WSDL file, any other fault is an unmodeled fault. In addition, there is an output terminal (out) that maps to the WSDL response message and a timeout terminal (timeout), which is used for some types of asynchronous calls.

Details

The input and output terminals of the Service Invoke mediation primitive must reflect the reference operation in the following way:
  • The message type of the in terminal must match the request message type of the reference operation.
  • If there is a response message, the message type of the out terminal must match the response message type of the reference operation.
The in terminal uses the input message to call the service.
  • If the service call is successful, the out terminal propagates the updated message.
  • If the service call returns a modeled fault, the output terminal for that modeled fault, propagates the fault response message. No information is put in the failInfo element.
  • If the service call returns an unmodeled fault, the fail terminal propagates the original message together with any exception information. The exception information is stored in the failInfo element.
  • If an asynchronous call times out, the timeout terminal propagates the original message together with the timeout exception information. The timeout exception information is stored in the failInfo element. The timeout terminal is not used for calls that are asynchronous with callback, only for calls that are asynchronous with a deferred response.
Table 1. The terminals of the Service Invoke mediation primitive
Terminal type Terminal name Dynamic terminal?

See: Note 1.

Message type Terminal description
Input in No WSDL message type, for the request message of the operation. Receives the input message. The message (SMO) received at the input terminal is used to call the service. See: Note 2.
Output out Yes. WebSphere® Integration Developer defines one for the response message on the interface. WSDL message type, for the response message of the operation. Propagates the updated message. The result of the service call is used to make a new message (SMO) that is sent to this terminal. Used when the service call is successful. See: Note 3.
Output Defaults to modeled fault name. Yes. WebSphere Integration Developer defines one for each modeled fault on the interface. WSDL message type, for the fault message of the operation. Propagates the fault response message. No information is put in the failInfo element. Used when the relevant modeled fault is returned from the service call.
Output timeout No WSDL message type, for the request message of the operation. (Same as input terminal.) Propagates the original message together with the timeout exception information. The timeout exception information is stored in the failInfo element. Used when an asynchronous service call fails because of a timeout. The timeout terminal is not used for calls that are asynchronous with callback, only for calls that are asynchronous with a deferred response. See: Note 3.
Fail fail No WSDL message type, for the request message of the operation. (Same as input terminal.) Propagates the original message together with any exception information. The exception information is stored in the failInfo element. Used when an unmodeled fault is returned from the service call.
  1. The Service Invoke mediation primitive has a variable number of terminals, some of which are created for a specific reason. A dynamic terminal is a terminal that is created, for a specific reason. For example, a WSDL-defined fault causes a dynamic output terminal to be created.
  2. Service calls are defined by the operations specified in the WSDL. For example, you might have an operation called getCustomerDetails that calls a customer information service.
  3. This terminal does not exist if the operation is one-way.

Usage

You can use the Service Invoke mediation primitive to help control the service retry sequence. The retry sequence can be a combination of the following:
  • Re-send the initial request to the initial service.
  • Send the initial request to an alternate service.
  • Send a new request to the initial service.
  • Send a new request to an alternate service.
For more information on using the Service Invoke mediation primitive, see: Usage patterns.

Properties

Reference Name
The name of the service reference to be called. The reference name is associated with a WSDL interface. Initially, the reference name is set through a WebSphere Integration Developer dialog, and cannot be changed afterwards. You have to create a new Service Invoke mediation primitive to change the reference name.
For a Service Invoke mediation primitive in a subflow, the reference is defined on the subflow and resolved to a reference in the parent flow when an instance of the subflow is created.
Operation Name
The name of the service operation to be called. The operation name is associated with a WSDL operation. Initially, the Operation Name is set through a WebSphere Integration Developer dialog; and cannot be changed afterwards. You have to create a new Service Invoke mediation primitive to change the operation name.
Use Dynamic Endpoint if set in the message header
Determines whether the SMO header field Target, if present, should be used to override the service endpoint specified by the reference operation. You can use the Endpoint Lookup mediation primitive to set the Target field, or you can set the field yourself.
Note: the Endpoint Lookup mediation primitive searches for service information in a WebSphere Service Registry and Repository (WSRR), and only certain types of endpoint can be retrieved. For more information, see: Endpoint Lookup mediation primitive.
Async Timeout
The time to wait for a response, when a call is asynchronous with a deferred response. The Async Timeout property is not used for calls that are asynchronous with callback. If the Async Timeout is 0, there is no wait and the response is immediate. If the Async Timeout is -1, the wait is indefinite. When a timeout occurs the timeout terminal is fired. A timeout is treated as an unmodeled fault, with regard to retry.
Invocation Style
Determines whether the service is invoked synchronously or asynchronously. When the synchronous style is used, the service is performed under the same processing thread as the mediation flow. When the asynchronous style is used, a new processing thread is used when invoking the service. The asynchronous style allows the mediation flow to continue before a response is received from the service. The invocation style can affect the transactional scope that applies to the service invocation, and whether a timeout might occur if the service fails to respond.
If set to sync, the service invocation is performed synchronously. This setting can allow the service to be included in the transaction scope of the mediation flow when the service or binding supports this function.
Setting the property to async means that the service invocation is performed asynchronously, and the service is outside the scope of the mediation flow transaction. For a one way operation, a reference qualifier can be used to control whether the asynchronous service request is sent immediately, or when the mediation flow transaction commits. The async setting can also allow an async timeout to be set for a deferred response.
Setting the property to default means that the invocation style is determined by other factors such as the preferred interaction style of the target, or the invocation style used by the mediation module's export.
Table 2. Invocation style options, for default cases
How the mediation flow component is called Preferred interaction style of the target One-way or request-response Require mediation flow to wait for service response when the flow component is invoked asynchronously with callback Invocation style
invoke (synchronous) ANY One-way true or false Async
Request-response true or false Sync
SYNC Either true or false Sync
ASYNC Either true or false Async
invokeAsync (asynchronous with deferred response) ANY One-way true or false Async
Request-response true or false Sync
SYNC Either true or false Sync
ASYNC Either true or false Async
invokeAsyncWithCallback (asynchronous with callback) ANY One-way true or false Async
Request-response true Async
Request-response false AsyncWithCallback
SYNC Either true or false Sync
ASYNC One-way true or false Async
Request-response true Async
false AsyncWithCallback
Require mediation flow to wait for service response when the flow component is invoked asynchronously with callback
Set to true, (select the check box), to force a service call to act in a synchronous manner. If true, an asynchronous call causes a deferred response, rather than a callback. Set this property to true if the whole mediation flow is to run in a single transaction. If you set this property to false and the mediation primitive is involved in a FanOut/FanIn operation or is contained in a subflow, the run time will override your setting and force the service call to act in a synchronous manner.
Retry On
Determines whether, and how, fault responses cause a retry. The following values are valid: Never, Any fault, Unmodeled fault and Modeled fault. To enable retry, you must set the value of the Retry On property to: Any fault, Unmodeled fault or Modeled fault. Modeled faults are those that are explicitly listed in a WSDL file, any other fault is an unmodeled fault. This property is only applicable to request-response operations.
Retry Count
How many times a service call should be retried before an output terminal is fired. The output terminal that is fired can be of the following types: modeled fault, timeout or fail. The value can be zero or a positive integer.
Retry Delay
The delay (in seconds) between retry attempts. The value can be zero or a positive integer.
Try Alternate Endpoints
Determines if any alternate endpoints in the SMO should be used on retries. Set to true, (select the check box), to try alternate endpoints.
This functionality is only available if the Use Dynamic Endpoint is also specified. If any fault is returned by the initial service request, and the retry count is greater than zero, the first endpoint from the alternate endpoint list is used for the retry. If the retry returns a fault, and the next retry would not exceed the retry count, the next alternate endpoint is used. After the last endpoint in the alternate endpoints list is used, the initial endpoint is used again.

For example, suppose that the first endpoint is ServiceA, and the alternate endpoints are ServiceB and ServiceC. If the retry count is 5, the sequence of service calls is as follows: ServiceA, ServiceB, ServiceC, ServiceA, ServiceB, ServiceC.

Table 3. mediation primitive properties
Property Valid Values Default
Reference Name String  
Operation Name String  
Use Dynamic Endpoint if set in the message header Boolean: true or false true
Async Timeout Integer 5
Invocation Style String: Default, Sync or Async Default
Require mediation flow to wait for service response when the flow component is invoked asynchronously with callback Boolean: true or false false
Retry On String: Never or Any fault or Unmodeled fault or Modeled fault Never
Retry Count Integer 0
Retry Delay Integer 0
Try Alternate Endpoints Boolean: true or false true

Considerations

Consider the following when using the Service Invoke mediation primitive:


reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:40:03 BST (DRAFT)


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